Limits and batches

Every limit below is served as data by GET /v2/dql/catalogue. Read it from there rather than carrying a copy: these are what the platform runs on today, and a client that hard-codes them will be wrong on the day they change. The sentences here say what to do when you meet one.

Nothing is silently truncated. A request past a limit is refused with DQL_LIMIT or DQL_COMPLEXITY and the message states both your figure and the ceiling — because a short answer that looks complete is worse than a refusal.

What a query may be

limit	value	what it means
source_bytes	8,192	The longest query text accepted.
nodes	256	Nodes in the parsed query. A condition with dozens of clauses meets this before it meets anything else.
depth	24	How deeply the expression may nest.
quantifiers_and_aggregates	16	How many any, all, count, max, min and sum one query may hold together.
series_calls	32	How many series functions one query may call.
timeframes	3	How many different periods one query may read. Reading three is a heavy query; reading four is a different question asked twice.
window	500	The largest window a series function may ask for, in periods — sma(close, 500) is the longest average there is.
bars_per_atom	2,000	The most bars one series read may cost.
cost	10,000	What the whole query may cost. POST /v2/dql/parse returns a query’s cost without running it, so this can be seen before it is hit.
in_list	32	The longest in (…) list.
select	16	How many values one select may return.
order_by	4	How many keys one order by may have.
reference_targets	4	How many different listings ref(INSTRUMENT, expr [, VENUE]) may read in one query: distinct (instrument, venue) pairs, where ref(X, …) without a venue is the pair (X, the venue evaluated).
freshness_min	1 s	The shortest freshness bound a query may set. Below this you are asking about jitter, not about staleness.
freshness_max	7 d	The longest. Past it, stale stops meaning anything.
screen_limit	500	The largest page POST /v2/screen returns. Use page.next_cursor for the rest; the cursor pins the instant, so page two sees the world page one saw.
screen_sampled_rows	150,000	The stored rows the sampled series of one screen may read: selected listings × the window of each sampled field ÷ its retained granularity (a row a second; funding, a row per ten seconds). A 60-bar hourly series of a ticker field is 219,600 rows per listing. Narrow where, or read candles, which cost a row per bar.

What one request may ask for

limit	value	endpoint
snapshots_listings	500	POST /v2/snapshots — or every listing of a single venue, however many that is.
history_listings	100	POST /v2/snapshots/history.
history_rows_per_layer	2,000	POST /v2/snapshots/history, in interval and at modes.
history_raw_rows	100,000	POST /v2/snapshots/history, in raw mode, across every listing and layer together.
candles_listings	100	POST /v2/candles.
candles_per_listing	1,500	POST /v2/candles.
liquidations_listings	100	POST /v2/liquidations.
liquidations_per_listing	1,000	POST /v2/liquidations — the newest events of each listing; truncated says there were more.
liquidations_window	7 d	POST /v2/liquidations — the longest (from, to] one request reads. Without from, an hour.
settlements_listings	500	GET /v2/funding/settlements.
settlements_per_page	1,000	GET /v2/funding/settlements — rows of a page (500 by default); follow next_cursor for the rest.
books_listings	100	POST /v2/books.
book_depth	25	POST /v2/books — levels per side. A larger depth is clamped to this and the answer states what was applied.
stream_listings	500	GET /v2/stream — listings on one connection.
response_bytes	8,388,608	Any endpoint. A response that would be larger is refused rather than cut.

Plan limits are a different thing

The numbers above are the same for everyone: they are what one request may ask the platform to do at once. How far back you may look, how often you may ask, and how many streams you may hold are set by the plan, and are refused with PLAN_LIMIT or RATE_LIMITED instead. A 429 carries Retry-After.

The per-second limit is a token bucket

Each key has a bucket that holds up to its burst and is refilled at the plan’s sustained rate, in requests a second. A client that has been quiet may send a burst at once (an AI client’s three to five parallel calls), then is held to the sustained rate. The burst is 4 times the rate, and at least 10: Free is 2 a second sustained and a burst of 10, Mini 5 and 20. Both numbers are in GET /v2/plans (requests_per_second, requests_burst) and, for your own account, in limits of GET /v2/account.

When the bucket is empty the request is a 429 RATE_LIMITED with limit set to requests_per_second and a Retry-After of the seconds until a token is back. The other plan limits keep their own names in limit: requests_per_day, dql_per_minute (a bucket of its own, per minute) and stream_connections.

What one paid call costs

A call without a key can be paid for with x402 instead: USDC on Base, one payment per request, no account. The price is by the class of the endpoint and is the same for everyone. A paid call is answered as Pro answers it, for that one request. You pay for what we recorded, not for what we missed. It is on in production since 2026-10-02: a request without a key to one of these endpoints is answered 402 with the price. How it works.

class	price (USDC)	endpoint
agent_state	0.01	GET /v2/agent/state (per rule named)
archive	0.10	GET /v2/archive/{listing}/{layer}/{day} (per file: core)
candles	0.005	POST /v2/candles
history	0.02	POST /v2/snapshots/history
screen	0.01	POST /v2/screen
snapshots	0.005	POST /v2/snapshots
archive_top100	0.05	GET /v2/archive/{listing}/{layer}/{day} (per file: top-100)

attest is priced (0.05) and has no endpoint yet. GET /v2/stream, /v2/books, /v2/liquidations and the DQL helpers are not payable: they need a key.

On debyko.com

• Plans and pricing
• Perpetual futures data API