# Get Metagraph History

Returns historical subnet neuron state, including stake, incentives, emissions, trust and validator permits.

_Source: https://beta.taostats.io/docs/api-reference/metagraph/get-metagraph-history_

_Last reviewed: 2026-09-18_

```http
GET https://api.taostats.io/api/metagraph/history/v1
```

Requires an API key in the `Authorization` header.

Returns historical subnet neuron state, including stake, incentives, emissions, trust and validator permits. Each Metagraph record identifies the neuron's UID, hotkey and coldkey at a block.

## Try it

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

### Examples

Track a specific neuron (UID 0 in subnet 19) across the metagraph over time

```text
https://api.taostats.io/api/metagraph/history/v1?netuid=19&uid=0&order=block_number_desc&limit=100
```

### Code samples

**cURL**

```bash
curl -H "Authorization: <YOUR_API_KEY>" \
  "https://api.taostats.io/api/metagraph/history/v1?netuid=19&uid=0&limit=100&order=block_number_desc"
```

**JavaScript**

```js
const response = await fetch('https://api.taostats.io/api/metagraph/history/v1?netuid=19&uid=0&limit=100&order=block_number_desc', {
  headers: {
    Authorization: '<YOUR_API_KEY>',
  },
});
const data = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    "https://api.taostats.io/api/metagraph/history/v1?netuid=19&uid=0&limit=100&order=block_number_desc",
    headers={"Authorization": "<YOUR_API_KEY>"},
)
data = response.json()
```

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `netuid` | query | `integer (int32)` |  | Subnet ID |
| `uid` | query | `integer (int32)` |  | Neuron ID |
| `hotkey` | query | `string` |  | SS58 or hex format |
| `coldkey` | query | `string` |  | SS58 or hex format |
| `block_start` | query | `integer (int32)` |  | Start of block range (inclusive) |
| `block_end` | query | `integer (int32)` |  | End of block range (inclusive) |
| `timestamp_start` | query | `integer (int64)` |  | Start of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive) |
| `timestamp_end` | query | `integer (int64)` |  | End of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive) |
| `page` | query | `integer (int32)` |  | The page number of the response. |
| `limit` | query | `integer (int32)` |  | The number of responses. max is 200, |
| `order` | query | `string` |  | One of `block_number_asc`, `block_number_desc`, `timestamp_asc`, `timestamp_desc`. |

## Responses

### `200` — Metagraph history retrieved successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `array` | Yes |  |
| `data[].active` | `boolean` | Yes |  |
| `data[].alpha_stake` | `string` | Yes |  |
| `data[].axon` | `object, nullable` |  |  |
| `data[].block_number` | `integer (int32)` | Yes |  |
| `data[].coldkey` | `object` | Yes |  |
| `data[].coldkey.hex` | `string` | Yes | The hex format of the hot key |
| `data[].coldkey.ss58` | `string` | Yes | The SS58 format of the hot key |
| `data[].collateral` | `string, nullable` |  | Locked registration collateral remaining on this miner's position. Null before runtime 437 and while the subnet has collateral disabled. |
| `data[].consensus` | `string` | Yes |  |
| `data[].daily_burned_alpha` | `string, nullable` |  | mining emission burned by owner hotkey |
| `data[].daily_burned_alpha_as_tao` | `string, nullable` |  | mining emission burned by owner hotkey denominated in tao |
| `data[].daily_mining_alpha` | `string, nullable` |  | post dtao mining alpha |
| `data[].daily_mining_alpha_as_tao` | `string, nullable` |  | post dtao mining alpha denominated in tao |
| `data[].daily_mining_tao` | `string, nullable` |  | pre dtao mining emission |
| `data[].daily_owner_alpha` | `string, nullable` |  | owner cut of alpha emission |
| `data[].daily_owner_alpha_as_tao` | `string, nullable` |  | owner cut of alpha emission denominated in tao |
| `data[].daily_reward` | `string` | Yes | deprecated |
| `data[].daily_total_rewards_as_tao` | `string, nullable` |  | total rewards denominated in tao |
| `data[].daily_validating_alpha` | `string, nullable` |  | validating alpha emission |
| `data[].daily_validating_alpha_as_tao` | `string, nullable` |  | validating alpha emission denominated in tao |
| `data[].daily_validating_tao` | `string, nullable` |  | validating tao emission (post dtao this is root dividends, pre dtao this is all dividends) |
| `data[].dividends` | `string` | Yes |  |
| `data[].emission` | `string` | Yes |  |
| `data[].hotkey` | `object` | Yes |  |
| `data[].hotkey.hex` | `string` | Yes | The hex format of the hot key |
| `data[].hotkey.ss58` | `string` | Yes | The SS58 format of the hot key |
| `data[].incentive` | `string` | Yes |  |
| `data[].is_child_key` | `boolean` | Yes |  |
| `data[].is_immunity_period` | `boolean` | Yes |  |
| `data[].is_owner_hotkey` | `boolean, nullable` |  |  |
| `data[].mech_incentive` | `array` | Yes |  |
| `data[].mech_incentive[]` | `string` | Yes |  |
| `data[].mech_updated` | `array` | Yes |  |
| `data[].mech_updated[]` | `integer (int32)` | Yes |  |
| `data[].netuid` | `integer (int32)` | Yes |  |
| `data[].rank` | `integer (int32)` | Yes |  |
| `data[].registered_at_block` | `integer (int32)` | Yes |  |
| `data[].root_stake` | `string` | Yes |  |
| `data[].root_stake_as_alpha` | `string` | Yes |  |
| `data[].root_weight` | `string` | Yes |  |
| `data[].stake` | `string` | Yes |  |
| `data[].timestamp` | `string (date-time)` | Yes |  |
| `data[].total_alpha_stake` | `string` | Yes |  |
| `data[].trust` | `string` | Yes |  |
| `data[].uid` | `integer (int32)` | Yes |  |
| `data[].updated` | `integer (int32)` | Yes |  |
| `data[].validator_permit` | `boolean` | Yes |  |
| `data[].validator_trust` | `string` | Yes |  |
| `pagination` | `object` | Yes |  |
| `pagination.current_page` | `integer (int32)` | Yes |  |
| `pagination.next_page` | `integer (int32), nullable` |  |  |
| `pagination.per_page` | `integer (int32)` | Yes |  |
| `pagination.prev_page` | `integer (int32), nullable` |  |  |
| `pagination.total_items` | `integer (int32)` | Yes |  |
| `pagination.total_pages` | `integer (int32)` | Yes |  |

