# Rate Limits

Yes. Rate limits vary by plan and may also depend on the endpoint type (REST vs WebSocket).

Arkham API endpoints generally fall into two categories:

  Standard
  Most endpoints, with small burst allowance
  **20 requests/second**

  Heavy
  Resource-intensive endpoints
  **1 request/second**

Both limits can be **scaled up** under custom API plans.

### Heavy Endpoints

The following endpoints are resource-intensive and subject to the lower **1 request/second** limit:

| Endpoint |
| --- |
| `GET /transfers` |
| `GET /transfers/unenriched` |
| `GET /transfers/histogram` |
| `GET /swaps` |
| `GET /token/top` |
| `GET /token/top_flow/{id}` |
| `GET /token/top_flow/{chain}/{address}` |
| `GET /token/volume/{id}` |
| `GET /token/volume/{chain}/{address}` |
| `GET /intelligence/search` |
| `GET /counterparties/address/{address}` |
| `GET /counterparties/entity/{entity}` |
| `GET /flow/address/{address}` |
| `GET /flow/entity/{entity}` |

All other endpoints fall under the **Standard** limit.

## Increasing Your Limits

If you need higher limits for a specific endpoint or across your entire plan, contact [api@arkm.com](mailto:api@arkm.com).

## What Happens When You Hit Limits

If you exceed your limit, requests are rejected with:

- **HTTP 429** (Too Many Requests)
- A "too many requests" error response

## Avoiding Rate Limits

Best practices for staying within limits:

1. **Cache** responses when possible
2. **Paginate correctly** (don't repeatedly hit the first page)
3. Use **bulk endpoints** where available
4. Implement **retries with exponential backoff + jitter** on 429

### Backoff Example (Python)

```python
import time
import random
import requests

def request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code == 429:
            # Get retry delay from header, or use exponential backoff
            retry_after = int(resp.headers.get('Retry-After', 2 ** attempt))
            # Add jitter to prevent thundering herd
            jitter = random.uniform(0, 1)
            time.sleep(retry_after + jitter)
            continue
        return resp
    raise Exception("Max retries exceeded")
```

::: tip
Always add jitter to your backoff delays to prevent synchronized retry storms.
:::

## Intel Label Limits

In addition to per-second rate limits, the API enforces **label limits** that cap the number of unique labeled addresses you can look up per billing period.

A "label lookup" is a unique blockchain address for which Arkham returns proprietary intelligence data (entity labels, tags, etc.). Repeated lookups of the same address within a billing period count only once.

  Trial
  Free trial accounts
  **10,000 label lookups/period**

  Individual
  Paying individual plans
  **1,000,000 label lookups/period**

  Organization
  Paying org plans, per seat
  **10,000,000 label lookups/period/seat**

These limits can be **increased** upon request. Contact [api@arkm.com](mailto:api@arkm.com).

### Tracking Your Label Usage

Every API response from intelligence endpoints includes headers showing your current usage:

| Header | Description |
| --- | --- |
| `X-Intel-Datapoints-Usage` | Label lookups consumed so far this period |
| `X-Intel-Datapoints-Limit` | Your per-seat limit for this period |
| `X-Intel-Datapoints-Remaining` | Label lookups remaining before the limit is reached |

You can also check your usage programmatically:

```
GET /subscription/intel-usage
```

This authenticated endpoint returns your total count, per-seat limit, per-chain breakdown, and period start date.

### What Happens When You Reach Your Label Limit

Once your label limit is reached, intelligence requests are rejected with:

- **HTTP 429** (Too Many Requests)
- Message: `"Intelligence label lookup limit reached for this billing period."`

Other endpoints that don't return intel label data (price data, etc.) are **not affected** by label limits.

::: tip
You can request an increase to your label limit at any time by contacting api@arkm.com or through the "Request More" button on your API Dashboard.
:::