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

# Rate Limits & Monthly Credits

> Request limits, monthly credit system, and retry guidance

## Per-Minute Rate Limit

Each API key is limited to **100 requests per minute** using a fixed-window counter. The window resets every 60 seconds.

## Monthly Credits

Every API key has a monthly credit allowance that varies by plan. Use `GET /v1/usage` to check your current request counts and remaining budget.

Some endpoints are available only on higher plans. In particular:

* Core lookup and monitoring endpoints are available broadly
* Brief endpoints require a higher plan
* Bulk feed and webhook endpoints are limited to higher-tier plans

## Response Headers

Every response includes rate limit and credit headers:

| Header                  | Description                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window (100)                                                                       |
| `X-RateLimit-Remaining` | Requests remaining in the current window                                                                |
| `X-Monthly-Limit`       | Total credits for the billing month                                                                     |
| `X-Monthly-Used`        | Credits consumed so far this month                                                                      |
| `X-Monthly-Remaining`   | Credits remaining this month                                                                            |
| `X-Credit-Cost`         | Credit cost for the current request                                                                     |
| `X-Plan-Tier`           | Plan tier attached to the API key                                                                       |
| `X-Api-Surface`         | Route packaging surface such as `lookup`, `query`, `feed`, `timeline`, `replay`, `brief`, or `delivery` |
| `X-Access-Layer`        | Access layer such as `evaluation`, `operational`, or `premium`                                          |
| `X-Endpoint-Policy`     | Stable internal policy label for the endpoint (for example `search` or `radar.all`)                     |
| `X-Request-Id`          | Unique identifier for the request (useful for support)                                                  |

## Access Layers

Shoal’s pricing and access model is intentionally tied to route type, not just raw request count:

* `evaluation` routes are the safest entry points for new integrations
* `operational` routes are higher-value workflow surfaces
* `premium` routes expose bulk feed or delivery capabilities and are more tightly gated

Typical examples:

* `evaluation`: `/v1/search`, `/v1/entities/byName`, `/v1/signal/top`
* `operational`: `/v1/brief`, `/v1/brief/batch`, `/v1/webhooks/*`
* `premium`: `/v1/radar/all`, `/v1/signal/all`, `/v1/organizations/all`, `/v1/replay/global`

Premium routes are not just higher-plan. They also carry tighter access constraints:

* `/v1/organizations/all` is an export-style directory surface with smaller page sizes
* `/v1/radar/all` and `/v1/signal/all` are recent-monitoring surfaces with a required `since` window and tighter pagination caps
* `/v1/replay/global` is a merged premium replay surface with a 30-day recent-history window and smaller pages

Operational delivery routes are different:

* `/v1/webhooks/*` is a scoped delivery primitive for `radar` and `signal` subscriptions
* premium/global delivery should be treated as a separate product surface if added later

## Exceeding Limits

### Per-Minute Rate Limit

```json theme={null}
{
  "error": "Rate limit exceeded. Maximum 100 requests per 60 seconds."
}
```

* **Status:** `429 Too Many Requests`
* Check `X-RateLimit-Reset` header for seconds until the window resets

### Monthly Credit Limit

```json theme={null}
{
  "error": "API usage limit reached. Please upgrade your plan or contact support."
}
```

* **Status:** `403 Forbidden`
* Check `X-Monthly-Limit` and `X-Monthly-Used` headers for your quota status
* Credits reset on the 1st of each month (UTC)

## Best Practices

* Use the `since` parameter to poll incrementally instead of re-fetching everything
* Prefer filtered endpoints over bulk feeds unless you explicitly need a full export workflow
* Use `X-Api-Surface` and `X-Access-Layer` to verify you are hitting the route class you intended
* Check `X-RateLimit-Remaining` before sending bursts
* Monitor `X-Monthly-Remaining` to avoid hitting your credit cap
* Use the `/v1/usage` endpoint to track both request volume and monthly budget
* On `429`, wait for the `X-RateLimit-Reset` duration before retrying
* Implement exponential backoff on non-2xx responses