Download Data

Overview

The /v1/data/download endpoint returns time-limited signed URLs for Parquet files stored in Google Cloud Storage. Each file contains one hour of data for a single message type. Signed URLs expire after the requested duration (default 12 hours) and can be used directly with DuckDB, pandas, or any HTTP client.

Authentication requires an API key with datasets:read scope, passed via the X-API-Key header. Keys are scoped to specific feeds and date ranges.

Available Feeds

API Reference

Query Parameters

Constraints

• Maximum 7-day date range per request
• Maximum 200 files per response
• API key must be authorized for the requested feed
• Key date range restrictions are enforced (dates are clamped to the key's allowed range)

Response

{
  "feed": "kalshi",
  "from": "2026-02-15",
  "to": "2026-02-15",
  "type": null,
  "files": [
    {
      "path": "kalshi/crypto/2026-02-15/ticker_0000.parquet",
      "name": "ticker_0000.parquet",
      "type": "ticker",
      "hour": "0000",
      "bytes": 1234567,
      "signedUrl": "https://storage.googleapis.com/...",
      "expiresAt": "2026-02-16T00:00:00.000Z"
    }
  ],
  "expiresIn": "12h"
}

Error Responses

curl Examples

List available feeds:

curl -H "X-API-Key: $API_KEY" https://api.varshtat.com/v1/data/feeds

Get signed URLs for one day of Kalshi data:

curl -H "X-API-Key: $API_KEY" \
  "https://api.varshtat.com/v1/data/download?feed=kalshi&from=2026-02-15&to=2026-02-15"

Filter by message type:

curl -H "X-API-Key: $API_KEY" \
  "https://api.varshtat.com/v1/data/download?feed=kalshi&from=2026-02-15&to=2026-02-15&type=ticker"

Multi-day range with shorter URL expiry:

curl -H "X-API-Key: $API_KEY" \
  "https://api.varshtat.com/v1/data/download?feed=kalshi&from=2026-02-10&to=2026-02-15&expires=6h"

Download all files from a response:

curl -s -H "X-API-Key: $API_KEY" \
  "https://api.varshtat.com/v1/data/download?feed=kalshi&from=2026-02-15&to=2026-02-15" \
  | jq -r '.files[].signedUrl' \
  | xargs -n1 -P4 curl -O

DuckDB Examples

Query directly from a signed URL (no download needed):

SELECT * FROM read_parquet('https://storage.googleapis.com/...')
LIMIT 10;

Query downloaded files with a time filter:

SELECT * FROM read_parquet('ticker_*.parquet')
WHERE ts BETWEEN '2026-02-15 14:00:00' AND '2026-02-15 15:00:00';

Aggregate across hours:

SELECT
  date_trunc('hour', ts) AS hour,
  count(*) AS ticks,
  avg(yes_price) AS avg_price
FROM read_parquet('ticker_*.parquet')
GROUP BY 1 ORDER BY 1;

Python Example

import pandas as pd
import requests

API_KEY = "sk_live_..."
API_HOST = "https://api.varshtat.com"

resp = requests.get(
    f"{API_HOST}/v1/data/download",
    params={"feed": "kalshi", "from": "2026-02-15", "to": "2026-02-15"},
    headers={"X-API-Key": API_KEY},
)
files = resp.json()["files"]

dfs = [pd.read_parquet(f["signedUrl"]) for f in files]
df = pd.concat(dfs, ignore_index=True)
print(f"Loaded {len(df)} rows from {len(files)} files")

File Naming Convention

Parquet files follow the pattern {type}_{HHMM}.parquet:

• type — message type (ticker, trade, book, etc.)
• HHMM — UTC hour (0000, 0100, ... 2300)

For example, ticker_1430.parquet contains ticker data from 14:30–15:29 UTC. A full day of one message type produces up to 24 files.

Limits