Each validator's share of a subnet's staked alpha, per closed UTC day
https://api.bittensor.ai/api/v2/subnets/{netuid}/validators/dominance- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Who dominates a subnet over time: per closed UTC day of the last days (1..90, default 30), each validator pool's stake on the subnet (alpha), its share of the subnet's staked alpha that day (every pool on the subnet, meta.subnet_totals) and its stakers.
Full description
Who dominates a subnet over time: per closed UTC day of the last days (1..90, default 30), each validator pool's stake on the subnet (alpha), its share of the subnet's staked alpha that day (every pool on the subnet, meta.subnet_totals) and its stakers. Only days of the subnet's current registration are served: a window reaching further back is meta.complete false with meta.incomplete_reason, and a subnet with no current registration is served with no points (no_current_life). hotkeys limits the answer to those validators (in that order); without it every pool on the subnet is served. Figures are at UTC day closes: the newest is meta.through_day (the day before today once that day's data is published, normally within about an hour of midnight UTC). A day that is late but at most 36 hours overdue is still served, labelled by meta.through_day, with the response headers X-BTAI-Data-Through: <YYYY-MM-DD> and X-BTAI-Overdue-S: <seconds>; data more than 36 hours overdue is not served (503 SOURCE_NOT_READY with Retry-After); where this deployment does not serve the route it is a 503 SOURCE_NOT_READY. Amounts are integer strings in rao, ratios decimal strings. Cached as slow (the data moves once a day). Errors are application/problem+json: INVALID_NETUID, ADDRESSES_REQUIRED, BATCH_TOO_LARGE, INVALID_ADDRESS, INVALID_DAYS, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503), SERVICE_UNAVAILABLE (503), BAD_GATEWAY (502).
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
- hotkeysquery· string
Only these validators: a comma list of 1-500 hotkeys (SS58, or 0x + 64 hex; a repeat counts once). An empty list is a 400
ADDRESSES_REQUIRED, more than 500 a 400BATCH_TOO_LARGE, an invalid one a 400INVALID_ADDRESSnaming its index (hotkeys[i]). The request line is capped at 4,094 bytes, which fits about 60 SS58 hotkeys. Default: every pool on the subnet.- daysquery· integer · default 30 · 1 to 90
The closed UTC days served, ending at
meta.through_day: 1..90 (default 30). Anything else is a 400INVALID_DAYS.
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.
With hotkeys: one series per hotkey asked, in the order asked (a repeated hotkey once). Without: every validator pool on the subnet in the window, by stake at the newest served day, largest first (pools gone by then last), then by hotkey.
- hotkeyvalue · optional
The validator's hotkey, as
{ss58, hex}.- pointsarray of objects · optional
One point per served day the validator had a pool on the subnet, oldest first;
[]when none (a hotkey asked that held no pool there).4 fields in points (each item)
- daystring (date) · optional
The UTC day, at its close.
- Format: date, YYYY-MM-DD
- alpha_raostring · unit alpha_rao (÷1e9) · optional
Stake in the validator's pool on this subnet at the close, alpha (root: TAO) rao.
- Format: whole number, as a string · on chain: u64
- stakersinteger · unit count · optional
Positions with stake above 0 in the pool at the close.
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.
- ADDRESSES_REQUIRED
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BATCH_TOO_LARGE
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_DAYS
- INVALID_NETUID
- 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.