A subnet's holders, delegates, positions and staked alpha at each closed UTC day's end
https://api.bittensor.ai/api/v2/subnets/{netuid}/holders/daily- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Per closed UTC day, oldest first, at the day's last block.
Full description
Per closed UTC day, oldest first, at the day's last block: the coldkeys holding the subnet's alpha (holder_count), the delegates (delegate_count: the hotkeys holding a share from a coldkey other than their Owner, null before meta.delegate_count_from_day; on an older data version's answer the hotkeys with a staker), the (hotkey, coldkey) positions, the alpha staked (total_alpha_rao), the largest position, the 10 largest coldkeys' alpha, nakamoto, the normalised HHI and the validator permits. The delegates, positions and largest position come from the pools' day-end stakers: null on a day where they cannot be whole, never a 0 standing in. A subnet without holder rows in the window answers [] with meta.missing_netuids = [netuid]. Moves when the next day is available: cached as slow. Day window: from_day / to_day (inclusive UTC days), or days back from to_day (not both days and from_day); no ceiling: a range longer than meta.page.limit_days pages by cursor (meta.page.next_cursor), oldest days first, and meta.range states the whole request (from_day raised to the first available day says so). An explicit to_day is never answered with an earlier day: one not available yet is a 503 NOT_READY. While paged day windows are not available yet, from_day, to_day and cursor are a 503 SOURCE_NOT_READY (a days-only request is unchanged). One life: a netuid is a slot and a re-registered subnet is a new life; the series covers the subnet's CURRENT life only, from its first whole UTC day (data[].generation, data[].life_start_height, data[].life_first_day; a life with no whole day yet answers no rows). While per-life series are not available yet, the series is not limited to one life and those members are null. meta.lives states the subnet's current life with rows or not. include=distribution adds the analytics store's stake distribution of the series' life over the same days (data[].distribution: per closed day the Gini coefficient and top-10 share of the holders' alpha, the holdings' TAO value at the close, its p50 / p90 / p99 (null under 50 priced holdings) and the unpriced holdings; never a holder list), its day watermark in meta.sections.distribution and both stores in meta.sources. The holder figures stay the chain database's. Each day is computed after it closes, so its newest day can trail the page's. The section never fails the call: when it cannot be served it is null and meta.sections.distribution.unavailable_reason says why (not_enabled where this deployment does not read it, not_ready, stale when the store is more than 6 hours overdue, source_unavailable, no_series); the answer is then cached as slow. Errors are application/problem+json: INVALID_NETUID, INVALID_DAYS, INVALID_DAY, INVALID_RANGE, INVALID_CURSOR, INVALID_INCLUDE, UNKNOWN_PARAMETER, NOT_READY (503), NOT_FINAL (503), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503). meta.final_through_day is the key to cache closed days by: the rows through it never change again (but by an announced rerun); later rows may (null on an older data version's answer).
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
- daysquery· integer · default 30 · at least 1
How many closed UTC days end at
to_day(default 30, ending at the newest closed day; fewer where the daily holders starts later:meta.from_daysays where). No ceiling: a range longer than one page pages bycursor(while paged day windows are not available yet, more than 365 is a 400INVALID_DAYS). Not withfrom_day(both: a 400INVALID_RANGE). Outside 1..1,000,000 is a 400INVALID_DAYS.- from_dayquery· string (date)
The first UTC day,
YYYY-MM-DD, inclusive (raised to the first available day:meta.range.from_day_raised). Not withdays(both: a 400INVALID_RANGE); afterto_day: a 400INVALID_RANGE; not a date: a 400INVALID_DAY.- Format: date, YYYY-MM-DD
- to_dayquery· string (date)
The last closed UTC day,
YYYY-MM-DD, inclusive (default: the newest available day). Final or refused, never an earlier day: a day not available yet is a 503NOT_READY, one available but aftermeta.final_through_daya 503NOT_FINAL(retry). Today is a 503NOT_READY(closed days only), a later day a 400INVALID_RANGE, not a date a 400INVALID_DAY. A finalto_dayis cached as settled.- Format: date, YYYY-MM-DD
- cursorquery· string · up to 200 characters
meta.page.next_cursorof the previous page: the next days of a range longer than one page, sent back unchanged with the same other parameters (a changed or altered one is a 400INVALID_CURSOR). While paged day windows are not available yet: 503SOURCE_NOT_READY.- includequery· string
distribution: add the life's stake distribution per day from the analytics store (data[].distribution,meta.sections.distribution). 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.
The subnet's series (one item), or [] when it has no holder rows in the window.
- netuidinteger · unit id
The subnet slot.
- daysarray of objects
One per closed day with holder rows, oldest first; the current life's days only (from
life_first_day).11 fields in days (each item)
- daystring (date)
The UTC day.
- Format: date, YYYY-MM-DD
- heightinteger · unit block
The day's last block: every figure is read there.
- holder_countinteger · unit count
Coldkeys with alpha > 0 on the subnet (each counted once).
- delegate_countinteger · unit count · can be null
The nominator count: hotkeys whose pool on the subnet holds a non-zero share from a coldkey other than the hotkey's Owner (the validators other people delegate to; the subnet list's
delegates), at the day's end. Null on a day beforemeta.delegate_count_from_day(each pool's Owner is not recorded for those days; every day when that is null), never a 0 standing in. On an older data version's answer: hotkeys with at least one staker. Either way null, withposition_countandmax_position_alpha_rao, when the pools' day-end stakers cannot be whole (fewer positions than holders) or disagree with the holders (the largest position abovetop10_alpha_rao).- position_countinteger · unit count · can be null
(hotkey, coldkey) positions with alpha > 0 (at least
holder_count). Null when the pools' day-end stakers cannot be whole (fewer positions than holders) or disagree with the holders (the largest position abovetop10_alpha_rao).- total_alpha_raostring · unit alpha_rao (÷1e9)
The holders' alpha together, alpha rao.
- Format: whole number, as a string · on chain: u64
- max_position_alpha_raostring · unit alpha_rao (÷1e9) · can be null
The largest single (hotkey, coldkey) position, alpha rao (at most
top10_alpha_rao). Null withposition_count.- Format: whole number, as a string · on chain: u64
- top10_alpha_raostring · unit alpha_rao (÷1e9)
The 10 largest coldkeys' alpha together, alpha rao (at most
total_alpha_rao).- Format: whole number, as a string · on chain: u64
- nakamotointeger · unit count
The fewest coldkeys holding more than half the alpha (0 without a holder; at most 10 exactly when
top10_alpha_raois more than half, checked).- hhi_ratiostring · unit ratio · 8 decimals · can be null
Normalised Herfindahl-Hirschman index over the coldkeys' alpha, 0..1, 8 decimals (0 = spread evenly, 1 = one holder). Null when the source has none.
- Format: decimal number, as a string
- validator_permitsinteger · unit count · can be null
UIDs holding a validator permit at the day's end. Null while the day's neuron data isn't available yet.
- generationinteger · unit id · can be null
Opaque life id (the life's registration identifier), NOT a block height; use
life_start_heightfor the first block. The subnet life served (GET /subnets/generations). A netuid is a slot: a re-registered subnet is a new life, and this series covers the current one only. Null when the slot has no recorded life (root) and on an older data version's answer.- 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.- life_start_heightinteger · unit block · can be null
The served life's first block. Null exactly when
generationis null.- life_first_daystring (date) · can be null
The served life's first whole UTC day (the day after its first block's day, which also holds the previous life's blocks): the days start here. Null without a life (or when its first block's time is unknown), and on an older data version's answer.
- Format: date, YYYY-MM-DD
- distributionarray of objects · can be null
include=distribution(GET /subnets/{netuid}/holders/dailyonly): the life's stake distribution per closed day of the page, oldest first: the Gini coefficient, the top-10 share, the holdings' TAO value and its percentiles. It ends atmeta.sections.distribution.through_day(each day is computed after it closes, so its newest day may traildays); a day with no holder has no row. Null when the section is unavailable (meta.sections.distribution.unavailable_reason); absent without the include.11 fields in distribution (each item)
- daystring (date)
The closed UTC day; every figure is at its last block.
- Format: date, YYYY-MM-DD
- day_end_heightinteger · unit block
The day's last block.
- holdersinteger · unit count
Coldkeys holding the life's alpha (> 0, summed over their hotkeys): the holder figure's population.
- alpha_raostring · unit alpha_rao (÷1e9)
Their alpha together, alpha rao.
- Format: whole number, as a string · on chain: u64
- value_tao_raostring · unit rao (÷1e9) · can be null
That alpha's TAO value at the day's close, rao. Null when any holding could not be priced (
unpriced_holders> 0): a partial total is never served.- Format: whole number, as a string · on chain: u64
- unpriced_holdersinteger · unit count
Holdings whose value is unknown that day (no close price): left out of the value figures, never counted as 0.
- gini_ratiostring · unit ratio · 6 decimals
The Gini coefficient of the holders' alpha, 0..1, 6 decimals (0 = evenly held, near 1 = one holder).
- Format: decimal number with 6 places, as a string
- value_p50_tao_raostring · unit rao (÷1e9) · can be null
The median holding's TAO value at the close, rao. Linear interpolation between closest ranks (R-7), floored to rao, over the priced holdings only. Null when fewer than 50 holdings are priced: a small population's high percentile would be one holder's exact holding.
- Format: whole number, as a string · on chain: u64
- value_p90_tao_raostring · unit rao (÷1e9) · can be null
The 90th percentile of the holdings' TAO value, rao. Linear interpolation between closest ranks (R-7), floored to rao, over the priced holdings only. Null when fewer than 50 holdings are priced: a small population's high percentile would be one holder's exact holding.
- Format: whole number, as a string · on chain: u64
- value_p99_tao_raostring · unit rao (÷1e9) · can be null
The 99th percentile of the holdings' TAO value, rao. Linear interpolation between closest ranks (R-7), floored to rao, over the priced holdings only. Null when fewer than 50 holdings are priced: a small population's high percentile would be one holder's exact holding.
- 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), 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_CURSOR
- INVALID_DAY
- INVALID_DAYS
- INVALID_INCLUDE
- INVALID_NETUID
- INVALID_RANGE
- NOT_FINAL
- NOT_READY
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.