Skip to content
TAO$188.27
BTC0.002928
MCap$2.22B
Vol$86.25M

API reference / Subnets

A subnet's epoch: tempo, last and next epoch block, pending emission

GET/api/v2/subnets/{netuid}/epoch
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

Where one subnet is in its epoch cycle at the latest block, in one light call: epoch (tempo, last_step_height, blocks_since_last_step, as GET /subnets/{netuid}?include=state serves them in state.epoch, plus next_step_height = last_step_height + tempo, the block the next epoch is scheduled for, and blocks_until_next_step) and pending_emission (the alpha accumulated since the last epoch, paid at the next one, per recipient: state.pending_emission). Root (netuid 0) is served like any subnet; it runs no epochs, so its next epoch is null. Head only (no at). Cached for a block. Errors are application/problem+json: INVALID_NETUID, UNKNOWN_PARAMETER, SUBNET_NOT_FOUND (404: no subnet is registered in the slot), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Path parameters

netuidpath, required· integer · 0 to 65535

Subnet slot (0 = root).

Query parameters

includequery· string

Reserved for opt-in sections. This route defines none yet; the parameter is declared so that adding one later is additive for generated clients. Any value 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.

The subnet's epoch cycle and pending emission.

netuidinteger · unit id

Subnet slot (0 = root).

generationinteger · unit id · can be null

Opaque life id (the life's registration identifier), NOT a block height; use life_start_height for the first block. The subnet life occupying netuid at the head (as on GET /subnets/{netuid}; 0 for root). Null when not recorded.

life_start_heightinteger · unit block · can be null

The first block of the life generation names (GET /subnets/generations' start_height): use it, never generation, for heights, ages and dates. Null exactly when generation is null (root without a life, no subnet), or transiently when this API cannot read the lives. Root's generation 0 starts at 0.

is_current_lifeboolean · can be null

Whether generation is the slot's current life (true) or an ended one, re-registered since (false). Null exactly when generation is null, or transiently when this API cannot read the lives. Root's generation 0 is current.

epochobject

Tempo, the last epoch's block and the next scheduled one: GET /subnets/{netuid}?include=state's state.epoch plus next_step_height and blocks_until_next_step.

5 fields in epoch
tempointeger · unit blocks · can be null

SubtensorModule.Tempo: blocks per epoch. Null without an entry.

last_step_heightinteger · unit block · can be null

SubtensorModule.LastMechansimStepBlock: the block of the subnet's last epoch. Null without one.

blocks_since_last_stepinteger · unit blocks · can be null

meta.at height - last_step_height: blocks since the subnet's last epoch (so the two always add up to meta.at). Root has not stepped since dTAO and reads in the millions (4,266,411 on 2026-10-01). Null without a last step.

next_step_heightinteger · unit block · can be null

The block the subnet's next epoch is scheduled for: last_step_height + tempo (the chain runs a subnet's epoch once tempo blocks have passed since its last one). The chain can still run it a block or more later (when too many subnets are due in the same block) or earlier (an epoch the subnet owner triggers). Always after meta.at. Null for root (netuid 0, which runs no epochs), without tempo or last_step_height, with a tempo of 0, and when the subnet is past its scheduled epoch at meta.at (more than tempo blocks since the last one: that epoch was skipped or deferred, so the next block it runs at cannot be told from these members).

blocks_until_next_stepinteger · unit blocks · can be null

next_step_height - meta.at height: blocks until the next scheduled epoch, at least 1 (about 12 seconds a block). Null exactly when next_step_height is.

pending_emissionobject

Alpha accumulated since the last epoch, paid at the next one, per recipient: exactly GET /subnets/{netuid}?include=state's state.pending_emission.

3 fields in pending_emission
server_alpha_raostring · unit alpha_rao (÷1e9) · can be null

SubtensorModule.PendingServerEmission: the miners' share, in alpha rao. Null without one.

Format: whole number, as a string · on chain: u64
validator_alpha_raostring · unit alpha_rao (÷1e9) · can be null

SubtensorModule.PendingValidatorEmission: the validators' share, in alpha rao. Null without one.

Format: whole number, as a string · on chain: u64
owner_cut_alpha_raostring · unit alpha_rao (÷1e9) · can be null

SubtensorModule.PendingOwnerCut: the owner's cut, in alpha rao. Null without one.

Format: whole number, as a string · on chain: u64

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.