> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://documents.pyramid-ai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documents.pyramid-ai.com/_mcp/server.

# Rate Limits

The Pyramid API enforces per-key rate limits to ensure fair usage and system stability.

## Default limits

| Limit               | Default        | Scope            |
| ------------------- | -------------- | ---------------- |
| Requests per minute | 100            | Per API key      |
| Monthly request cap | Varies by plan | Per organization |
| Monthly token cap   | Varies by plan | Per organization |

Custom rate limits can be configured per key during provisioning.

## Rate limit headers

Every API response includes rate limit information:

| Header                  | Description                               | Example      |
| ----------------------- | ----------------------------------------- | ------------ |
| `X-RateLimit-Limit`     | Max requests per minute for this key      | `100`        |
| `X-RateLimit-Remaining` | Requests remaining in current window      | `97`         |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets     | `1713100800` |
| `Retry-After`           | Seconds to wait (only on `429` responses) | `42`         |

## Handling rate limits

When you exceed the rate limit, the API returns a `429` status code:

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 42 seconds."
  },
  "request_id": "..."
}
```

### Recommended retry strategy

Use exponential backoff with the `Retry-After` header:

```python
import time
import requests

def call_api(url, headers, body, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=body)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")
```

## Quota limits

Organizations have monthly caps on total requests and LLM tokens. When a quota is exceeded, the API returns `402`:

```json
{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly token quota exceeded. Contact your account manager to increase limits."
  },
  "request_id": "..."
}
```

> **Note**
>
> Quota usage resets on the 1st of each month at 00:00 UTC.

## Tips for staying within limits

* **Batch operations** — use batch endpoints (e.g., `POST /agent/batches`) instead of many individual calls
* **Cache responses** — cache results client-side where appropriate
* **Use idempotency keys** — prevent duplicate processing on retries (see [Error Handling](/error-handling))
* **Monitor usage** — check `X-RateLimit-Remaining` headers proactively