Metagraph of a subnet
https://api.bittensor.ai/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(adddata.weights: per UID its last update,weights_countandweights_total, mechanism 0),weight_pairs(also each UID's stored[target_uid, weight]pairs; needsuids/hotkeys, 1..16 in all, orvalidators=permit, else 400NARROW_WEIGHT_PAIRS) andweight_commits(adddata.weight_commits, the pending timelocked commits of every mechanism, narrowed byuids/hotkeys). Anything else is a 400INVALID_INCLUDE.- uidsquery· string
Only these UIDs: a comma list of integers 0..65535, at most 256 (400
FILTER_TOO_LARGEabove; anything else is a 400INVALID_UID). Duplicates are dropped; an entry with no registered UID simply matches nothing (the list may come back empty, never a 404). With bothuidsandhotkeys, a UID is listed only when it matches both (AND).data.neuronskeeps its order byuid; the summary (anddata.weightswithinclude=weights) stays the whole subnet's, andmeta.neuron_filterechoes 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_LARGEabove; an invalid one is a 400INVALID_ADDRESSnaming 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 bothuidsandhotkeys, a UID is listed only when it matches both (AND).data.neuronskeeps its order byuid; the summary (anddata.weightswithinclude=weights) stays the whole subnet's, andmeta.neuron_filterechoes the filter applied.- validatorsquery· string
permit: only the neurons holding a validator permit (at most 64 on a subnet), and their weights;include=weight_pairsthen needs nouids/hotkeys(one read for the weight-similarity view). Combines withuids/hotkeys(a neuron must match all).meta.neuron_filter.validatorsis true and itsuidsthe permit holders' uids. Anything else is a 400INVALID_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 (
activetracks 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
uidascending (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_raoxmeta.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_raoin USD atmeta.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_raoamong 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 whenmeta.stake_weight_epochis (root).- Format: decimal number, as a string
- stake_weight_partsobject · can be null · beta
stake_weight_alphasplit into own, inherited and root alpha:own_alpha+inherited_alpha+root_alpha=stake_weight_alphaexactly (checked). Null whenstake_weight_alphais, 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_type4, 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_type4, 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=weightslists 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.
0when 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.
0when 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.
- 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), byuid, 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'sweights_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=weightsno 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 byweights_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/hotkeysnarrow them likedata.neurons(a commit whose hotkey holds no UID then drops out of auidsfilter).[]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), 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
- FILTER_TOO_LARGE
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_INCLUDE
- INVALID_NETUID
- INVALID_PARAMETER
- INVALID_UID
- NARROW_WEIGHT_PAIRS
- 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.