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

API reference / Subnets

Metagraph of a subnet

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

The subnet's metagraph at the latest processed block.

Full description

The subnet's metagraph at the latest processed block: a summary (registered UIDs and the cap, validators and miners with how many are active, the last epoch's emission and the total stake) and every UID by uid: its hotkey and the hotkey's owner coldkey, whether it is active and holds a validator permit, the hotkey's stake in alpha and at spot in TAO and USD (meta.price_tao / meta.tao_usd), the alpha the last epoch paid it and its rank, incentive, dividends, consensus and validator trust as ratios (mechanism meta.mechanism), the last weight-setting block, the registration block, and the delegate and childkey takes, plus its axon and Prometheus endpoints, how many UIDs it sets weights on, its alpha dividends and their root-sourced part, and its associated EVM address, and weights_total, its raw weights summed, and stake_weight_parts, its stake weight split into own, inherited and root alpha (summing to stake_weight_alpha exactly). include=weights adds data.weights: per UID with a Weights row its last update, weights_count and weights_total. The weight pairs are opt-in: include=weight_pairs adds each row's [target_uid, raw u16] pairs, only for a request narrowed to 1..16 uids / hotkeys in all or to validators=permit (else 400 NARROW_WEIGHT_PAIRS). include=weight_commits adds data.weight_commits: the pending timelocked weight commits of every mechanism, oldest first, without the ciphertext. There is no pruning score: the runtime removed PruningScores in v393. Always the head (no at); not paged (at most 256 UIDs). uids / hotkeys narrow data.neurons, data.weights and data.weight_commits to some UIDs (the summary stays the whole subnet's; meta.neuron_filter states the filter). Errors are application/problem+json: INVALID_NETUID, NARROW_WEIGHT_PAIRS, INVALID_PARAMETER, INVALID_INCLUDE, INVALID_UID, INVALID_ADDRESS, FILTER_TOO_LARGE, SUBNET_NOT_FOUND (404, no registered neurons in this slot), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Path parameters

netuidpath, required· integer · 0 to 65535

Subnet slot (0 = root).

Query parameters

includequery· string

