Bulk Data API Reference

Authentication

Authenticated endpoints require a Bearer token in the Authorization header. Tokens are provisioned automatically when you subscribe via Stripe. The /v1/sample/* endpoints are always public — no token required.

$ curl https://data.valuein.biz/v1/sample/entity \
    --output entity.parquet

$ curl https://data.valuein.biz/v1/sp500/fact \
    -H "Authorization: Bearer YOUR_TOKEN" \
    --output fact.parquet

$ curl https://data.valuein.biz/v1/me \
    -H "Authorization: Bearer YOUR_TOKEN"

{
  "plan":   "sp500",
  "status": "active",
  "email":  "[email protected]"
}

Response Format

Data endpoints return raw Parquet bytes. The Content-Type is application/octet-stream. Files are ZSTD-compressed — DuckDB, Pandas, and Polars decompress automatically via read_parquet(). Non-data endpoints return application/json.

Plans

Your token's plan determines which bucket you can access. A higher plan grants access to all lower tiers as well.

Endpoints

8 endpoints across the gateway. Expand a row for its query parameters and an example response.

Python Example

Download a Parquet table and query it locally with DuckDB in under 10 lines.

import duckdb
import requests

token = "YOUR_TOKEN"
url   = "https://data.valuein.biz/v1/sp500/fact"

r = requests.get(url, headers={"Authorization": f"Bearer {token}"}, stream=True)
r.raise_for_status()

with open("fact.parquet", "wb") as f:
    for chunk in r.iter_content(chunk_size=8192):
        f.write(chunk)

conn = duckdb.connect()
df   = conn.execute(
    "SELECT * FROM read_parquet('fact.parquet') LIMIT 5"
).df()
print(df)

Available Tables

9 tables cover the full schema. Pass any table name as the {table} path segment. See Parquet Schema Reference for full field definitions.

Manifest Response

Call GET /v1/manifest to discover available tables and the current snapshot timestamp for your plan. Check this before downloading tables to detect updates.

{
  "snapshot":     "snapshot_20260411",
  "last_updated": "2026-04-11T00:00:00Z",
  "tables": ["entity", "security", "filing", "fact",
             "valuation", "taxonomy_guide",
             "index_membership", "references", "ratio"]
}

Rate Limits & Retries

Limits are per Bearer token and enforced at the Cloudflare edge. Every response includes the standard rate-limit headers — read them before retrying so your client never busy-waits.

X-RateLimit-Limit:     120
X-RateLimit-Remaining: 117
X-RateLimit-Reset:     1735680000
Retry-After:           42

curl with retry-aware streaming

# --retry honors Retry-After on 429 and exponentially backs off on 5xx.
# --retry-max-time bounds total elapsed time; --retry-connrefused covers
# the cold-start case after a cache eviction.
$ curl https://data.valuein.biz/v1/sp500/fact \
    -H "Authorization: Bearer $VALUEIN_TOKEN" \
    --retry 5 --retry-max-time 120 \
    --retry-connrefused \
    --output fact.parquet

Parquet responses are a single binary stream — no pagination, no cursor tokens. The gateway sets Content-Length on every data response so clients can show progress and pre-allocate buffers. For incremental reads, query the latest snapshot from /v1/manifest and download only when the timestamp changes.

Bulk Data API vs MCP Server vs Python SDK

Three channels, one Bearer token, same warehouse. Pick by access pattern.

Use the SDK first if you're writing Python — it wraps this API and the MCP server with sensible defaults. Use the raw Bulk Data API when you're in a non-Python stack or building a partner integration.

Error Codes