Documentation / New API reference / Miners
Get Miners Coldkey Summary
GET /v1/miners/coldkey-summary — Taostats API endpoint in the Miners group.
Reference
Last reviewed 2026-10-07
Try it
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
coldkey | query | string | Yes | Coldkey, SS58 or 0x-prefixed hex. |
days | query | integer (int32) | Yes | How many days of history the windowed totals cover. Required, matching the OLD API. Between 1 and 36,500. |
Responses
200 — Mining summary for one coldkey
| Field | Type | Required | Description |
|---|---|---|---|
data | array | Yes | The summary, as a one-element array: data is always an array (docs/api_standards.md). |
data[].active_subnets | integer (int32) | Yes | Distinct subnets the coldkey currently mines in. |
data[].alpha_balances | array | Yes | Every alpha position the coldkey holds, mining or not. |
data[].alpha_balances[].balance | string | Yes | Alpha balance (RAO, u64 decimal string). |
data[].alpha_balances[].balance_as_tao | string | Yes | The same balance valued in TAO (RAO, u64 decimal string). |
data[].alpha_balances[].coldkey | string | Yes | Coldkey that owns the position (SS58). |
data[].alpha_balances[].hotkey | string | Yes | Hotkey the alpha is staked to (SS58). |
data[].alpha_balances[].netuid | integer (int32) | Yes | Subnet the alpha belongs to. |
data[].average_mining_emission_as_tao_per_hotkey | string | Yes | That total divided by total_active_hotkeys, floored (RAO, decimal string). "0" when there are no active hotkeys. |
data[].coldkey | string | Yes | Coldkey (SS58). |
data[].free_balance | string | Yes | Free TAO balance (RAO, decimal string). |
data[].hotkeys | array | Yes | Per-hotkey breakdown: currently registered neurons first, then deregistrations from the window. |
data[].hotkeys[].alpha_balance | string | Yes | Alpha staked to this hotkey in this subnet (RAO, decimal string). "0" when the coldkey holds no position there. |
data[].hotkeys[].alpha_balance_as_tao | string | Yes | That alpha valued in TAO (RAO, decimal string). |
data[].hotkeys[].axon | string | Yes | ip:port of the neuron's axon, or "" when it serves none. |
data[].hotkeys[].coldkey | string | Yes | Coldkey (SS58). |
data[].hotkeys[].consensus | string | Yes | Consensus (normalised u16 / 65535). |
data[].hotkeys[].deregistered | boolean | Yes | Whether this row is a deregistration that happened during the window. |
data[].hotkeys[].deregistration_timestamp | string, nullable | Yes | When it was deregistered (ISO 8601, millisecond precision), or null for a currently registered hotkey. |
data[].hotkeys[].emission | string | Yes | The neuron's emission at the current snapshot (RAO, decimal string). |
data[].hotkeys[].hotkey | string | Yes | Hotkey (SS58). |
data[].hotkeys[].immune | boolean | Yes | Within the subnet's immunity period, so it cannot be deregistered yet. |
data[].hotkeys[].in_danger | boolean | Yes | Among the subnet's lowest-incentive non-immune neurons, so it is at risk of deregistration. Always false for a deregistered hotkey. |
data[].hotkeys[].incentive | string | Yes | Incentive summed across the subnet's mechanisms, weighted by its emission split (normalised over 65535²), as the OLD API serves it. On a single-mechanism subnet this is the plain u16 / 65535 incentive. |
data[].hotkeys[].mech_incentive | array | Yes | Per-mechanism incentive (normalised u16 / 65535, one per mechanism). |
data[].hotkeys[].mech_incentive[] | string | Yes | |
data[].hotkeys[].miner_rank | integer (int32), nullable | Yes | Competition rank by incentive within the subnet, null when incentive is zero. |
data[].hotkeys[].netuid | integer (int32) | Yes | Subnet ID. |
data[].hotkeys[].registration_block | integer (int32) | Yes | Block the neuron registered at. 0 for a deregistered hotkey, which is what the OLD API reports: neuron_deregistration_v1 does not record a registration block. |
data[].hotkeys[].total_emission | string | Yes | Alpha emitted to this hotkey across the whole window (RAO, decimal string) — the sum of its per-epoch emission. |
data[].hotkeys[].total_emission_as_tao | string | Yes | total_emission valued in TAO at the current alpha price (RAO, decimal string). |
data[].hotkeys[].trust | string | Yes | Trust (normalised u16 / 65535). |
data[].hotkeys[].uid | integer (int32) | Yes | Neuron UID within the subnet. |
data[].hotkeys[].validator_rank | integer (int32), nullable | Yes | Competition rank by dividends within the subnet, null when dividends are zero. |
data[].total_active_hotkeys | integer (int32) | Yes | Currently registered (subnet, hotkey) neurons. |
data[].total_balance | string | Yes | Free plus reserved plus staked, all in RAO (decimal string). |
data[].total_deregistered_hotkeys | integer (int32) | Yes | Deregistrations recorded for this coldkey during the window. |
data[].total_hotkeys_in_danger | integer (int32) | Yes | How many of those are in danger. |
data[].total_hotkeys_in_danger_during_period | integer (int32) | Yes | Distinct (subnet, hotkey) neurons that were in danger at any epoch in the window, including ones since deregistered. |
data[].total_immune_hotkeys | integer (int32) | Yes | How many of those are immune. |
data[].total_immune_hotkeys_during_period | integer (int32) | Yes | Distinct (subnet, hotkey) neurons that were immune at any epoch in the window, including ones since deregistered. |
data[].total_mining_emission_as_tao | string | Yes | Every epoch's emission across the window, each row valued in TAO at the current alpha price (RAO, decimal string). |
data[].total_staked_balance_as_tao | string | Yes | Every alpha position valued in TAO (RAO, decimal string). Derived by summing alpha_balances, so the response's own numbers add up rather than mixing two snapshots. |
data[].total_staked_mining_balance_as_tao | string | Yes | The part of that staked in a subnet the coldkey currently mines in, on the mining hotkey (RAO, decimal string). |
data[].total_staked_non_mining_balance_as_tao | string | Yes | The rest (RAO, decimal string). |
pagination | object | Yes | Pagination block. Always one item on one page. |
pagination.current_page | integer (int32) | Yes | 1-indexed page that produced the rows in data. |
pagination.next_page | integer (int32), nullable | Yes | Next page number, or null if this is the last page. |
pagination.per_page | integer (int32) | Yes | Number of items requested per page. |
pagination.prev_page | integer (int32), nullable | Yes | Previous page number, or null if this is the first page. |
pagination.total_items | integer (int64) | Yes | Number of items matching the query across all pages. This is the exact count — every matching row, however many there are. It is not bounded by total_pages, so a listing can legitimately report far more items than total_pages × per_page. |
pagination.total_pages | integer (int32) | Yes | Number of pages at the current per_page that this API will serve: ceil(total_items / per_page), capped at ceil(1000000 / per_page) because the page parameter only reaches into the first 1,000,000 rows. When the cap bites, total_items is still the true total and this is the last page a request can ask for; reach deeper history with the endpoint's range filters instead of a larger page. |
400 — Invalid query parameter
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Plain-english message describing the failure from the caller's perspective. |
status_code | integer (int32) | Yes | HTTP status code (mirrored in the response status line for convenience). |
500 — Internal server error
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Plain-english message describing the failure from the caller's perspective. |
status_code | integer (int32) | Yes | HTTP status code (mirrored in the response status line for convenience). |
Every request needs an Authorization header holding your API key — see Getting started with the Taostats API.