A comma list of weights (add data.weights: per UID its last update, weights_count and weights_total, mechanism 0), weight_pairs (also each UID's stored [target_uid, weight] pairs; needs uids / hotkeys, 1..16 in all, or validators=permit, else 400 NARROW_WEIGHT_PAIRS) and weight_commits (add data.weight_commits, the pending timelocked commits of every mechanism, narrowed by uids / hotkeys). Anything else is a 400 INVALID_INCLUDE.

uidsquery· string

Only these UIDs: a comma list of integers 0..65535, at most 256 (400 FILTER_TOO_LARGE above; anything else is a 400 INVALID_UID). Duplicates are dropped; an entry with no registered UID simply matches nothing (the list may come back empty, never a 404). With both uids and hotkeys, a UID is listed only when it matches both (AND). data.neurons keeps its order by uid; the summary (and data.weights with include=weights) stays the whole subnet's, and meta.neuron_filter echoes the filter applied.

hotkeysquery· string

Only the UIDs registered to these hotkeys: a comma list of SS58 or 0x + 64 hex, at most 256 (400 FILTER_TOO_LARGE above; an invalid one is a 400 INVALID_ADDRESS naming its index). The edge caps the request line at 4,094 bytes, which fits about 60 SS58 hotkeys. Duplicates are dropped; an entry with no registered UID simply matches nothing (the list may come back empty, never a 404). With both uids and hotkeys, a UID is listed only when it matches both (AND). data.neurons keeps its order by uid; the summary (and data.weights with include=weights) stays the whole subnet's, and meta.neuron_filter echoes the filter applied.

validatorsquery· string

permit: only the neurons holding a validator permit (at most 64 on a subnet), and their weights; include=weight_pairs then needs no uids / hotkeys (one read for the weight-similarity view). Combines with uids / hotkeys (a neuron must match all). meta.neuron_filter.validators is true and its uids the permit holders' uids. Anything else is a 400 INVALID_PARAMETER.

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 summary and the UIDs.

summaryobject

Counts and totals over the UIDs.

8 fields in summary
neuronsinteger · unit count

Registered UIDs (SubnetworkN).

max_uidsinteger · unit count · can be null

SubtensorModule.MaxAllowedUids. Null without an entry.

validatorsinteger · unit count

UIDs holding a validator permit.

active_validatorsinteger · unit count

UIDs holding a validator permit that are active (set weights within the activity cutoff).

minersinteger · unit count

UIDs without a validator permit.

active_minersinteger · unit count

Miners with incentive above 0 in the last epoch (active tracks weight setting, which miners do not do).

emission_epoch_alpha_raostring · unit alpha_rao (÷1e9) · can be null

Sum of the UIDs' emission_alpha_rao: alpha the last epoch paid them, in alpha rao.

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

Sum of the UIDs' stake_alpha_rao (TotalHotkeyAlpha on this subnet), in alpha rao.

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

One row per registered UID, by uid ascending (at most 256; not paged).

34 fields in neurons (each item)
uidinteger · unit id

The neuron's UID on the subnet.

hotkeystring · can be null

The UID's hotkey (SubtensorModule.Keys), SS58 (prefix 42). Null without an entry.

Format: SS58 address
coldkeystring · can be null

The coldkey that owns the hotkey (SubtensorModule.Owner), SS58. Null without an entry.

Format: SS58 address
activeboolean · can be null

SubtensorModule.Active[uid]: the UID set weights within the activity cutoff. Miners do not set weights, so this is about validators. Null without an entry.

validator_permitboolean · can be null

SubtensorModule.ValidatorPermit[uid]. Null without an entry.

stake_alpha_raostring · unit alpha_rao (÷1e9) · can be null

All alpha staked to the hotkey on this subnet (TotalHotkeyAlpha: the owner's and every nominator's), in alpha rao.

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

stake_alpha_rao x meta.price_tao, floored, in rao of TAO: a spot valuation, not what unstaking would pay. Null when either is null.

Format: whole number, as a string · on chain: u64
stake_spot_usdstring · unit usd · 6 decimals · can be null

stake_spot_tao_rao in USD at meta.tao_usd (6 decimals). Null without a price.

Format: decimal number, as a string
emission_alpha_raostring · unit alpha_rao (÷1e9) · can be null

SubtensorModule.Emission[uid]: alpha the last epoch paid the UID, in alpha rao.

Format: whole number, as a string · on chain: u64
emission_rankinteger · unit count · can be null

Rank of emission_alpha_rao among the subnet's UIDs, 1 = the largest. Null when the UID earned nothing in the last epoch.

incentive_ratiostring · unit ratio · 6 decimals · can be null

SubtensorModule.Incentive[uid] (u16 / 65535) of mechanism meta.mechanism: the miner score, a ratio 0..1 with 6 decimals. Null when the chain has no entry.

Format: decimal number, as a string
dividends_ratiostring · unit ratio · 6 decimals · can be null

SubtensorModule.Dividends[uid] (u16 / 65535) of mechanism meta.mechanism: the validator dividend share, a ratio 0..1 with 6 decimals. Null when the chain has no entry.

Format: decimal number, as a string
consensus_ratiostring · unit ratio · 6 decimals · can be null

SubtensorModule.Consensus[uid] (u16 / 65535) of mechanism meta.mechanism: the consensus weight, a ratio 0..1 with 6 decimals. Null when the chain has no entry.

Format: decimal number, as a string
validator_trust_ratiostring · unit ratio · 6 decimals · can be null

SubtensorModule.ValidatorTrust[uid] (u16 / 65535) of mechanism meta.mechanism: how far the validator's weights agree with consensus, a ratio 0..1 with 6 decimals. Null when the chain has no entry.

Format: decimal number, as a string
last_update_heightinteger · unit block · can be null

SubtensorModule.LastUpdate[uid]: the block the UID last set weights. Null without one.

blocks_since_updateinteger · unit blocks · can be null

meta.at.height - last_update_height. Null with it.

registered_at_heightinteger · unit block · can be null

SubtensorModule.BlockAtRegistration[uid]: the block the UID was registered at.

take_ratiostring · unit ratio · 6 decimals · can be null

The hotkey's delegate take (Delegates, u16 / 65535) as a ratio 0..1, 6 decimals. Null when the hotkey has no Delegates entry (the runtime's default take applies).

