Rate Limiting

Your workspace has an API budget measured in credits, and two ceilings applied at the same time:

1. A credit budget sized by your plan — a burst allowance that refills every second.
2. A flat ceiling of 5 requests per second, per workspace.

You’re bounded by whichever you reach first. Both are scoped per workspace: if one token has access to several workspaces, each workspace gets its own budget, and they never share. That holds for agency plans too — every workspace carries its own full allowance, so one brand’s heavy sync can’t slow a sister brand.

The MCP server draws on the same budget. There’s no separate allowance for it: a tool call maps to a query and costs what that query costs. An AI agent working through a long task is spending the same credits as your own integrations.

What a credit is

One credit is one millisecond of backend compute. A request’s cost reflects the work it actually causes, not how many bytes come back — which is why a cheap lookup and a filtered AI search are priced so differently.

Two things follow from that table, and they’re the whole game:

Bigger pages are cheaper per record. Every request pays the floor of 5 whatever it does, so one first: 100 call costs far less than 100 × first: 1 returning the same data. Always page at 100.

Filtering creators by custom attributes is the single most expensive thing you can ask for — roughly five times a plain creator search, because a filtered creator search is genuinely slow on our side. Fetch broadly and narrow locally where you can.

Your budget

Two numbers per plan: the burst allowance your bucket holds, and the refill rate that tops it up every second. Short spikes dip into the bucket; sustained throughput is capped by the refill rate.

Agency 2026 and Agency 2026 Unlimited: every workspace in the account gets its own full Growth allowance. There is no shared pool across the account. (“Unlimited” refers to UGC, not API capacity — both agency plans carry the same API limits.)

To put the refill rate in practical terms: Startup sustains about 10 cheap requests or 1 items page per second; Growth sustains about 50 cheap requests or 5 items pages per second. A Growth workspace refills its entire burst allowance every 60 seconds.

The API add-on

The API add-on is a capacity purchase worth +5,000 burst and +50 credits per second — one Startup unit.

On a 2026 plan the add-on adds to your plan’s allowance. On a legacy plan it’s the only source of API capacity — legacy plans carry none of their own — so the add-on is your entire envelope rather than a supplement.

Demo workspaces stay at 500 / 5 regardless of other products. Full schema access, ceilings deliberately too low to bulk-extract.

Reading your budget from the response

Every response carries the standard IETF rate-limit headers, so you never have to guess or discover your limit through errors:

ratelimit-policy: "growth";q=15000;w=60
ratelimit: "growth";r=14203;t=1785409320

q ÷ w gives you your refill rate. Self-throttle against r — that’s what these headers are for, and it’s much better than finding the ceiling with a 429.

Hitting the limit

Going over is graceful, not fatal. An over-budget request returns HTTP 429 with a Retry-After header, and the GraphQL body carries RATE_LIMIT_EXCEEDED:

{
  "errors": [
    {
      "message": "Rate limit exceeded. Retry after 0.4 seconds.",
      "extensions": { "code": "RATE_LIMIT_EXCEEDED" }
    }
  ]
}

A client that honours Retry-After slows down instead of breaking. A batch sync takes more minutes and loses no work. Only clients that ignore 429s see failures — and unattended overnight jobs with a wall-clock timeout wrapped around them are where that hurts most.

Designing around it

Shape traffic before it leaves your service. Retries with backoff don’t raise your effective rate, they just add latency. Keep a token-bucket limiter on your side, sized to your plan’s refill rate, and share it across processes if more than one of them talks to the same workspace.

Page at 100. The per-request floor of 5 credits means small pages are pure waste.

Watch engagementHistory. It’s the one query that can’t take a batch of IDs — it accepts a single itemId — so it’s the usual reason a client suddenly starts fanning out and hitting the ceiling. It’s also the cheapest call we have at ~7 credits, so the problem is request count, not cost.

Pace writes by credits, not by requests. A mutation costs ~55 credits, so 5 writes per second needs 275 credits/s — more than Startup or Growth refills. In practice that’s about 1 write/second on Startup, 4 on Growth, 18 on Enterprise. Bulk tagging loops are the usual place this bites.

Budget your first paint. If a job has a hard time budget, size the initial fetch to fit inside it at your plan’s refill rate rather than hoping bursts absorb it.

See also: Best Practices and Error Handling → Rate limit errors.