**Example response**

```json
{
  "data": [
    {
      "active": false,
      "axon": {
        "block": 3854601,
        "ip": "13.248.142.17",
        "ipType": 4,
        "placeholder1": 0,
        "placeholder2": 0,
        "port": 8097,
        "protocol": 4,
        "version": 711
      },
      "block_number": 4207460,
      "coldkey": {
        "hex": "0x829a538c77776782639b69c9b6e97c326295e6285bd94fa6e5a03f61fcadb733",
        "ss58": "5F1wvhbYNdq7E7tMsaUdHRXy462nbUNnMurihtNrZ8zMSoF3"
      },
      "consensus": "0.00419623102159151598",
      "daily_reward": "246139420",
      "dividends": "0",
      "emission": "12306971",
      "hotkey": {
        "hex": "0x92b6d40fe7134903eef7f9b3f5ab06fe24008326cb189c30e0c17b3150116c45",
        "ss58": "5FP5ADUSBNpmtRiQd2rtjVcQs3Emc5b1rMbiatxRYJ7gWJHn"
      },
      "incentive": "0.00422674906538490883",
      "is_child_key": false,
      "is_immunity_period": false,
      "netuid": 10,
      "rank": 110,
      "registered_at_block": 4144278,
      "stake": "497653819",
      "timestamp": "2024-11-06T15:33:24.001Z",
      "trust": "0.98957808804455634394",
      "uid": 145,
      "updated": 1320571,
      "validator_permit": false,
      "validator_trust": "0"
    },
    {
      "active": false,
      "axon": {
        "block": 4157211,
        "ip": "103.252.0.169",
        "ipType": 4,
        "placeholder1": 0,
        "placeholder2": 0,
        "port": 15107,
        "protocol": 4,
        "version": 7003001
      },
      "block_number": 4207460,
      "coldkey": {
        "hex": "0x143807a7dcfb4a7c4883110d7aa060d09de5dddd40a53be80c380842d63b374b",
        "ss58": "5CXDTb3cSxSvhfdB7Xk7hzxRkwKdCi2AZhvKFejtJvD5EwxS"
      },
      "consensus": "0.00425726710917830167",
      "daily_reward": "33000820",
      "dividends": "0",
      "emission": "1650041",
      "hotkey": {
        "hex": "0xfef49a2e2487dccef370fb090a7723f5a0673ee4e30cc568c7a8f4701583711d",
        "ss58": "5HpzgWFbyJX7DnauCnSzrRroPxmYiv8azwXGWwZMiRUwHsBP"
      },
      "incentive": "0.00421149004348821241",
      "is_child_key": false,
      "is_immunity_period": false,
      "netuid": 15,
      "rank": 0,
      "registered_at_block": 4157209,
      "stake": "0",
      "timestamp": "2024-11-06T15:33:24.001Z",
      "trust": "0.97795071335927367056",
      "uid": 123,
      "updated": 467707,
      "validator_permit": false,
      "validator_trust": "0"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "per_page": 2,
    "prev_page": null,
    "total_items": 5205444,
    "total_pages": 2602722
  }
}
```

**Response details**

```text
{
      "hotkey": {
        "ss58": "5CAQhe9pWMe9anWX9qbK6Z9RydRth7S6WDopapSr6uShGum5",
        "hex": "0x0459b8ac46933d4cbbd4f0b36934704e7a726851b359ca2ee8d5e704a8896e02"
      },
      "coldkey": {
        "ss58": "5F4kLq8YVzHYj8uv41BUB9ocqTGxAJECeDbYfcqJFKqAhSMj",
        "hex": "0x84bd11456ecf5f3abcfc983232f3fb2d97bcd2cf05657852774d15a1cea2f366"
      },
      "netuid": 19,
      "uid": 142, neuron id
      "block_number": 5453670,
      "timestamp": "2025-04-28T23:27:36Z",
      "stake": "0", not used
      "trust": "0", trust of neuron
      "validator_trust": "0.98783855954833295186", neuron vtrust
      "consensus": "0", neuron consensus
      "incentive": "0", neuron incentive
      "dividends": "0.25934233615625238422", neuron dividends
      "emission": "38386670943", neuron emission in rao per epoch
      "active": true, 
      "validator_permit": true,
      "updated": 71,
      "daily_reward": "767733418860", daily reward in rao
      "registered_at_block": 4112860,
      "is_immunity_period": false,
      "rank": 1,
      "is_child_key": true,
      "axon": null,
      "root_weight": "0.17999999999999999996",
      "alpha_stake": "192498557725397", alpha stake as rao
      "root_stake": "1209153325609965", root stake as rao
      "root_stake_as_alpha": "217647598609794.74000000000000", weighted root stake as rao
      "total_alpha_stake": "410146156335191.74000000000000" total alpha stake as rao
    },
```

### Other responses

| Status | Meaning |
| --- | --- |
| `400` | Bad request |
| `404` | Metagraph history not found |
| `500` | Internal server error |

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