Skip to content
TAO$188.36
BTC0.002929
MCap$2.22B
Vol$86.25M

API reference / Status

Readiness and freshness of the /api/v2 data source

GET/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 (adds data.chain: the node's finalized head and the source's lag behind it, read over RPC). Anything else is a 400 INVALID_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 reason source_not_configured: /api/v2 data routes answer 503 SOURCE_NOT_READY here, so show v2 as unavailable.

reasonstring · can be null

Why ready is 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_seconds past 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_seconds exceeds data.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:own that 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_check appears 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 older meta.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 not ready is 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_reason says 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_reason says 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_of instead.
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 when data_as_of is: unknown, never 0.

is_degradedboolean

True when lag_seconds exceeds degraded_after_seconds, or window is active now (its starts_at has passed and its ends_at has not): show a delayed-data banner. With lag_seconds null it follows window alone.

degraded_after_secondsinteger · unit seconds

The bound on lag_seconds past which is_degraded is true (this API's setting, 600 by default).

unavailable_reasonstring · can be null

Why lag_seconds is null: source_not_configured (no /api/v2 data source here; ready is false), not_applicable (the data is read where it is written, so there is no delay to measure), read_failed (the measurement failed; the rest of the status is served), not_measured (no update received yet since a restart). Null when lag_seconds is set. Clients must accept values not documented yet. New values may be added; treat unknown values as unavailable.

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 as lag_blocks). Null when either time is unknown.

unavailable_reasonstring · can be null

rpc_unavailable when the node could not be read within 3 s (every figure above is then null; the rest of the status is served). Null otherwise. Clients must accept values not documented yet. New values may be added; treat unknown values as unavailable.

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), slow public, max-age=300, stale-while-revalidate=600 (state that moves in minutes or days) or tip public, 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). Never immutable. no-store on 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-revalidate and stale-if-error; no-store with X-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, with X-BTAI-Stale-As-Of, Age (its seconds since then) and Warning: 110 - "Response is Stale", and Cache-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.