A hotkey's per-subnet take, stake and nominator yield, with a daily series
https://api.bittensor.ai/api/v2/hotkeys/{hotkey}/performance- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
A validator's performance in one call.
Full description
A validator's performance in one call. Per subnet the hotkey held a UID or a stake pool on in the window, or holds a UID on now: its UID, childkey take and stake NOW; its nominator yield over the window (yield: snapshots, the dividend credits summed, the mean stake and the APY of the pool's per-share index, net of take, alpha-denominated, price moves excluded); and one row per day with the day-end UID, validator permit, active flag, consensus, vtrust (validator_trust_ratio), dividends, stake, the pool's nominator dividend credits and that day's APY. Default window: the 30 days ending at the last available day, never before the data (meta.neuron_daily_from_day, meta.share_index_from_day; dividends after meta.emission_last_day are null, never a partial sum). yield.consistently_active is given only when the daily neuron history covers every window day (yield.active_days_covered = yield.window_days), null otherwise; an APY is negative when the pool's value per share fell. netuids narrows it to some subnets. A pinned window that has closed is cached 300 s (the current-state members still move with the chain); anything else as head state. Errors are application/problem+json: INVALID_ADDRESS, INVALID_NETUID, INVALID_DAY, INVALID_RANGE, UNKNOWN_PARAMETER, NOT_READY (503, the daily figures are not available yet), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).
Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).
Path parameters
- hotkeypath, required· string
The hotkey: SS58, or 0x + 64 hex.
Query parameters
- netuidsquery· string
Only these subnets. A comma list (or the parameter repeated) of subnets, each 0..65535, as many as needed; duplicates are ignored. Anything else is a 400
INVALID_NETUID.- from_dayquery· string (date)
First UTC day,
YYYY-MM-DD, inclusive. Default: 29 days beforeto_day.- Format: date, YYYY-MM-DD
- to_dayquery· string (date)
Last UTC day,
YYYY-MM-DD, inclusive. Default: the last available day.- Format: date, YYYY-MM-DD
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 hotkey and its subnets.
- hotkeyobject
The hotkey, as
{ss58, hex}.2 fields in hotkey
- ss58string
The account, SS58 (prefix 42).
- Format: SS58 address
- hexstring
The same 32-byte account id, 0x + 64 lower-case hex (the public key).
- Format: 32-byte hex: 0x and 64 hex digits
- take_ratiostring · unit ratio · can be null
Delegates (the validator take) / 65535, a ratio 0..1. Null when the hotkey is not a delegate.
- Format: decimal number, as a string
- subnetsarray of objects
Subnets the hotkey held a UID or a stake pool on in the window, or holds a UID on now;
netuidsfilters.[]when none.6 fields in subnets (each item)
- netuidinteger · unit id
The subnet slot.
- uidinteger · unit id · can be null
Its UID there now. Null when not registered there now.
- childkey_take_ratiostring · unit ratio · can be null
ChildkeyTake(hotkey, netuid) / 65535 now, a ratio 0..1. Null when unset.
- Format: decimal number, as a string
- stake_alpha_raostring · unit alpha_rao (÷1e9) · can be null
TotalHotkeyAlpha now, alpha rao of that subnet.
- Format: whole number, as a string · on chain: u64
- yieldobject
The nominator yield over the window (
meta.from_day..meta.to_day).12 fields in yield
- from_daystring (date)
First day the yield is rated over.
- Format: date, YYYY-MM-DD
- to_daystring (date)
Last day the yield is rated over.
- Format: date, YYYY-MM-DD
- snapshotsinteger · unit count
Window days with a pool share index.
- daysinteger · unit count · can be null
Days the window has for the pool: the window, or from the pool's first index day when it is younger (root: the days with an accrual and a stake to rate it against).
apy_ratiois served only when this is the whole window (elseapy_unavailable_reasonwindow_too_short). Null when no index exists.- period_nominator_dividend_alpha_raostring · unit alpha_rao (÷1e9) · can be null
The window's daily nominator dividend credits summed, in alpha rao of that subnet. Null when a window day is past
meta.emission_last_day(a partial sum is never served).- Format: whole number, as a string · on chain: u64
- avg_stake_alpha_raostring · unit alpha_rao (÷1e9) · can be null
Mean day-end TotalHotkeyAlpha over the window days that have one, alpha rao. Null without any.
- Format: whole number, as a string · on chain: u64
- apy_ratiostring · unit ratio · can be null
The pool's per-share return annualised: (index_to / index_start)^(365 / days) - 1, a ratio (nominator yield net of take, alpha-denominated, price moves excluded). Negative when the pool's value per share fell over the window (-1 = it fell to zero, e.g. a dissolved subnet's pool). Null exactly when
apy_unavailable_reasonis set (checked): only a whole window is annualised, never a younger pool's fewer days. On an older data version's answer it may be rated over a younger pool's own days, and is null without both indexes.- Format: decimal number, as a string · can be negative
- consistently_activeboolean · can be null
True when the hotkey was registered on this subnet with Active set at every window day end; false when any was not. Given only when the daily neuron history covers every window day (
active_days_covered=window_days, checked), null otherwise: a partial window is no claim about the days it lacks. On an older data version's answer it may be read over the covered days only (null when none was covered), or null.- active_days_coveredinteger · unit count · can be null
The window day ends the daily neuron history covers, 0..
window_days(checked).consistently_activeis given only when this equalswindow_days. Null on an older answer.- window_daysinteger · unit count · can be null
The day ends in the window (
from_day..to_dayinclusive, and the subnet'sdailyrows; checked). Null on an older answer.- apy_basisstring · can be null
What
apy_ratio(here and on everydailyrow) is measured on.share_index: a subnet pool's per-share growth (nominator yield net of take, alpha-denominated, price moves excluded).root_claimable(root, netuid 0): the root claimable accrued over the window against the mean day-end root stake held over those days, pool-wide, net of take, at spot, before the claim's swap cost and RootClaimableThreshold: accrued, not realised. Either way a rate, never a stake or income total. Null on an older data version's answer. New values may be added; show an unknown value as is (or generically).
- dailyarray of objects
One row per window day, oldest first.
10 fields in daily (each item)
- daystring (date)
The UTC day.
- Format: date, YYYY-MM-DD
- uidinteger · unit id · can be null
The UID the hotkey held at the day end. Null when it held none that day, or outside
meta.neuron_daily_from_day..meta.neuron_daily_to_day.- validator_permitboolean · can be null
ValidatorPermit at the day end. Null without a UID that day or outside the neuron days.
- activeboolean · can be null
Active at the day end. Null without a UID that day or outside the neuron days.
- consensus_ratiostring · unit ratio · can be null
Consensus / 65535 at the day end, a ratio 0..1. Null without a UID.
- Format: decimal number, as a string
- validator_trust_ratiostring · unit ratio · can be null
ValidatorTrust / 65535 at the day end, a ratio 0..1 (vtrust). Null without a UID.
- Format: decimal number, as a string
- dividends_ratiostring · unit ratio · can be null
Dividends / 65535 at the day end, a ratio 0..1. Null without a UID.
- Format: decimal number, as a string
- stake_alpha_raostring · unit alpha_rao (÷1e9) · can be null
TotalHotkeyAlpha at the day end, alpha rao. Null outside the days with daily stake data.
- Format: whole number, as a string · on chain: u64
- nominator_dividend_alpha_raostring · unit alpha_rao (÷1e9) · can be null
The pool's nominator dividend credits that day (net of take), alpha rao. Null after
meta.emission_last_day.- Format: whole number, as a string · on chain: u64
- apy_ratiostring · unit ratio · can be null
(index_D / index_{D-1})^365 - 1: the pool's per-share return that day, compounded (nominator yield net of take, alpha-denominated, price moves excluded). Negative when the value per share fell that day (-1 = it fell to zero). Null without both indexes.
- Format: decimal number, as a string · can be negative
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_ADDRESS
- INVALID_DAY
- INVALID_NETUID
- INVALID_RANGE
- NOT_READY
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.