> ## 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 credits apply at the **organization** level. All API keys and users under your Seamless org share the same quotas.

## Rate limits

Every endpoint is rate limited per organization. The limit is operator-configured and can differ by endpoint and by organization, so do not hardcode a number: read **`X-RateLimit-Limit`** on each response, which always reflects your actual limit for that endpoint in the current window. The standard allowance is on the order of 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 window.

> [!TIP]
>
> **Need higher rate limits?** If you need higher custom rate limits, contact us for pricing details. [Contact sales →](https://seamless.ai/pricing-inquiry)

### Response headers

| 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` | Credits remaining for your org. Sent on every authenticated response. |

### Handle 429 errors

**1. Read the reset time**

Parse `X-RateLimit-Reset` and wait until that timestamp before retrying
the same endpoint.

**2. Backoff between polls**

When polling research results, use a 2–5 second interval instead of
tight loops.

**3. Avoid duplicate research**

A `duplicate` poll status means the record was already researched — do
not resubmit research for the same `searchResultId`.

```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)
```

## Credits

Search and research spend the same credit balance. Reading records already in your org, polling for results, and OAuth do not.

### Which requests use credits

| Request type | Uses credits? |
| - | - |
| **Search** — `POST /search/contacts`, `POST /search/companies` | **Yes** — 1 credit for every 50 results returned, rounded up. Returning 1–50 results costs 1 credit, and each further 50 results, or part of them, costs 1 more. A response with no rows costs nothing. If the balance cannot cover the requested `limit`, the page is shortened to what the balance can pay for. The request returns 422 when fewer than 1 credit remains. |
| **Research** — `POST /companies/research`, `POST /contacts/research` | **Yes** — 1 credit per record submitted for enrichment |
| **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** |

Search does not start a research job. Researching a `searchResultId` is a separate charge on top of the search that found it.

### Check your credit balance

* Every authenticated response includes the remaining balance in the **`X-PublicAPI-Credits`** header.
* v2 (beta) has a dedicated endpoint, `GET /client/v2/credits`. v1 has none.
* You can also check **Settings → Billing** in 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 credits for this search or research request | Check billing, lower the search `limit`, or reduce the research batch |
| **`missingApiAccess`** | No active Public API license | Contact your administrator or support |

See [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md) for the full status code reference.

| Symptom | Likely cause |
| - | - |
| Poll status `error` | Insufficient credits or license restriction |
| HTTP 422 on search or research | Insufficient credits or missing license — see [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md) |
| Low `X-PublicAPI-Credits` | Org is near its credit limit |

## Related

* [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md) — HTTP 400, 401, 403, 422, 429, and more
* [Troubleshooting](https://docs.seamless.ai/troubleshooting/authentication-and-request-failures.md) — failed research and auth errors
* [Choose an API](https://docs.seamless.ai/api-catalog/choose-an-api.md) — when to search, research, or read records you already have


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