# Get Miners Coldkey Summary

GET /v1/miners/coldkey-summary — Taostats API endpoint in the Miners group.

_Source: https://beta.taostats.io/docs/new/miners/get-miners-coldkey-summary_

_Last reviewed: 2026-10-07_

```http
GET https://api.taostats.io/v1/miners/coldkey-summary
```

Requires an API key in the `Authorization` header.

## Try it

Try this request in the browser on the HTML version of this page, or use the code samples below.

### Code samples

**cURL**

```bash
curl -H "Authorization: <YOUR_API_KEY>" \
  "https://api.taostats.io/v1/miners/coldkey-summary"
```

**JavaScript**

```js
const response = await fetch('https://api.taostats.io/v1/miners/coldkey-summary', {
  headers: {
    Authorization: '<YOUR_API_KEY>',
  },
});
const data = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    "https://api.taostats.io/v1/miners/coldkey-summary",
    headers={"Authorization": "<YOUR_API_KEY>"},
)
data = response.json()
```

## 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](https://beta.taostats.io/docs/start-here/getting-started-with-taostats-api).