Bulk Data API Reference

Parquet-first edge gateway for bulk financial data. All endpoints stream ZSTD-compressed Parquet files — load directly into DuckDB, Pandas, or Polars.

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

{ "status": "ok", "ts": "2026-04-11T00:00:00.000Z" }

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

{ "snapshot": "snapshot_20260411", "last_updated": "2026-04-11T00:00:00Z", "tables": [...] }

{ "snapshot": "snapshot_20260411", "tables": [...], "upgrade_url": "/pricing" }

application/octet-stream — raw Parquet bytes

application/octet-stream — raw Parquet bytes

application/octet-stream — raw Parquet bytes

{ "period_days": 7, "total_calls": 1420, "error_rate": 0.012, "daily": [...], "table_breakdown": {...} }

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

Eight 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", "factor_scores", "earnings_signals"]
}

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.

Error Codes