Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

Rate limits

Limit Default Applies to
Requests 100 per minute and 10,000 per day each key, sliding windows
Requests in flight at once 25 each key, per server instance
Uploads (photos, logo) in flight at once 1 each key, per server instance
Webhook replays 10 per day the whole account, per mode
Answers about other accounts' creators 20 per rolling 24 hours the whole account

Defaults can be raised per account — talk to us before a large import. GET /v1/me shows the limits in effect for your account (limits.per_minute, limits.per_day, limits.duplicate_budget).

What counts

  • Every request with a valid key counts, whatever its result — also 400, 403, 409 and 500.
  • 429 answers, 401 answers and requests refused for ip_not_allowed do not count against the key (401s use the per-IP budget instead).
  • Windows are sliding: they look back 60 seconds and 24 hours from each request and never reset at a fixed time.

Headers

Every answer that got past the key, IP, scope and concurrency checks tells you where you stand:

http
RateLimit-Policy: 100;w=60, 10000;w=86400
RateLimit: limit=100, remaining=97, reset=42

RateLimit describes the tighter of the two windows: the one that is used up, otherwise the one with fewer requests left. remaining already counts the current request; reset is the number of seconds until a slot in that window frees up. Slow down as remaining approaches 0 instead of waiting for a 429.

When you hit a limit

http
HTTP/1.1 429 Too Many Requests
Retry-After: 42

The body is an error with code rate_limited. Retry-After is the reset of the window that is used up (the daily one when both are). Pause the whole queue for that long, not just the one request.

Requests without a valid key

Requests that have no valid key — no Authorization header, an unknown, revoked or expired key — as well as GET /v1/ and paths that do not exist, share a separate budget per client IP address: 30 per minute, refilled continuously (one every 2 seconds). Past it, every such request from that address gets 429 rate_limited with Retry-After, without RateLimit headers. Requests with a valid key never use this budget, and a key that was accepted in the last 10 minutes is let through even from an address whose budget is used up; a key never seen before (or not for 10 minutes) from such an address waits like any other request until the budget refills. Like the concurrency limit it is kept per server instance. A correctly configured integration never comes near it; a loop retrying a wrong key does.

Concurrency

More than 25 requests of one key in flight at the same moment → 429 concurrency_limited with Retry-After: 1. Run at most about 10 requests in parallel and the limit never bites. The limit is kept per server instance; during a release two instances can briefly answer, so do not rely on reaching exactly 25.

Uploads (POST /v1/leads/{id}/photos, PUT /v1/me/logo) are tighter: one upload per key at a time. A second upload of the same key while the first is still running → 429 concurrency_limited with Retry-After: 1, before its body is read. Each server instance also takes only a few uploads of all accounts at once; when they are busy, an upload waits up to 10 seconds before it starts, and past that (or when too many are already waiting) it gets 429 concurrency_limited with Retry-After: 2. Upload photos one after the other.

Duplicate budget

A 409 duplicate_other_referrer tells you another account already submitted a creator. So that this cannot be used to test lists of handles against other accounts' creators, the account gets 20 such answers per rolling 24 hours, counted across all of its keys at the moment we answer, so parallel requests cannot exceed it.

When they are used up, every request that has to check a handle — POST /v1/leads with an instagram_handle, or a PATCH /v1/leads/{id} that changes it — answers 429 duplicate_limit_reached, whether that creator is new or taken, so it reveals nothing. Retry-After says when the oldest counted answer leaves the window. Requests that check no handle are not affected, and neither is a POST whose external_id you already used: it returns that lead before any handle check.

Sending many creators

There is no batch endpoint: one request per creator, with an Idempotency-Key and external_id each. A steady pace of one request per second stays far below the limits; up to 10 in parallel is fine. For more than 10,000 a day, talk to us first.