Format: decimal number, as a string
childkey_take_ratiostring · unit ratio · 6 decimals · can be null

The hotkey's childkey take on this subnet (ChildkeyTake, u16 / 65535) as a ratio 0..1, 6 decimals. Null when it has no entry (a take of 0).

Format: decimal number, as a string
stake_weight_alphastring · unit alpha · can be null

The stake weight the subnet's latest epoch (meta.stake_weight_epoch) used for this UID, exactly as the runtime logged it ('Filtered stake' / 1e9), a decimal string of alpha: alpha-equivalent stake = alpha stake + tao_weight x TAO (root) stake, both inherited through childkeys (the share a parent delegates counts at the child, not at the parent). It is filtered only by the global StakeThreshold: UIDs below it are set to 0 (at current runtimes the subnet owner's UID is exempt and keeps its weight). It is not the validator-permit filter: permits go to the top-K UIDs of this vector, so a UID with a positive weight can hold no permit. Null when the UID is not in that epoch's vector (registered after it), which is distinct from 0 (in the vector, below the threshold or without stake); null on every UID when meta.stake_weight_epoch is (root).

Format: decimal number, as a string
stake_weight_sharestring · unit ratio · can be null

stake_weight_alpha normalised to sum 1 over the subnet's UIDs ('Normalised Stake'): the stake weight Yuma consensus used in that epoch, a ratio 0..1 as a decimal string. Null exactly when stake_weight_alpha is.

Format: decimal number, as a string
stake_weight_partsobject · can be null · beta

