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

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.

Need higher rate limits? If you need higher custom rate limits, contact us for pricing details. Contact sales →

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

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 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 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
Low `X-PublicAPI-Credits`	Org is near its credit limit

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

Get Started

Core concepts

Use cases

Workflows

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