# Getting started with the taostats API

From an API key to your first response in a few minutes: authentication, a first request in curl, JavaScript and Python, pagination, and four endpoints to try first.

_Source: https://beta.taostats.io/blog/getting-started-with-the-taostats-api_  
_Author: taostats Team, Editorial_  
_Published: 2026-09-21_  
_Category: Guides_  
_Tags: API, Data, Developers, SDK_

The taostats API gives you the data behind the explorer, as JSON over plain HTTP: subnets, validators, metagraphs, pools, prices and more. This guide takes you from nothing to a first response, then through the patterns you need for real code.

It is a read-only API. You can look at accounts and balances, blocks and extrinsics, subnet configuration, validators and miners, dTAO pools and prices, but you cannot sign or send a transaction through it. That keeps the mental model simple: every call is a question about the state of the network, and every response is an answer you can cache, store or chart however you like.

## What you can build

Because it is the same data that powers the explorer, most projects fall into one of three shapes.

- **Dashboards and alerts.** Poll the latest endpoints for the figures you care about, such as a subnet's emission or a validator's stake, then chart them or notify yourself when they cross a threshold.
- **Research notebooks.** Many endpoints come in a latest and a history variant. Pull the history into a notebook or a spreadsheet to study how prices, emissions and registrations have moved over time.
- **Bots and integrations.** Feed subnet data into a chat bot, a portfolio tracker or a tool of your own. If you automate anything that moves money, be careful: the API describes the state of the chain, but it cannot stop you acting on a stale or misread number.

## 1. Get a key

