Concepts

Response format

The envelope every data route returns, the meta object, strict query parameters and the rules that hold on every route.

The envelope#

Every successful data answer is JSON in the same shape:

json

{
  "data": [ /* rows, or one object on a single-record route */ ],
  "meta": { "source": "okx", "status": "ok", "fetchedAt": "2026-01-01T00:00:00Z", "dataDate": "2025-12-31T00:00:00Z", "message": null },
  "next_cursor": null
}

data is an array of rows (a list route) or one object (a single-record route). The shape of a row is its JSON Schema.
meta says where the data came from and how fresh it is (below).
next_cursor is null on the last page and on routes without paging; otherwise pass it back unchanged as cursor (Pagination).

A few service routes differ: GET /v1/datasets and GET /v1/whoami return { "data": ... } only, and GET /healthz / GET /readyz return { "status": "ok" | "unavailable" }. Errors use their own envelope (Errors).

The `meta` object#

Field	Meaning
`source`	The one source of the rows, or `aggre` when they mix several.
`status`	`ok`, `stale` (our last read is older than the dataset's window) or `empty` (nothing matched, or nothing was ever read). Some families add other states, documented on their route.
`fetchedAt`	When Aggre last successfully read the source. `null` where nothing has been read yet.
`dataDate`	The newest data point returned. What it means per route (a bar's open time, a publisher's list date, the last read) is stated on the route.
`message`	A sentence the route wants you to see, or `null`. Where a dataset has a standing caveat (name lists are not a screening verdict; Congress trades are disclosed weeks late) it is here, on every response.

Routes add keys of their own (for example restricted, attribution, licenses on statutes; series on macro observations; dataset on filings). Ignore keys you do not know: fields are added over time and never removed or renamed (Versioning).

Strict query parameters#

An unknown or repeated query parameter is 400 invalid_request, never silently ignored. So is a value out of range, a malformed date, or a cursor from another route. This catches typos (limt=5) before they return the wrong rows; build your requests from the parameter lists in the reference.

Values and units#

Identifiers are strings. Measured values are JSON numbers. Money and on-chain amounts that need exact precision are decimal strings.
Time-series timestamps are Unix milliseconds in UTC (ts); times inside meta are RFC 3339. Calendar dates are YYYY-MM-DD. See Identifiers and values.
Units are explicit where a value is not obvious (unit, unit_multiplier); nothing is converted on the way in, so value × unit_multiplier is in unit.
A value a publisher leaves out is absent or null, never 0.

Headers#

Every response carries x-request-id; quote it when you report a problem. A 429 rate_limited also carries Retry-After.