Fetching Data & Pagination

Response formats (?format=)

Every endpoint that returns a row array can return it as CSV or TSV instead of a JSON envelope — straight into a spreadsheet or a dataframe with no parsing step. Pick the format from the format dropdown in any endpoint's Try it panel, or pass?format=csv on the request. CSV is ~2.1x smaller than the equivalent JSON, TSV ~2.3x.

csv and tsv require the Scale or Enterprise plan. format=json is the default and is available on every tier — existing requests are completely unchanged.

Because a flat file has nowhere to put the JSON envelope, those fields move to response headers:X-Total-Count, X-Limit, X-Offset, X-Interval,X-Row-Count and X-Format. All are CORS-exposed, so browser clients can read them. Nulls render as \N (ClickHouse's convention) — in pandas passna_values=["\\N"], or an unenriched value will read as the literal string.

Columns are the union of every row's keys, so a field present on only some rows (for example crypto, which appears on crypto and exchange markets only) is still a column, with \N on the rows that lack it. One combination is rejected with a 400rather than being silently reshaped: group_by_event=true on market metadata, which returns a nested event tree rather than a row array.

Order books work in CSV too. With includebook=true eachbids / asks ladder is written into its cell as compact JSON — nothing is lost (verified: 29,679 price levels in, 29,679 out) and one line turns it back into data:df["bids"] = df["bids"].apply(json.loads). Two things to know: a spreadsheet shows a wall of JSON in that column, so touchsize=true — which givesbest_bid_size / best_ask_size as plain numbers — is usually the better ask there; and CSV's size advantage largely disappears on book rows, because the ladder is JSON either way.

Pagination

Endpoints that return large result sets support limit and offset parameters. The default limit is 500 rows, with a maximum of 5,000 per request.

# Page 1
GET /v1/markets/{id}/snapshots?limit=500&offset=0

# Page 2
GET /v1/markets/{id}/snapshots?limit=500&offset=500

# Page 3
GET /v1/markets/{id}/snapshots?limit=500&offset=1000

Time-Range Filtering

Use from and to parameters to restrict results to a specific time window.

GET /v1/markets/{id}/snapshots?from=2026-03-10 14:00:00&to=2026-03-10 15:00:00

Filtering

Response Structure

Paginated responses include metadata to help you iterate through results:

{
  "market_id": "0x...",
  "total": 54000,      // Total matching rows
  "limit": 500,        // Current page size
  "offset": 0,         // Current offset
  "data": [...]        // Array of results
}