Skip to content
TAO$188.21
BTC0.002927
MCap$2.22B
Vol$86.25M

API reference / Subnets

Every life (generation) of every subnet slot

GET/api/v2/subnets/generations
Status
Stable
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

The subnet lifecycle registry: one row per life of a netuid slot (a netuid is reused; each registration starts a new life at its NetworkAdded block; its generation is the stored registration id candles and pools key on), every slot or only netuid. Each row has the life's generation_index (1, 2, ... within the slot), whether it is current, its start and end (block and time; end exclusive), why it ended (removed: a NetworkRemoved or a same-block kill of the key; superseded: the next registration with no removal on record, only before runtime v133), its first emission block, the owner coldkey at its start and end, the TAO locked to register it and the last identity it carried. A life ends at its NetworkRemoved block (else the next registration), so the slot's empty period is the gap to the next life's start_height. Always the head (no at); not paged. include=owner_changes (with netuid) adds each life's owner_changes: every owner coldkey / owner hotkey change inside it. Errors are application/problem+json: INVALID_NETUID, INVALID_INCLUDE, NETUID_REQUIRED (owner_changes without netuid), SUBNET_NOT_FOUND (404, the slot was never registered), UNKNOWN_PARAMETER, NOT_READY (503, the decoded chain events do not reach genesis yet), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Query parameters

netuidquery· integer · 0 to 65535

Only this slot's lives (0 = root). Omitted: every slot. Anything else is a 400 INVALID_NETUID.

includequery· string

owner_changes: add each life's owner_changes (every SubnetOwner / SubnetOwnerHotkey change inside it, oldest first). Needs netuid (else a 400 NETUID_REQUIRED). Anything else is a 400 INVALID_INCLUDE.

Response

data is a list of objects 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.

One row per life of every slot, or of netuid when given. Not paged.

netuidinteger · unit id

The subnet slot this life occupied (0 = root).

generation_indexinteger · unit count

Which life this is for its netuid slot, counting up by start height: 1 for the slot's first registration, 2 for the next, and so on (at least 1). A label next to generation, which stays the id.

generationinteger · unit id

Opaque life id (the life's registration identifier), NOT a block height; use life_start_height for the first block. This life's id. Candles and pools are keyed on it, and it is the generation of /subnets/{netuid}/candles. Often equal to start_height, but runtime v133 set the key retroactively, so a life alive then has an id later than its start_height (SN1: 1,497,824 for a life that began at 172,898); a life that ended before v133 without one uses its start_height.

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.

is_currentboolean

True for the life occupying the slot now (no end_height); at most one per netuid.

start_heightinteger · unit block

The life's first block: its NetworkAdded block (the registration).

start_timestring (date-time) · can be null

Timestamp of start_height, RFC 3339 UTC. Null when that block's time is not known.

Format: date and time, ISO 8601 in UTC
end_heightinteger · unit block · can be null

The block that ended the life, exclusive (the life's last block is end_height - 1): its NetworkRemoved block; with no removal on record, the next registration's block. Null while current. A removed life ends at its removal, not at the next registration: the gap up to the next life's start_height is the slot's empty period.

end_timestring (date-time) · can be null

Timestamp of end_height, RFC 3339 UTC. Null while current.

Format: date and time, ISO 8601 in UTC
end_reasonstring · can be null

Why the life ended. removed: a NetworkRemoved event, or a same-block kill of the slot's NetworkRegisteredAt key before a re-registration in that block. superseded: the next registration ended it with no removal on record, which can happen only before runtime v133 (block 1,404,224), before the key existed; netuid 21's first life is the likely case. Null while current. New values may be added; treat unknown values as unavailable.

first_emission_heightinteger · unit block · can be null

FirstEmissionBlockNumber as stored during this life: the block its emission started. Null if it never started in this life.

owner_at_startstring · can be null

The subnet owner coldkey (SubtensorModule.SubnetOwner) at start_height, SS58 (prefix 42; the source's 0x + 64 hex, rendered). Null without an entry.

Format: SS58 address
owner_at_endstring · can be null

The life's last subnet owner coldkey (the current owner for the current life), SS58 (prefix 42; the source's 0x + 64 hex, rendered). Differs from owner_at_start when ownership moved during the life. Null without an entry.

Format: SS58 address
registration_lock_tao_raostring · unit rao (÷1e9) · can be null

SubnetLocked at the life's start: the TAO locked to register it, in rao of TAO. Null when not recorded.

Format: whole number, as a string · on chain: u64
identity_at_endobject · can be null

The identity the life last carried: the newest one set inside it (as_of_height says when). Null if it never had one.

8 fields in identity_at_end
as_of_heightinteger · unit block

The block this identity was set at: the newest identity set inside the life.

namestring · can be null

The subnet's name (SubnetIdentitiesV3.subnet_name) as set at as_of_height; null when unset (empty).

urlstring · can be null

The subnet's website (SubnetIdentitiesV3.subnet_url) as set at as_of_height; null when unset (empty).

githubstring · can be null

The subnet's GitHub repository (SubnetIdentitiesV3.github_repo) as set at as_of_height; null when unset (empty).

discordstring · can be null

The subnet's Discord (SubnetIdentitiesV3.discord) as set at as_of_height; null when unset (empty).

descriptionstring · can be null

The subnet's description (SubnetIdentitiesV3.description) as set at as_of_height; null when unset (empty).

logo_urlstring · can be null

URL of the subnet's logo (SubnetIdentitiesV3.logo_url) as set at as_of_height; null when unset (empty).

symbolstring · can be null

The token symbol (SubtensorModule.TokenSymbol) the life last carried. Null when unknown, and on an older data version's answer.

symbol_at_endstring · can be null

The token symbol (SubtensorModule.TokenSymbol) the life last carried, on its own: the same value as identity_at_end.symbol, and also there for a life that never had a subnet identity (identity_at_end null). Null when never set or not known yet, and on an older data version's answer that does not carry it.

is_end_exactboolean · can be null

Whether end_height is the recorded end. True: the chain recorded the removal (end_reason removed). False: superseded, so end_height is the next registration's block, an upper bound on the end. Null while current, and on an older data version's answer (unknown there).

owner_changesarray of objects · optional

With include=owner_changes only (absent otherwise; it needs netuid): every change of the subnet owner coldkey (SubnetOwner) or owner hotkey (SubnetOwnerHotkey) inside the life after its registration, from the storage history whatever the cause, oldest first. Empty when ownership never moved.

5 fields in owner_changes (each item)
kindstring

coldkey: the owner coldkey (SubnetOwner) changed; hotkey: the owner hotkey (SubnetOwnerHotkey). New values may be added; show an unknown value as is (or generically).

heightinteger · unit block

The block the new value was written in.

timestring (date-time) · can be null

That block's time, RFC 3339 UTC. Null when not recorded.

Format: date and time, ISO 8601 in UTC
fromstring · can be null

The value before the change, SS58 (prefix 42; the source's 0x + 64 hex, rendered). Null without a previous entry.

Format: SS58 address
tostring · can be null

The value after the change, SS58 (prefix 42). Null when the entry was removed.

Format: SS58 address

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.