Rate limits and credits

Rate limits and 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`	Credits remaining for your org

Handle 429 errors

Read the reset time

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

Backoff between polls

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

Avoid duplicate research

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

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 10 results returned, rounded up. Returning 1–10 results costs 1 credit; 11–20 costs 2. 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

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 credits for this search or research request	Check billing, lower the search `limit`, or reduce the research batch
`missingLicense`	No active Public API license	Contact your administrator or support

See API HTTP status codes 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 API HTTP status codes
Low `X-PublicAPI-Credits`	Org is near its credit limit

API HTTP status codes — HTTP 400, 401, 403, 422, 429, and more
Troubleshooting — failed research and auth errors
Choose a workflow — when to search, research, or read records you already have

Get Started

Core concepts

Use cases

Workflows

Guides

Troubleshooting

Rate limits and credits

Rate limits

Response headers

Handle 429 errors

Credits

Which requests use credits

Check your credit balance

License vs credits (HTTP 422)

​Rate limits

​Response headers

​Handle 429 errors

​Credits

​Which requests use credits

​Check your credit balance

​License vs credits (HTTP 422)

​Related

Rate limits

Response headers

Handle 429 errors

Credits

Which requests use credits

Check your credit balance

License vs credits (HTTP 422)

Related