stake_weight_alpha split into own, inherited and root alpha: own_alpha + inherited_alpha + root_alpha = stake_weight_alpha exactly (checked). Null when stake_weight_alpha is, when the epoch predates the breakdown (each subnet's epochs after 2026-10-04 carry it), when the UID fell below the StakeThreshold (its weight set to 0), and on an older data version's answer.

3 fields in stake_weight_parts
own_alphastring · unit alpha

The hotkey's own alpha stake on the subnet ('Initial alpha for hotkey'), a decimal string of alpha.

Format: decimal number, as a string
inherited_alphastring · unit alpha

The epoch's alpha stake minus own_alpha: alpha inherited from parent hotkeys minus alpha allocated to child hotkeys, a signed decimal string of alpha (negative when the hotkey gives its children more than it inherits).

Format: decimal number, as a string · can be negative
root_alphastring · unit alpha

tao_weight x the hotkey's root (TAO) stake after the same childkey inheritance, alpha-equivalent: stake_weight_alpha - the epoch's alpha stake, a decimal string of alpha.

Format: decimal number, as a string
axonobject · can be null

SubtensorModule.Axons(netuid, hotkey): the endpoint the UID serves. Null when unset or its ip is 0, and on an older data version's answer.

6 fields in axon
ipstring · can be null

The IP as text: dotted quad for ip_type 4, colon-separated hex groups for 6. Null when it cannot be decoded.

portinteger · unit id

The port.

ip_typeinteger · unit id

4 or 6.

protocolinteger · unit id

The protocol code the miner announced (as stored).

versioninteger · unit id

The software version the miner announced (as stored).

blockinteger · unit block

The block the axon was last served at.

prometheusobject · can be null

SubtensorModule.Prometheus(netuid, hotkey): the UID's metrics endpoint. Null when unset or its ip is 0, and on an older data version's answer.

5 fields in prometheus
ipstring · can be null

The IP as text: dotted quad for ip_type 4, colon-separated hex groups for 6. Null when it cannot be decoded.

portinteger · unit id

The port.

ip_typeinteger · unit id

4 or 6.

versioninteger · unit id

The version announced (as stored).

blockinteger · unit block

The block it was last served at.

weights_countinteger · unit count · can be null

Entries in SubtensorModule.Weights(netuid, uid) for mechanism 0: how many UIDs this one sets weights on (include=weights lists them). 0 when the UID has no Weights row; null only on an older answer.

dividends_alpha_raostring · unit alpha_rao (÷1e9) · can be null

SubtensorModule.AlphaDividendsPerSubnet(netuid, hotkey): the alpha dividends the last epoch paid the hotkey, in alpha rao. 0 when unset (the map's default); null only on an older answer.

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

SubtensorModule.RootAlphaDividendsPerSubnet(netuid, hotkey): the part of the dividends sourced by root (TAO) stake, also paid in alpha, in alpha rao. The runtime has had no TAO dividends map since v326. 0 when unset; null only on an older answer.

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

True while the UID is inside its immunity period: BlockAtRegistration + ImmunityPeriod is above meta.at. Null on an older answer.

immune_until_heightinteger · unit block · can be null

BlockAtRegistration + ImmunityPeriod: the block the UID's immunity ends. Null on an older answer.

sharesstring · unit shares · 9 decimals · can be null

The hotkey's share supply in this subnet's staking pool, 9 decimals: SubtensorModule.TotalHotkeySharesV2 (SafeFloat, mantissa × 10^exponent) where the pool has moved to it, else the legacy TotalHotkeyShares (U64F64, bits / 2^64); the two maps never both hold a hotkey. A share count, not a stake-weight fraction (that is stake_weight_share). Null when the hotkey has no pool on the subnet, and on an older answer.

Format: decimal number, as a string
shares_rawstring · can be null

The stored share value as read from chain storage, hex (the SafeFloat or U64F64 encoding named by shares_format). Null when shares is.

shares_formatenum · can be null

Which map shares came from, an opaque identifier: v2 (TotalHotkeySharesV2) or legacy (TotalHotkeyShares). Null when shares is.

One of: v2, legacy
weights_totalinteger · unit count · can be null

The UID's raw u16 weights summed as stored (0 without a Weights row): the denominator of its weight shares. The pairs: include=weight_pairs. Null on an older answer.

evm_h160object · can be null

SubtensorModule.AssociatedEvmAddress(netuid, uid): the EVM address associated with the UID and when. Null when none.

2 fields in evm_h160
addressstring

The H160, 0x + 40 lower-case hex.

Format: EVM address: 0x and 40 hex digits
associated_at_heightinteger · unit block

The block the association was stated at.

weightsarray of objects · optional

Only with include=weights (absent otherwise): every UID with a Weights row (mechanism 0), by uid, with its stored [target_uid, weight] pairs.

5 fields in weights (each item)
uidinteger · unit id

The UID setting the weights.

last_update_heightinteger · unit block · can be null

SubtensorModule.LastUpdate[uid]: the block it last set weights. Null without one.

weights_countinteger · unit count · can be null

How many [target_uid, weight] pairs the UID's Weights row holds (the neuron's weights_count). Null when the UID is not among the neurons.

weights_totalinteger · unit count · can be null

The UID's raw u16 weights summed as stored (divide a pair's weight by it for its share). Null only on an older data version's answer whose pairs were not decoded.

weightsarray of array · can be null

Only with include=weight_pairs (absent otherwise; include=weights no longer carries the pairs): SubtensorModule.Weights(netuid, uid) for mechanism 0, as stored: [target_uid, weight] pairs, the weight a raw u16 (0..65535; normalise by weights_total). Null when the row could not be decoded.

weight_commitsarray of objects · optional

Only with include=weight_commits (absent otherwise): the subnet's PENDING timelocked (commit-reveal v3+) weight commits, every mechanism (SubtensorModule.TimelockedWeightCommits), oldest commit first: who committed, for which epoch and mechanism, and the drand round that reveals it. The encrypted weights are not served. uids / hotkeys narrow them like data.neurons (a commit whose hotkey holds no UID then drops out of a uids filter). [] when none is pending.

6 fields in weight_commits (each item)
hotkeystring

The hotkey that committed, SS58 (prefix 42).

Format: SS58 address
uidinteger · unit id · can be null

The UID that hotkey holds on the subnet now. Null when it no longer holds one.

mechanisminteger · unit id

The mechanism the commit is for (the storage index is mechanism x 4096 + netuid; 0 = the subnet's first).

epochinteger · unit id

The epoch the commit belongs to (the map's second key).

commit_blockinteger · unit block

The block the commit was made in.

reveal_roundinteger · unit id

The drand round whose signature decrypts it (when the chain reveals the weights).

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.