---
title: Rate limits and API keys
description: Limits on Thru's public RPC and data endpoints, how to get a free
  API key, and how to send it.
source_url:
  html: https://thru.org/docs/api-ref/rate-limits/
  md: https://thru.org/docs/api-ref/rate-limits.md
---

# Rate limits and API keys

Thru’s public endpoints (`rpc.betanet.thru.org` and `data.thru.org`) accept requests without an API key at a low limit. A free API key gives your organization its own, higher limit.

## Limits

| Caller | Requests | Response bytes |
| - | - | - |
| Without an API key | 10 weighted requests/s per IP address | 5 MiB/s per IP address |
| With an API key | 100 weighted requests/s per organization (default) | 5 MiB/s per organization (default) |

- **Weighted requests.** Each method costs a fixed weight.

  - Most methods cost 1.
  - Single account, transaction and event lookups cost 2.
  - Block lookups, list and batch methods cost 10.
  - `DebugReExecute` costs 50.
  - So without a key, `ListTransactions` is limited to one call per second.

- **Response bytes** are counted only for streams and expensive methods.

- **Organization limits.** All keys in an organization share its limit. See yours in [Thru Developers](https://dev.thru.org/organization) under the info button next to **API keys**.

## Get a key

1. Open [dev.thru.org/keys](https://dev.thru.org/keys?ref=docs) and sign in with GitHub, Google or X.
2. Name the key and create it.
   - Optionally, restrict it to your browser origins.
3. Copy it. It is shown once and looks like `thru_` followed by 32 letters and digits.

Keep keys out of source control and client bundles unless you’ve restricted them to your origins.

## Send the key

Send the key as a bearer token on every request. This works for gRPC, gRPC-Web, Connect and REST:

```http
Authorization: Bearer thru_...
```

- **CLI:**

  - Run `thru auth login`. It creates a key and uses it automatically with the official RPC endpoints.
  - Or set `THRU_API_KEY`.

- **TypeScript SDK:** pass `createThruClient({ apiKey: process.env.THRU_API_KEY })`.

- **AI agents:** run `thru auth keys create --name <name> --agent <client>` to create a key and install it for the [Thru MCP](https://thru.org/docs/api-ref/thru-mcp/overview.md). Its tool calls count against your organization’s limits.

- **grpcurl:**

  ```bash
  grpcurl -H "authorization: Bearer $THRU_API_KEY" rpc.betanet.thru.org:443 thru.services.v1.QueryService/GetHeight
  ```

## When you hit a limit

| Protocol | Response |
| - | - |
| gRPC, gRPC-Web, Connect | Status `RESOURCE_EXHAUSTED` (8) |
| Other HTTP | `429 Too Many Requests` with a JSON body |

Every rate-limited response has these headers:

- `retry-after: 1`
- `x-ratelimit-limit`
- `x-ratelimit-remaining`

Without a key, the message names the per-IP limit you hit (weighted requests, or response bytes) and links here:

```text
rate limit for requests without an API key exceeded (10 weighted requests/s per IP). Get a free key with higher limits at https://dev.thru.org/keys?ref=edge-429 and send it as "Authorization: Bearer thru_...". Docs: https://thru.org/docs/api-ref/rate-limits/
```

The JSON body adds `get_key_url` and `docs_url`:

```json
{
  "error": {
    "code": "resource_exhausted",
    "message": "rate limit for requests without an API key exceeded (...)",
    "get_key_url": "https://dev.thru.org/keys?ref=edge-429",
    "docs_url": "https://thru.org/docs/api-ref/rate-limits/"
  }
}
```

The SDKs throw a typed error you can check for:

- **TypeScript:** `ThruRateLimitError`, which has `getKeyUrl`, `keyed` and `retryAfterSeconds`.
- **Rust:** `ClientError::RateLimited`.

Wait at least `retry-after` seconds before retrying, and back off if the denials continue.

Responses to requests without a key also carry `link: <https://dev.thru.org/keys?ref=edge>; rel="help"`.

A region-wide ceiling protects the network as a whole and applies with or without a key. When a request is denied by it, the message is `rate limit exceeded`, with no key link.

With a key, the message is `rate limit exceeded`. The limit is your organization’s (or the key’s own cap, if Thru has set one).

A key that is unknown or revoked returns `UNAUTHENTICATED` (401). A key used from an origin outside its allowlist returns `PERMISSION_DENIED` (403).
