Rate Limit

All API endpoints are rate limited to ensure reliability and fair usage. When a limit is exceeded, the API returns HTTP 429 Too Many Requests. Limits are applied per user with fixed windows, which reset at the start of each second, minute, hour and day (UTC); multiple windows may apply simultaneously.

Tiered endpoints and limitsCopy Anchor Link

Endpoints covered by tier-based limits:

• POST /v1/jobs/search (Jobs Search)
• POST /v1/companies/search (Companies Search)
• POST /v1/companies/technologies (Technographics)
• POST /v1/companies/buying_intents (Buying Intents)

Shared limits across all four endpoints:

• Paid tier applies to users who have made at least one payment.
• Free tier applies to all other users (users who have never paid or users without any payments done).

Multiple limits are applied simultaneously. A request is rejected if it exceeds any active window.

Queue enrichment and prioritize interactive searchesCopy Anchor Link

Two types of work need different priorities in your integration:

• Interactive searches: a user clicks a button or opens a page and waits for the results. Give these calls priority within the available allowance.
• List enrichment: a process makes hundreds or thousands of similar lookups, such as counting jobs for each company in a list. Queue these calls as background work. A user action that starts a large enrichment run still needs the same pacing.

Use a shared queue for calls that draw from the same rate-limit budget. Give interactive searches preference when choosing which calls to dispatch next, while keeping enrichment progressing within the available allowance. This scheduling preference does not require pausing enrichment. Dispatch all calls within the advertised limits and retry 429 responses with exponential backoff, respecting the reset time. Apply the same scheduling preference to queued retries. These requirements still apply when a higher or separate limit has been agreed. Repeated enrichment calls alone do not justify a higher rate limit.

When a higher limit helpsCopy Anchor Link

We are happy to discuss more capacity as your integration grows. A short spike and sustained demand need different approaches. If a process submits a large batch and the queue clears before more work arrives, pacing absorbs the spike. Raising the per-second ceiling to match that one burst usually adds capacity the integration does not need the rest of the time.

A higher allowance can help when new work keeps arriving faster than the queue can process it, so the backlog keeps growing instead of clearing. This can happen with interactive searches or enrichment, for one user or many. We assess ongoing demand, how the results are used and available capacity together. The same reasoning applies to reseller end-user allowances and the workspace's aggregate limit.

Tell us about your integration, including whether the calls serve an interactive page or bulk enrichment and how you queue and retry them. We can review the traffic with you and work out the capacity it needs.

Planned support for reseller end usersCopy Anchor Link

We are preparing separate rate-limit budgets for the end users of approved resellers. TheirStack will enable this on request for individual workspaces. Once enabled, concurrent end users will have separate allowances, subject to the reseller workspace's aggregate capacity limit. Queues, pacing and retries will still apply to each allowance.

This policy is not active yet. Until we confirm activation for your workspace, the existing limits continue to apply. Sending an identifier does not enable separate limits or raise your allowance.

If we ask you to identify reseller traffic, send this request header on each call made for an end user:

X-TheirStack-End-User-Id: customer_4821

Use a stable, opaque identifier from your system, or a stable hash of it. Send the same value for every call belonging to that end user and different values for different end users. Do not send names, email addresses or phone numbers. This identifier lets us analyze overlapping traffic from distinct users; it does not authenticate the end user or change billing.

Separate allowances support genuine growth in your user base. Keep each end user's identifier stable across sessions, background jobs and retries. Do not generate random values per request or split one user's workflow across multiple identifiers to bypass their limit.

If we detect identifier rotation or fabricated end users used to bypass limits, we will block the offending traffic, reduce the permitted rate and remove the workspace from the per-end-user rate-limit program. All of its end users will then share one allowance, so background batches and interactive searches will compete for that capacity and may take longer. These are conditions of the planned program; sending the header does not mean the program is active.

Contact support to discuss reseller activation. We will confirm the applicable limits and activation before the policy takes effect.

Rate limit headersCopy Anchor Link

The API returns rate limit information in every response. We follow the IETF HTTPAPI draft for RateLimit headers: RateLimit header fields for HTTP. When multiple rate limits apply, header items are comma-separated and ordered consistently across headers.

IETF compliant headersCopy Anchor Link

• RateLimit: Current quota status per policy. Format: "<policy-name>"; r=<remaining-requests>; t=<time-until-reset>; pk=<partition-key>.
• RateLimit-Policy: Applied policy definition. Format: "<policy-name>"; q=<limit>; w=<window-seconds>.

Other headersCopy Anchor Link

These are included for client convenience:

• RateLimit-Limit: Total allowed requests for each window
• RateLimit-Remaining: Requests remaining in each window
• RateLimit-Reset: Seconds until the current window resets

The order of values in legacy headers matches the order of RateLimit items.

Example response headers:

RateLimit: "per-second";r=3;t=1;pk="dXNlcjoxMjM0", "per-minute";r=9;t=60;pk="dXNlcjoxMjM0", "per-hour";r=49;t=3600;pk="dXNlcjoxMjM0", "per-day";r=399;t=86400;pk="dXNlcjoxMjM0"
RateLimit-Policy: "per-second";q=4;w=1, "per-minute";q=10;w=60, "per-hour";q=50;w=3600, "per-day";q=400;w=86400
RateLimit-Limit: 4, 10, 50, 400
RateLimit-Remaining: 3, 9, 49, 399
RateLimit-Reset: 1, 60, 3600, 86400

Exceeding limits and best practicesCopy Anchor Link

• The 429 error says which limit you hit and how many seconds to wait. Calls made before then are rejected and still count toward your limits.
• Retry with exponential backoff on HTTP 429 responses.
• Monitor RateLimit or RateLimit-Remaining and RateLimit-Reset to avoid hitting limits.
• Prefer batching and caching to reduce request counts.
• Avoid concurrent bursts that violate per-second limits.