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

# Rate limits and credits

> Organization-level rate limits, response headers, 429 handling, and credit balance headers on the Seamless API.

Rate limits and research credits apply at the **organization** level. All API keys and users under your Seamless org share the same quotas.

## Rate limits

The default limit is **60 requests per minute per endpoint**. When you exceed the limit, the API returns **429 Too Many Requests** with a JSON error body.

All API keys and users in your organization share the same quota. The limit applies separately to each endpoint — for example, search and poll each have their own 60 requests per minute window — but the default cap is the same for all v1 endpoints.

Some endpoints use different limits (for example, OAuth token routes). Your organization may also have custom limits. The `X-RateLimit-Limit` header on each response always reflects your actual limit for that endpoint in the current window.

Need a higher limit? Contact **Sales** or your **Account Executive**.

### Response headers

Every API response can include:

| Header                  | Example      | Description                                                  |
| ----------------------- | ------------ | ------------------------------------------------------------ |
| `X-RateLimit-Limit`     | `60`         | Max requests allowed in the current window for this endpoint |
| `X-RateLimit-Remaining` | `42`         | Requests remaining in the window                             |
| `X-RateLimit-Reset`     | `1745587198` | Epoch seconds when the window resets                         |
| `X-PublicAPI-Credits`   | `1000`       | Research credits remaining for your org                      |

### Handle 429 errors

<Steps>
  <Step title="Read the reset time">
    Parse `X-RateLimit-Reset` and wait until that timestamp before retrying the same endpoint.
  </Step>

  <Step title="Backoff between polls">
    When polling research results, use a 2–5 second interval instead of tight loops.
  </Step>

  <Step title="Avoid duplicate research">
    A `duplicate` poll status means the record was already researched — do not resubmit research for the same `searchResultId`.
  </Step>
</Steps>

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

response = requests.get(
    "https://api.seamless.ai/api/client/v1/contacts/research/poll",
    headers={"Token": API_KEY},
    params={"requestIds": request_id},
)

if response.status_code == 429:
    reset = int(response.headers.get("X-RateLimit-Reset", 0))
    wait_seconds = max(reset - time.time(), 1)
    time.sleep(wait_seconds)
```

## Research credits

Research endpoints consume credits when enrichment runs. Search and org-data reads do not start new research jobs.

### Which requests use research credits

| Request type                                                             | Uses research credits?                     |
| ------------------------------------------------------------------------ | ------------------------------------------ |
| **Research** — `POST /companies/research`, `POST /contacts/research`     | **Yes** — enrichment consumes credits      |
| **Org data** — `GET /companies`, `GET /contacts`                         | **No** — reads records already in your org |
| **Poll** — `GET /companies/research/poll`, `GET /contacts/research/poll` | **No**                                     |
| **OAuth** — `POST /oauth/accessToken`, `GET /oauth/me`                   | **No**                                     |

### Check your credit balance

* Remaining credits appear in the **`X-PublicAPI-Credits`** response header on authenticated v1 requests.
* You can also check **Settings → Billing** in the Seamless app.

There is no dedicated v1 endpoint to query credits — use the response header or the Seamless app.

### License vs credits (HTTP 422)

Both problems return **HTTP 422**, but the `code` field tells you which applies:

| `code`                    | Meaning                      | What to do                            |
| ------------------------- | ---------------------------- | ------------------------------------- |
| **`insufficientCredits`** | Not enough research credits  | Check billing or reduce batch size    |
| **`missingLicense`**      | No active Public API license | Contact your administrator or support |

See [API HTTP status codes](/api-http-status-codes) for the full status code reference.

| Symptom                   | Likely cause                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| Poll status `error`       | Insufficient credits or license restriction                                                   |
| HTTP 422 on research      | Insufficient credits or missing license — see [API HTTP status codes](/api-http-status-codes) |
| Low `X-PublicAPI-Credits` | Org is near its credit limit                                                                  |

## Related

* [API HTTP status codes](/api-http-status-codes) — HTTP 400, 401, 403, 422, 429, and more
* [Troubleshooting](/troubleshoot-authentication-and-request-failures) — failed research and auth errors
* [Choose a workflow](/choose-the-right-workflow) — when search vs org data avoids new credit use