Neuron history

Description

Returns time-series metagraph snapshots for one or more neurons. Each row carries the same per-neuron fields as /api/neuron/latest/v1 — hotkey, coldkey, registration block, immunity/danger/active flags, and the Yuma metrics (incentive, mech_incentive, consensus, trust, validator_trust, dividends, emission, pruning_score, validator_permit) — sampled at successive blocks.

Filter by netuid, uid, hotkey, or coldkey to fix a neuron, and by block_start/block_end or timestamp_start/timestamp_end to bound the window. Use this to plot a neuron’s incentive/consensus/dividends trajectory or reconstruct historical metagraph state.

Endpoint

GET /api/neuron/history/v1

Parameters

Name	In	Type	Required	Description
netuid	query	integer		Subnet ID
uid	query	integer		Neuron ID
hotkey	query	string		SS58 or hex format
coldkey	query	string		SS58 or hex format
is_immune	query	boolean		Start of block range (inclusive) Is immune
in_danger	query	boolean		Is in danger
has_dividends	query	boolean		Has dividends
has_incentive	query	boolean		Has incentive
block_start	query	integer
block_end	query	integer		End of block range (inclusive)
timestamp_start	query	integer		Start of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive)
timestamp_end	query	integer		End of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive)
page	query	integer
limit	query	integer
order	query	—

Responses

200 — Neuron history retrieved successfully

Media: application/json

Schema

{
  "type": "object",
  "required": [
    "pagination",
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "block_number",
          "timestamp",
          "netuid",
          "uid",
          "hotkey",
          "coldkey",
          "registration_block",
          "is_immune",
          "in_danger",
          "active",
          "consensus",
          "dividends",
          "emission",
          "incentive",
          "mech_incentive",
          "pruning_score",
          "trust",
          "validator_permit",
          "validator_trust"
        ],
        "properties": {
          "active": {
            "type": "boolean"
          },
          "axon": {
            "type": "string",
            "nullable": true
          },
          "block_number": {
            "type": "integer",
            "format": "int32"
          },
          "coldkey": {
            "type": "object",
            "required": [
              "ss58",
              "hex"
            ],
            "properties": {
              "hex": {
                "type": "string",
                "description": "The hex format of the hot key"
              },
              "ss58": {
                "type": "string",
                "description": "The SS58 format of the hot key"
              }
            }
          },
          "consensus": {
            "type": "string"
          },
          "dividends": {
            "type": "string"
          },
          "emission": {
            "type": "string"
          },
          "hotkey": {
            "type": "object",
            "required": [
              "ss58",
              "hex"
            ],
            "properties": {
              "hex": {
                "type": "string",
                "description": "The hex format of the hot key"
              },
              "ss58": {
                "type": "string",
                "description": "The SS58 format of the hot key"
              }
            }
          },
          "in_danger": {
            "type": "boolean"
          },
          "incentive": {
            "type": "string"
          },
          "is_immune": {
            "type": "boolean"
          },
          "mech_incentive": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "miner_rank": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "netuid": {
            "type": "integer",
            "format": "int32"
          },
          "pruning_score": {
            "type": "string"
          },
          "registration_block": {
            "type": "integer",
            "format": "int32"
          },
          "stake_weight": {
            "type": "string",
            "nullable": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "trust": {
            "type": "string"
          },
          "uid": {
            "type": "integer",
            "format": "int32"
          },
          "validator_permit": {
            "type": "boolean"
          },
          "validator_rank": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "validator_trust": {
            "type": "string"
          }
        }
      }
    },
    "pagination": {
      "type": "object",
      "required": [
        "current_page",
        "per_page",
        "total_items",
        "total_pages"
      ],
      "properties": {
        "current_page": {
          "type": "integer",
          "format": "int32"
        },
        "next_page": {
          "type": "integer",
          "format": "int32",
          "nullable": true
        },
        "per_page": {
          "type": "integer",
          "format": "int32"
        },
        "prev_page": {
          "type": "integer",
          "format": "int32",
          "nullable": true
        },
        "total_items": {
          "type": "integer",
          "format": "int32"
        },
        "total_pages": {
          "type": "integer",
          "format": "int32"
        }
      }
    }
  }
}

400 — Bad request

404 — Neuron history not found

500 — Internal server error

Try it

Interactive request console coming soon. In the meantime you can use the OpenAPI spec with any client (Insomnia, Bruno, Scalar, curl).

Authentication

All Taostats API requests require an Authorization header containing your API key. See Getting Started.