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

Interactive discovery searches usually need a quick response because someone is waiting for the results. Enrichment often runs as a scheduled process making hundreds or thousands of similar lookups, such as counting jobs for each company in a list. Those calls can wait in a queue and run at a steady pace. 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 priority over background enrichment, stay within the advertised limits, and retry 429 responses with exponential backoff. These are basic integration requirements even when a higher or separate limit has been agreed. Repeated enrichment calls alone do not justify a higher rate limit.

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.

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.