Skip to main content

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 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:
HeaderExampleDescription
X-RateLimit-Limit60Max requests allowed in the current window for this endpoint
X-RateLimit-Remaining42Requests remaining in the window
X-RateLimit-Reset1745587198Epoch seconds when the window resets
X-PublicAPI-Credits1000Research credits remaining for your org

​
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.
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 typeUses research credits?
Research — POST /companies/research, POST /contacts/researchYes — enrichment consumes credits
Org data — GET /companies, GET /contactsNo — reads records already in your org
Poll — GET /companies/research/poll, GET /contacts/research/pollNo
OAuth — POST /oauth/accessToken, GET /oauth/meNo

​
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:
codeMeaningWhat to do
insufficientCreditsNot enough research creditsCheck billing or reduce batch size
missingLicenseNo active Public API licenseContact your administrator or support
See API HTTP status codes for the full status code reference.
SymptomLikely cause
Poll status errorInsufficient credits or license restriction
HTTP 422 on researchInsufficient credits or missing license — see API HTTP status codes
Low X-PublicAPI-CreditsOrg is near its credit limit