Documentation / New API reference / Validators

Post Validators Yield

Reference

Last reviewed 2026-10-07

POST

https://api.taostats.io/v1/validators/yieldAPI key required

Bulk yield for specific (hotkey, netuid) positions.

Code samples

bash

curl -X POST \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      {
        "hotkey": "string",
        "netuid": 0
      }
    ]
  }' \
  "https://api.taostats.io/v1/validators/yield"

const response = await fetch('https://api.taostats.io/v1/validators/yield', {
  method: 'POST',
  headers: {
    Authorization: '<YOUR_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "positions": [
      {
        "hotkey": "string",
        "netuid": 0
      }
    ]
  }),
});
const data = await response.json();

python

import requests

response = requests.post(
    "https://api.taostats.io/v1/validators/yield",
    headers={"Authorization": "<YOUR_API_KEY>"},
    json={
      "positions": [
        {
          "hotkey": "string",
          "netuid": 0
        }
      ]
    },
)
data = response.json()

Parameters

No parameters.

Request body

Field	Type	Required	Description
`limit`	`integer (int32), nullable`		Results per page. Default: 50. Max: 200.
`min_stake`	`integer (int64), nullable`		Minimum stake filter (u64 rao).
`order_by`	`string, nullable`		Column to order by. Default: `stake`. One of `stake`, `netuid`, `name`, `one_hour_apy`, `one_day_apy`, `seven_day_apy`, `thirty_day_apy`.
`order_dir`	`string, nullable`		Sort direction. Default: `desc`. One of `asc`, `desc`.
`page`	`integer (int32), nullable`		Page number (1-indexed). Default: 1. Bounded window: `(page − 1) × limit` must be below 1,000,000. Deep `OFFSET` paging is linear in the offset, so an uncapped `page` lets one request scan tens of millions of rows; a page past the window is rejected with a 400. Reach deeper history with this endpoint's range filters (`block_start`/`block_end`, `timestamp_start`/`timestamp_end`) rather than a larger `page`.
`positions`	`array`	Yes	`(hotkey, netuid)` positions to fetch yield for. Required, non-empty.
`positions[].hotkey`	`string`	Yes	Validator hotkey (SS58 or 0x-hex).
`positions[].netuid`	`integer (int32)`	Yes	Subnet ID.

json

{
  "positions": [
    {
      "hotkey": "string",
      "netuid": 0
    }
  ]
}

Responses

`200` — Paginated validator yield

Field	Type	Required	Description
`data`	`array`	Yes
`data[].block_number`	`integer (int32)`	Yes
`data[].hotkey`	`string`	Yes	Validator hotkey (SS58).
`data[].name`	`string, nullable`	Yes	On-chain account identity display name (from `IdentitiesV2`, joined by coldkey). `null` when the coldkey has no identity set.
`data[].netuid`	`integer (int32)`	Yes
`data[].one_day_apy`	`number (double)`	Yes
`data[].one_day_epoch_participation`	`number (double), nullable`	Yes
`data[].one_hour_apy`	`number (double)`	Yes
`data[].seven_day_apy`	`number (double)`	Yes
`data[].seven_day_epoch_participation`	`number (double), nullable`	Yes
`data[].stake`	`string`	Yes	Stake (`total_hotkey_alpha`), u64 rao as a decimal string.
`data[].thirty_day_apy`	`number (double)`	Yes
`data[].thirty_day_epoch_participation`	`number (double), nullable`	Yes
`data[].timestamp`	`string`	Yes	ISO 8601 snapshot timestamp.
`pagination`	`object`	Yes	Pagination metadata appended to collection responses. `next_page` / `prev_page` are explicitly required+nullable in the OpenAPI spec: per `docs/api_standards.md` we emit `null` rather than omitting the field, so the SDK should model them as `Option`/nullable types that are always present in the response. `total_items` is the exact number of matching rows on every route (issue #992). It used to stop at 1,000,000, which reported a million transfers when finney holds 7,513,252 and a million events when the real figure is 981,179,110; the cap was removed on 29 Sep 2026 and nothing may reintroduce one — `crate::pagination::exact_count_sql` is the only count form, and `no_capped_count_reaches_the_api_surface` in `data-debug-scripts` fails the build if a capped one comes back. `total_pages` is still bounded, to `crate::pagination::max_reachable_page(per_page)`, because the `page` parameter is capped to a 1,000,000-row window: deep `OFFSET` paging reads every skipped row (24.7M rows / 36.6 GiB / 42 s measured on one endpoint, issue #413). So `total_pages` is exactly the last page this API will serve and `next_page` / `prev_page` stay coherent at the window edge, while `total_items` tells the caller how many rows there really are. History beyond the window is reached with each endpoint's range filters, not a larger `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 parameter or malformed JSON body

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

`413` — Request body exceeds the size limit

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

`415` — Content type is not application/json

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.

Was this page helpful?

Documentation / New API reference / Validators

Post Validators Yield

Reference

Last reviewed 2026-10-07

POST

https://api.taostats.io/v1/validators/yieldAPI key required

Bulk yield for specific (hotkey, netuid) positions.

Code samples

bash

curl -X POST \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      {
        "hotkey": "string",
        "netuid": 0
      }
    ]
  }' \
  "https://api.taostats.io/v1/validators/yield"

