Every life (generation) of every subnet slot
https://api.bittensor.ai/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'sowner_changes(every SubnetOwner / SubnetOwnerHotkey change inside it, oldest first). Needsnetuid(else a 400NETUID_REQUIRED). Anything else is a 400INVALID_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
netuidslot, 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 togeneration, which stays the id.- generationinteger · unit id
Opaque life id (the life's registration identifier), NOT a block height; use
life_start_heightfor the first block. This life's id. Candles and pools are keyed on it, and it is thegenerationof/subnets/{netuid}/candles. Often equal tostart_height, but runtime v133 set the key retroactively, so a life alive then has an id later than itsstart_height(SN1: 1,497,824 for a life that began at 172,898); a life that ended before v133 without one uses itsstart_height.- life_start_heightinteger · unit block · can be null
The first block of the life
generationnames (GET /subnets/generations'start_height): use it, nevergeneration, for heights, ages and dates. Null exactly whengenerationis null (root without a life, no subnet), or transiently when this API cannot read the lives. Root'sgeneration0 starts at 0.- is_current_lifeboolean · can be null
Whether
generationis the slot's current life (true) or an ended one, re-registered since (false). Null exactly whengenerationis null, or transiently when this API cannot read the lives. Root'sgeneration0 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'sstart_heightis 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's0x+ 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 fromowner_at_startwhen 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_heightsays 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_endnull). 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_heightis the recorded end. True: the chain recorded the removal (end_reasonremoved). False:superseded, soend_heightis 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_changesonly (absent otherwise; it needsnetuid): 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), 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.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_INCLUDE
- INVALID_NETUID
- NETUID_REQUIRED
- NOT_READY
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- SUBNET_NOT_FOUND
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.