specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Seamless.AI
providerId: seamless-ai
generated: '2026-08-14'
method: searched
source: https://docs.seamless.ai/rate-limits-and-credits
created: '2026-05-04'
modified: '2026-08-14'
note: >-
  Replaces the 2026-05-04 bulk-sweep scaffold, which invented free/professional/enterprise tiers
  and per-minute/per-month numbers Seamless.AI has never published. Every value below is
  transcribed from the provider's own rate-limits page, harvested 2026-08-14.
tags:
  - B2B
  - Contact Data
  - Sales Intelligence
  - Rate Limiting
  - Quotas
  - Throttling
description: >-
  Published rate limits and credit metering for the Seamless.AI Public API v1. Limits are enforced
  at the ORGANIZATION level and apply per endpoint, not per API key: all keys and users under one
  Seamless org share the same window.

headers:
  limit: X-RateLimit-Limit
  remaining: X-RateLimit-Remaining
  reset: X-RateLimit-Reset
  credits: X-PublicAPI-Credits
  retryAfter: null
reset_format: epoch-seconds
responseCodes:
  throttled: 429
  quotaExceeded: 422
error_codes:
  throttled: rateLimitExceeded
  credits_exhausted: insufficientCredits
  unlicensed: missingLicense

limit_count: 1
limits:
  - name: Default per-endpoint limit
    scope: organization
    applies_per: endpoint
    metric: requests_per_minute
    limit: 60
    burst: null
    timeFrame: minute
    published: true
    source: https://docs.seamless.ai/rate-limits-and-credits
    note: >-
      The default cap is the same for all v1 endpoints, but each endpoint gets its own window —
      search and poll do not share a bucket. OAuth token routes are stated to use different
      limits, which the provider does not publish. Custom org limits are available; the
      X-RateLimit-Limit header always reflects the actual limit for that endpoint in the current
      window, so a client should read the header rather than assume 60.

metering:
  unit: research credit
  scope: organization
  balance_header: X-PublicAPI-Credits
  balance_endpoint: null
  balance_endpoint_note: >-
    There is no dedicated v1 endpoint to query credits. The provider directs callers to the
    response header or to Settings -> Billing in the app. The MCP `get_credits` tool and the
    `seamless://credits` resource are the only first-class programmatic reads.
  charged:
    - operation: researchCompanies
      path: POST /companies/research
    - operation: researchContacts
      path: POST /contacts/research
  not_charged:
    - operation: getCompanies
      path: GET /companies
    - operation: getContacts
      path: GET /contacts
    - operation: pollCompanyResearchResults
      path: GET /companies/research/poll
    - operation: pollContactsResearchResults
      path: GET /contacts/research/poll
    - operation: getAccessToken
      path: POST /oauth/accessToken
    - operation: searchCompanies
      path: POST /search/companies
    - operation: searchContacts
      path: POST /search/contacts

policies:
  - name: 429 recovery
    description: >-
      Parse X-RateLimit-Reset and wait until that epoch timestamp before retrying the same
      endpoint. No Retry-After header is sent, so a generic Retry-After-based backoff will not
      work against this API.
  - name: Poll interval
    description: Poll research results on a 2-5 second interval; tight loops burn the endpoint's quota.
  - name: Avoid duplicate research
    description: >-
      A `duplicate` poll status means the record was already researched. Resubmitting wastes
      quota and is explicitly discouraged.
  - name: Raising the limit
    description: Higher limits are negotiated through Sales or an Account Executive, not self-serve.

maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com