1. **Sign up** at [taostats.io/pro](https://beta.taostats.io/pro) with Google, GitHub or an email address.
2. **Create an API key** from your dashboard. Treat it like a password.
3. **Store it in an environment variable**, and keep it out of source control.

> [!WARNING]
> **No Bearer prefix**
>
> The key goes in the `Authorization` header exactly as it is, with no `Bearer` prefix and no quotes. A wrongly formatted header is the most common cause of a 401 or 403 response.

## 2. Make your first request

Every endpoint lives under the base URL https://api.taostats.io/api/ and the paths in the reference are relative to it. A good first call is the latest subnet snapshot, which returns each subnet's configuration, emission metrics and participant counts. Ask for five subnets to keep the response small.

**curl**

```bash
curl -H "Authorization: $TAOSTATS_API_KEY" \
  "https://api.taostats.io/api/subnet/latest/v1?limit=5"
```

**JavaScript**

```js title="subnets.mjs"
const response = await fetch(
  'https://api.taostats.io/api/subnet/latest/v1?limit=5',
  { headers: { Authorization: process.env.TAOSTATS_API_KEY } }
);

if (!response.ok) {
  throw new Error('Request failed with status ' + response.status);
}

const { pagination, data } = await response.json();
console.log('Page ' + pagination.current_page + ' of ' + pagination.total_pages);

for (const subnet of data) {
  console.log(subnet.netuid, subnet.active_validators, subnet.active_miners);
}
```

**Python**

```python title="subnets.py"
import os

import requests

response = requests.get(
    "https://api.taostats.io/api/subnet/latest/v1",
    params={"limit": 5},
    headers={"Authorization": os.environ["TAOSTATS_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

for subnet in response.json()["data"]:
    print(subnet["netuid"], subnet["active_validators"], subnet["active_miners"])
```

## 3. Understand the response

Every list endpoint returns the same envelope: a `data` array and a `pagination` block.

```json title="response-shape.json"
{
  "pagination": {
    "current_page": 1,
    "per_page": 5,
    "total_items": 5,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  },
  "data": []
}
```

Once you have seen the envelope on one endpoint you have seen it on all of them, which makes it easy to write a single helper that fetches a page, checks the status and hands back the data. Three habits will save you time when you do.

- **Paginate.** Use `page` and `limit` to walk through results; the maximum page size is 200. Follow `next_page` until it is null.
- **Parse numbers carefully.** Many values, such as prices and emissions, arrive as strings so that no precision is lost. Use a decimal-aware type when you do arithmetic on them.
- **Convert units.** Token amounts are in RAO, the smallest unit. One TAO is 1,000,000,000 RAO, so divide before you display anything.

## 4. Narrow the request

Most endpoints accept filters, and using them is the difference between a script that takes a second and one that downloads the whole network. The subnet snapshot, for instance, takes a `netuid` to fetch one subnet and an `order` to sort the results, with options such as `emission_desc` for the subnets that emit the most. The pool endpoint can be sorted by liquidity, price or rank in the same way, and the metagraph endpoint can be filtered by hotkey, coldkey, validator permit and more.

A call for the ten subnets with the largest emission is then a single line:

```bash
curl -H "Authorization: $TAOSTATS_API_KEY" \
  "https://api.taostats.io/api/subnet/latest/v1?order=emission_desc&limit=10"
```

Each endpoint page in the reference lists the parameters it accepts, and the Try it panel on every GET page lets you run a request from your browser with your own key before you write any code.

## 5. Four endpoints worth knowing first

| You want to know                                  | Call                                    |
| ------------------------------------------------- | --------------------------------------- |
| The current TAO price                             | `GET /api/price/latest/v1?asset=tao`    |
| How subnets are configured and how much they emit | `GET /api/subnet/latest/v1`             |
| A subnet's pool price, reserves and fee           | `GET /api/dtao/pool/latest/v1?netuid=`  |
| Who is on a subnet, and how they are performing   | `GET /api/metagraph/latest/v1?netuid=`  |

The pool endpoint pairs well with our [field guide to subnet prices](https://beta.taostats.io/blog/a-field-guide-to-reading-subnet-prices-after-dtao), and the metagraph endpoint with [our look at validator weights](https://beta.taostats.io/blog/what-validator-weights-tell-you-about-a-subnet).

The endpoints combine well. A common first project is to take the subnet snapshot for a list of subnets, fetch the pool for each one, and join them on the subnet number to see emission next to price and depth. Because both responses are paginated in the same way, the join is a few lines of code in any language.

## 6. Be a good API citizen

- **Respect rate limits.** Limits depend on your plan. When you exceed yours the API returns `429 Too Many Requests`; wait for the time given in the `Retry-After` header before you retry.
- **Cache what you can.** The latest endpoints describe the chain tip. Reuse a response for a few seconds instead of polling in a tight loop.
- **Keep the key on the server.** Never ship it in browser code or a mobile app, where anyone can read it.

Wrap your calls in one small helper rather than repeating the same checks everywhere. It should confirm the status code, parse the body, and decide what to do about a failure. A rate-limit response is worth retrying after the delay the server asks for, with a cap on the number of attempts so a bad day does not turn into an infinite loop. A server error deserves a retry with a short, growing pause. Anything else, such as a bad parameter or a rejected key, will not fix itself and should surface as an error straight away. When you log a failure, record the status and the path, and never the key.

> [!TIP]
> **Prefer typed code or an AI assistant?**
>
> TypeScript developers can use the `@taostats/sdk` package, which wraps the API and adds direct RPC access to the chain. If you are building with an AI assistant, the taostats MCP server lets it call the same endpoints for you.

## Which tool should I use?

Start with curl or the Try it panel while you are exploring, because you see exactly what comes back. Move to plain HTTP calls in the language you already use when you know what you need. Reach for the TypeScript SDK if you want typed responses and do not want to hand-write the request code, and for the MCP server if the thing asking the questions is an AI assistant rather than your own program. They all talk to the same data, so you can mix them freely as a project grows.

## If something goes wrong

A 401 or 403 almost always means the `Authorization` header is wrong. A 429 means you are over your limit. A 404 usually means the path is missing the `/api/` prefix or the `/v1` version suffix. Everything else is covered in the quickstart.

## Next steps

- [API quickstart](https://beta.taostats.io/docs/api-reference/quickstart) — The same walkthrough in reference form, with troubleshooting.
- [Endpoint reference](https://beta.taostats.io/docs/api-reference) — Every endpoint, with a Try it panel on each GET page.
- [TypeScript SDK](https://beta.taostats.io/docs/start-here/typescript-sdk) — Typed access to the API and to the chain.
- [Model Context Protocol](https://beta.taostats.io/docs/start-here/model-context-protocol-mcp) — Give an AI assistant live access to Bittensor data.