Readiness and freshness of the /api/v2 data source
https://api.bittensor.ai/api/v2/status- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Whether /api/v2 has its data source here.
Full description
Whether /api/v2 has its data source here (ready), the newest block it holds and how far that is behind wall clock (head.lag_seconds: the staleness signal; the source reads finalized blocks only, so there is no separate chain-tip figure), and per API family (surfaces) and dataset (stages) how far each is exact (exact_through, lag_blocks), plus the off-chain feeds' newest rows (offchain) and the EVM feeds' latest runs (feeds: per feed, when its last successful run ended, ok_at, and when its last run started, last_attempt_at; null on a source that does not report them).
stale flags, set by this API: the head when head.lag_seconds exceeds stale_after_seconds (300 s); a dataset when lag_blocks exceeds its grain's normal lag (stale_after_blocks: 150 blocks for block datasets, 8400 for day datasets, which update at UTC day ends) or it has no exact range; a family when any of its datasets is stale or missing.
A deployment without the source answers 200 with ready false, reason source_not_configured and every source member null: the /api/v2 data routes answer 503 SOURCE_NOT_READY there. Cached as tip (6 s).
read_delay, always served: how far behind the chain data this API serves is (data_as_of, lag_seconds; null with unavailable_reason when it cannot be measured, never a guessed 0), is_degraded (lag_seconds over degraded_after_seconds, 600 s, or a maintenance window active now) and window, the announced maintenance window active now or starting within 7 days (null when none). A failed measurement serves unavailable_reason read_failed, not an error.
include=chain adds data.chain: the chain's finalized head read from the node over RPC (height, hash, time) and how far the source trails it (lag_blocks, lag_seconds); an RPC failure or a read over 3 s serves it null with unavailable_reason rpc_unavailable (never a 5xx); reused 6 s. Errors are application/problem+json: INVALID_INCLUDE (400), UNKNOWN_PARAMETER (400), BAD_GATEWAY (502: the source's answer broke its contract), SOURCE_TIMEOUT / SERVICE_UNAVAILABLE (503: the source did not answer).
Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).
Query parameters
- includequery· string
chain(addsdata.chain: the node's finalized head and the source's lag behind it, read over RPC). Anything else is a 400INVALID_INCLUDE.
Response
data is an object with these fields. Amounts are integer strings in their base unit, and null means unknown, never zero (see Units and formats). meta.at names the block the answer was read at.
Readiness, the head's lag, and per family and dataset coverage.
- sourcestring
An opaque identifier of the data source /api/v2 reads (one value today,
live). New values may be added; show an unknown value as is (or generically).- readyboolean
True when this deployment has the source configured and it answered. False with
reasonsource_not_configured: /api/v2 data routes answer 503SOURCE_NOT_READYhere, so show v2 as unavailable.- reasonstring · can be null
Why
readyis false:source_not_configured. Null when ready. New values may be added; treat unknown values as unavailable.- stale_after_secondsinteger · unit seconds
The bound on
head.lag_secondspast which the head is stale (this API's setting, 300 by default).- headobject · can be null
The newest block the source holds; null when not ready.
4 fields in head
- heightinteger · unit block
Height of the newest block the source holds. The source reads finalized blocks only, so this is also the newest finalized block it knows: there is no separate chain-tip figure.
- timestring (date-time)
That block's timestamp, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- lag_secondsinteger · unit seconds
Wall clock minus that block's time, in seconds: the staleness signal. Finalization alone keeps it near 20-50 s (2-4 blocks); more means the source is behind the chain.
- staleboolean
True when
lag_secondsexceedsdata.stale_after_seconds: the data on every /api/v2 page is older than it should be.
- surfacesobject · can be null
Per API family (
chain,state,accounts,subnets,trades,portfolio,baskets,validators,leaderboard,evm, ...; an open set): the datasets it reads, its watermark and lag. Null when not ready.- stagesobject · can be null
Per dataset, keyed by its name (an opaque identifier; an open set, including sub-datasets such as
net:ownthat no family reads): its tip island, lag, grain and latest failure. Null when not ready.- offchainobject · can be null
The off-chain feeds' newest rows; null when not ready.
4 fields in offchain
- tao_usdobject · can be null
The TAO/USD feed; null before its first row.
2 fields in tao_usd
- lateststring (date-time) · can be null
Start of the newest TAO/USD row (a minute), RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- lag_secondsinteger · unit seconds
Wall clock minus
latest, in seconds.
- forexobject
The FX reference rates.
1 field in forex
- latest_daystring (date) · can be null
The newest day with reference rates (YYYY-MM-DD); null before the first load.
- Format: date, YYYY-MM-DD
- market_referenceobject · can be null
The market reference feed; null before its first row.
2 fields in market_reference
- lateststring (date-time) · can be null
Time of its newest row, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- sourcestring
The feed that row came from, e.g.
coingecko.
- labelsobject · can be null
The address labels; null before the first run.
4 fields in labels
- run_idinteger · unit id
Id of the newest label run.
- rowsinteger · unit count
Labels that run produced.
- finished_atstring (date-time) · can be null
When the run finished, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- copied_atstring (date-time) · can be null
When its labels were copied in for serving, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- feedsobject · can be null
Per off-chain EVM feed (an open set keyed by feed name; known today:
abi(verified contract ABIs),creation_map(contract creations),token_meta(token metadata);token_checkappears once it first runs; a feed that has never run is absent): when its last run started and when its last successful run ended. For alerting on a stalled or failing feed. Null when not ready, and when the source does not report feed runs (an oldermeta.data_version).- read_delayobject
How far behind the chain data this API serves is (
lag_seconds,is_degraded) and the announced maintenance window, if any. Served whether or notreadyis true.7 fields in read_delay
- data_as_ofstring (date-time) · can be null
When the newest chain data this API can serve was written, RFC 3339 UTC. Null when it cannot be measured;
unavailable_reasonsays why.- Format: date and time, ISO 8601 in UTC
- replica_replay_timestring (date-time) · can be null · deprecated
When the newest chain data this API can serve was written, RFC 3339 UTC. Null when it cannot be measured;
unavailable_reasonsays why. Deprecated: use data_as_of; sunset 2027-02-15.- Format: date and time, ISO 8601 in UTC
- Deprecated since 2026-11-10, removed after 2027-02-15. Use
data_as_ofinstead. - lag_secondsinteger · unit seconds · can be null
How far behind the chain data this API serves is, in whole seconds: now minus
data_as_of, measured where the data is read (never negative). Null exactly whendata_as_ofis: unknown, never 0.- is_degradedboolean
True when
lag_secondsexceedsdegraded_after_seconds, orwindowis active now (itsstarts_athas passed and itsends_athas not): show a delayed-data banner. Withlag_secondsnull it followswindowalone.- degraded_after_secondsinteger · unit seconds
The bound on
lag_secondspast whichis_degradedis true (this API's setting, 600 by default).- windowobject · can be null
The announced maintenance window active now, else the soonest one starting within 7 days, else null.
3 fields in window
- starts_atstring (date-time)
When the window starts, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- ends_atstring (date-time)
When the window ends, RFC 3339 UTC; always after
starts_at.- Format: date and time, ISO 8601 in UTC
- notestring
Short text for users about the window (at most 280 characters), e.g. what may be slow or unavailable during it.
- chainobject · can be null
Only with
include=chain(absent otherwise): the chain's finalized head read from the node over RPC and how far the source trails it.7 fields in chain
- sourcestring
Where the head was read:
rpc, the chain node. New values may be added; show an unknown value as is (or generically).- finalized_heightinteger · unit block · can be null
The node's finalized head (chain_getFinalizedHead's header number). Null with
unavailable_reason.- finalized_hashstring · can be null
That block's hash, 0x + 64 hex. Null with
unavailable_reason.- Format: 32-byte hex: 0x and 64 hex digits
- finalized_timestring (date-time) · can be null
That block's timestamp (Timestamp.Now), RFC 3339 UTC. Null with
unavailable_reason, or when the block states none.- Format: date and time, ISO 8601 in UTC
- lag_blocksinteger · unit blocks · can be null
finalized_height-head.height: blocks the source trails the chain's finalized head by; negative when the node is behind the source (served as measured, never clamped). Null when either head is unknown.- lag_secondsinteger · unit seconds · can be null
finalized_time-head.time, in whole seconds (signed aslag_blocks). Null when either time is unknown.
Response headers
10 headers: ETag, Cache-Control, CDN-Cache-Control, X-BTAI-Stale, X-BTAI-Stale-As-Of, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- ETag
Strong validator of this answer. Send it back as
If-None-Match: an unchanged answer is a 304 Not Modified without a body. A settled answer's validator leaves the chain head out, so it stays valid as the head moves.- Cache-Control
One of three classes: settled
public, max-age=3600, stale-while-revalidate=86400(pinned to a block that cannot move), slowpublic, max-age=300, stale-while-revalidate=600(state that moves in minutes or days) or tippublic, max-age=6, stale-while-revalidate=12(follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Neverimmutable.no-storeon an earlier answer served because the data source failed (X-BTAI-Stale).- CDN-Cache-Control
The same class for shared caches (RFC 9213; browsers ignore it): settled 24 h, slow 300 s, tip 6 s, each with
stale-while-revalidateandstale-if-error;no-storewithX-BTAI-Stale.- X-BTAI-Stale
Present only when the data source failed to answer (it timed out or was unavailable) and an earlier answer to the same request is served instead of a 503 (stale if error, RFC 5861). Then
if-error, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-Control: no-store: the answer is never kept as fresh, and a later request reads again. Prices and quotes are never served this way.- X-BTAI-Stale-As-Of
With
X-BTAI-Stale: when the earlier answer served was produced, an RFC 3339 UTC time (2026-10-21T12:00:00Z).- RateLimit-Policy
The tier's request quota of the current window (IETF draft), e.g.
"tier";q=600.- RateLimit
Requests left in the current window and the seconds until it resets (IETF draft), e.g.
"tier";r=597;t=42.- X-RateLimit-Limit
The tier's request quota of the current window.
- X-RateLimit-Remaining
Requests left in the current window.
- X-RateLimit-Reset
When the current window resets, Unix seconds.
Status codes
200 · 304 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503
304 Not Modified: the If-None-Match validator still matches; no body.
Error codes
The codes this endpoint can return. Each links to what it means and what to do.
From the API's published specification, version 1.165.0.