# API Quickstart

Get a Taostats API key, authenticate, and make your first request to the Taostats API at api.taostats.io/v1.

_Source: https://taostats.io/docs/new/quickstart_

_Last reviewed: 2026-10-12_

The Taostats API is a read-only HTTP API over the Bittensor network: accounts, alpha positions, subnets and pools, validators, miners, chain records, EVM, OTC, prices, tax reports and live RPC. This page gets you from zero to your first successful request in a couple of minutes.

## 1. Get an API key

Sign up and create a key in [Taostats Pro](https://taostats.io/pro/api-keys). A free tier is available; paid tiers raise the rate limits. [Getting started with the Taostats API](https://taostats.io/docs/start-here/getting-started-with-taostats-api) walks through sign-up step by step.

## 2. Authenticate

Every request carries your API key, whole, in the `Authorization` header — no `Bearer` prefix, no other scheme:

```
Authorization: <YOUR_API_KEY>
```

A browser or WebSocket client that cannot set headers can pass the same key as the `?authorization=` query parameter instead.

## 3. Base URL

```
https://api.taostats.io/v1
```

Every endpoint path in this reference starts with `/v1/`. The endpoint listed as `/v1/subnets/pools` is reached at `https://api.taostats.io/v1/subnets/pools`.

## 4. Your first request

Fetch the latest pool snapshot for five subnets:

```bash
curl -H "Authorization: <YOUR_API_KEY>" \
  "https://api.taostats.io/v1/subnets/pools?limit=5"
```

The response is a JSON object with a `data` array (one row per subnet: `netuid`, `price`, `tao_in_pool`, `alpha_in_pool`, `alpha_staked` and more) and a `pagination` block.

## 5. Paging and filtering

Collection endpoints share the same controls:

- `page` (1-indexed, default 1) and `limit` (default 50, maximum 200). `pagination` in the response reports `current_page`, `next_page`, `prev_page`, `per_page`, `total_items` and `total_pages`; `next_page` is `null` on the last page.
- `order_by` and `order_dir` (`asc` or `desc`). Each endpoint lists the columns it can sort by.
- Range filters such as `block_start`/`block_end` and `timestamp_start`/`timestamp_end` (Unix seconds) on history endpoints. `(page − 1) × limit` must stay below 1,000,000, so reach deep history with a range filter rather than a high page number.

Amounts in TAO and alpha come back in RAO as decimal strings (1 TAO = 10⁹ RAO), so they never lose precision in a JSON number.

## 6. Errors

Every failure returns the same JSON body:

```json
{ "status_code": 400, "message": "…" }
```

## 7. Rate limits

Rate limits depend on your plan. See your tier, quota and usage on the [billing dashboard](https://taostats.io/pro/billing). Over quota, the API returns `429 Too Many Requests`.

## 8. Explore the endpoints

- [API reference overview](https://taostats.io/docs/new): every endpoint, organised by group.
- Use the sidebar to jump straight to a group: Accounts, Alpha positions, Subnets, Validators, Miners, Chain, Network, EVM, OTC, Price, Tax, RPC and more.
- [OpenAPI spec](https://api.taostats.io/openapi.json): the machine-readable spec this reference is generated from.

## Troubleshooting

- **401 / 403**: check the `Authorization` header carries your key exactly as issued, with no `Bearer` prefix and no quotes.
- **404 on an endpoint path**: check the path starts with `/v1/`. Paths of the form `/api/<name>/v1` belong to the previous API, which is retired on November 9, 2026.
- **400**: a query parameter is out of range or not one the endpoint accepts. `message` says which.
- **429**: you've hit your rate limit. Back off and retry, or move to a higher plan.