const response = await fetch('https://api.taostats.io/v1/validators/yield', {
  method: 'POST',
  headers: {
    Authorization: '<YOUR_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "positions": [
      {
        "hotkey": "string",
        "netuid": 0
      }
    ]
  }),
});
const data = await response.json();

python

import requests

response = requests.post(
    "https://api.taostats.io/v1/validators/yield",
    headers={"Authorization": "<YOUR_API_KEY>"},
    json={
      "positions": [
        {
          "hotkey": "string",
          "netuid": 0
        }
      ]
    },
)
data = response.json()

Parameters

No parameters.

Request body

Field	Type	Required	Description
`limit`	`integer (int32), nullable`		Results per page. Default: 50. Max: 200.
`min_stake`	`integer (int64), nullable`		Minimum stake filter (u64 rao).
`order_by`	`string, nullable`		Column to order by. Default: `stake`. One of `stake`, `netuid`, `name`, `one_hour_apy`, `one_day_apy`, `seven_day_apy`, `thirty_day_apy`.
`order_dir`	`string, nullable`		Sort direction. Default: `desc`. One of `asc`, `desc`.
`page`	`integer (int32), nullable`		Page number (1-indexed). Default: 1. Bounded window: `(page − 1) × limit` must be below 1,000,000. Deep `OFFSET` paging is linear in the offset, so an uncapped `page` lets one request scan tens of millions of rows; a page past the window is rejected with a 400. Reach deeper history with this endpoint's range filters (`block_start`/`block_end`, `timestamp_start`/`timestamp_end`) rather than a larger `page`.
`positions`	`array`	Yes	`(hotkey, netuid)` positions to fetch yield for. Required, non-empty.
`positions[].hotkey`	`string`	Yes	Validator hotkey (SS58 or 0x-hex).
`positions[].netuid`	`integer (int32)`	Yes	Subnet ID.

json

{
  "positions": [
    {
      "hotkey": "string",
      "netuid": 0
    }
  ]
}

Responses

`200` — Paginated validator yield

Field	Type	Required	Description
`data`	`array`	Yes
`data[].block_number`	`integer (int32)`	Yes
`data[].hotkey`	`string`	Yes	Validator hotkey (SS58).
`data[].name`	`string, nullable`	Yes	On-chain account identity display name (from `IdentitiesV2`, joined by coldkey). `null` when the coldkey has no identity set.
`data[].netuid`	`integer (int32)`	Yes
`data[].one_day_apy`	`number (double)`	Yes
`data[].one_day_epoch_participation`	`number (double), nullable`	Yes
`data[].one_hour_apy`	`number (double)`	Yes
`data[].seven_day_apy`	`number (double)`	Yes
`data[].seven_day_epoch_participation`	`number (double), nullable`	Yes
`data[].stake`	`string`	Yes	Stake (`total_hotkey_alpha`), u64 rao as a decimal string.
`data[].thirty_day_apy`	`number (double)`	Yes
`data[].thirty_day_epoch_participation`	`number (double), nullable`	Yes
`data[].timestamp`	`string`	Yes	ISO 8601 snapshot timestamp.
`pagination`	`object`	Yes	Pagination metadata appended to collection responses. `next_page` / `prev_page` are explicitly required+nullable in the OpenAPI spec: per `docs/api_standards.md` we emit `null` rather than omitting the field, so the SDK should model them as `Option`/nullable types that are always present in the response. `total_items` is the exact number of matching rows on every route (issue #992). It used to stop at 1,000,000, which reported a million transfers when finney holds 7,513,252 and a million events when the real figure is 981,179,110; the cap was removed on 29 Sep 2026 and nothing may reintroduce one — `crate::pagination::exact_count_sql` is the only count form, and `no_capped_count_reaches_the_api_surface` in `data-debug-scripts` fails the build if a capped one comes back. `total_pages` is still bounded, to `crate::pagination::max_reachable_page(per_page)`, because the `page` parameter is capped to a 1,000,000-row window: deep `OFFSET` paging reads every skipped row (24.7M rows / 36.6 GiB / 42 s measured on one endpoint, issue #413). So `total_pages` is exactly the last page this API will serve and `next_page` / `prev_page` stay coherent at the window edge, while `total_items` tells the caller how many rows there really are. History beyond the window is reached with each endpoint's range filters, not a larger `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 parameter or malformed JSON body

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

`413` — Request body exceeds the size limit

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

`415` — Content type is not application/json

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.

Code samples

Parameters

Request body

Responses

200 — Paginated validator yield

400 — Invalid parameter or malformed JSON body

413 — Request body exceeds the size limit

415 — Content type is not application/json

500 — Internal server error

Was this page helpful?

Code samples

Parameters

Request body

Responses

200 — Paginated validator yield

400 — Invalid parameter or malformed JSON body

413 — Request body exceeds the size limit

415 — Content type is not application/json

500 — Internal server error

Was this page helpful?

`200` — Paginated validator yield

`400` — Invalid parameter or malformed JSON body

`413` — Request body exceeds the size limit

`415` — Content type is not application/json

`500` — Internal server error

`200` — Paginated validator yield

`400` — Invalid parameter or malformed JSON body

`413` — Request body exceeds the size limit

`415` — Content type is not application/json

`500` — Internal server error