> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Every endpoint allows a fixed number of requests per minute, for each organization or, on GET /key, for each key.

## Limits

| Endpoint | Limit | Counted per |
| - | - | - |
| `GET /credits` | 10 requests per minute | Organization |
| `GET /key` | 10 requests per minute | Key |
| `GET /activity` | 10 requests per minute | Organization |

* `GET /credits` and `GET /activity` each have one budget per organization: all of your management keys share it, and using one endpoint never spends another's.
* `GET /key` gives every key a budget of its own, so one application checking its key never slows down another.
* Each window is one calendar minute (UTC): the count starts over at the top of every minute.
* Every request that passes the key checks counts, including ones refused with `400` or `429`. A request refused with `401` or `403` never reaches the limit.
* These figures change slowly, so one read a minute is plenty for dashboards and alerts. Cache responses rather than polling.

## Rate-limit headers

Every response to a request that counts, successful or not, carries the current window:

**X-RateLimit-Limit** `integer`

Requests allowed per minute.

**X-RateLimit-Remaining** `integer`

Requests left in the current minute.

**X-RateLimit-Reset** `integer`

When the current minute's window ends, as a Unix timestamp in seconds.

**Retry-After** `integer`

On a `429` only: seconds until the window ends.

## Rate-limited responses

Over the limit, the API answers `429 Too Many Requests` with a `Retry-After` header and this body:

```json theme={null}
{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Please try again later."
  }
}
```

## Retry handling

Wait for `Retry-After` instead of retrying immediately: until the window ends, every request is refused and still counts.

```python Python theme={null}
import os
import time
import requests

def get_with_retry(url, headers, params=None, max_attempts=5):
    for _ in range(max_attempts):
        response = requests.get(url, headers=headers, params=params)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "1")))
    return response

activity = get_with_retry(
    "https://api.platform.pearlresearch.ai/api/v1/activity",
    headers={"Authorization": f"Bearer {os.environ['PEARL_MANAGEMENT_KEY']}"},
    params={"date": "2026-11-14"},
)
```

```typescript TypeScript theme={null}
async function getWithRetry(url: string, init: RequestInit, maxAttempts = 5) {
  let response = await fetch(url, init);
  for (let attempt = 1; attempt < maxAttempts && response.status === 429; attempt++) {
    const seconds = Number(response.headers.get("Retry-After") ?? "1");
    await new Promise(resolve => setTimeout(resolve, seconds * 1000));
    response = await fetch(url, init);
  }
  return response;
}

const activity = await getWithRetry(
  "https://api.platform.pearlresearch.ai/api/v1/activity?date=2026-11-14",
  {headers: {Authorization: `Bearer ${process.env.PEARL_MANAGEMENT_KEY}`}},
);
```

## Higher limits

If your workload needs more, email [support@pearlresearch.ai](mailto:support@pearlresearch.ai) with your organization and the endpoints you call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.