Skip to content
TAO$188.32
BTC0.002928
MCap$2.22B
Vol$86.25M

API reference / Subnets

Each validator's share of a subnet's staked alpha, per closed UTC day

GET/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 400 BATCH_TOO_LARGE, an invalid one a 400 INVALID_ADDRESS naming 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 400 INVALID_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
alpha_share_ratiostring · unit ratio · can be null

alpha_rao over the subnet's staked alpha that day (meta.subnet_totals), 8 decimals. Null when the subnet held no stake.

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), 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.