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 $VALUEIN_TOKEN" \    --output fact.parquet

# One company's rows only (10-digit CIK, .parquet suffix on partitions)curl https://data.valuein.biz/v1/pro/fact/0000320193.parquet \    -H "Authorization: Bearer $VALUEIN_TOKEN" \    --output aapl_fact.parquet

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

{  "plan":      "sp500",  "status":    "active",  "email":     "user@example.com",  "createdAt": "2026-04-11T00:00:00.000Z"}

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

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

{ "ok": true, "worker": "edge-gateway", "env": "production" }

{ "plan": "sp500", "status": "active", "email": "user@example.com", "createdAt": "2026-04-11T00:00:00.000Z" }

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

{ "snapshot": "snapshot_20260411", "tables": [...], "upgrade": "…" }

application/octet-stream — raw Parquet bytes

application/octet-stream — raw Parquet bytes

application/octet-stream — raw Parquet bytes

application/octet-stream — raw Parquet bytes

application/octet-stream — raw Parquet bytes

{ "url": "https://…", "expires_in": 3600 }

{ "version": "…", "plans": { "sample": {…}, "sp500": {…}, "pro": {…}, "full": {…} } }

{ "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.

# pip install duckdb requestsimport os import duckdbimport requests token = os.environ["VALUEIN_TOKEN"]  # your Bearer tokenurl   = "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

13 core tables ship on every tier. Pass any table name as the {table} path segment. Institutional adds 11 more (insider Forms 3/4/5/144, 13F/13D/13G holdings and Form ADV), listed below. See Parquet Schema Reference for full field definitions.

Paid-tier and Institutional tables

Not in the free sample. Institutional tables answer on /v1/full/ only; tables marked monolithic have no per-CIK partitions.

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_YYYYMMDD",  "last_updated": "YYYY-MM-DDTHH:MM:SSZ",  "tables": ["earnings_signals", "entity", "fact", "factor_scores",             "filing", "filing_registrant", "index_membership",             "industry_classification", "ratio", "references",             "restatement_events", "security", "standard_concept",             "stock_price", "taxonomy_guide"]}

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