Rate limits

The Backstage API limits how often you can call each endpoint. Limits protect the platform from traffic spikes and keep response times predictable for everyone.

📘

Which accounts are limited

Endpoint rate limits apply only to accounts created after October 4, 2026. Accounts created on or before that date are not limited.

An account that belongs to a network is limited only if the network, and every account in it, was created after that date.

How limits are applied

Every limited request is measured against three windows at once - a one-second window, a one-minute rate, and an hourly volume. A request is allowed only if it fits within all three. Whichever window you exhaust first is the one that stops you.

Limits are applied per account, per endpoint group, with reads and writes counted separately:

• GET, HEAD and OPTIONS requests draw from your read budget.
• Every other method - including POST, PUT, PATCH and DELETE - draws from your write budget.

📘

What a limit does not affect

Exceeding a limit on one endpoint group does not restrict the rest of your integration. Your other endpoint groups keep working, your write budget is untouched when you exhaust a read budget, and the same endpoint continues to work normally for your other accounts.

Windows refill continuously, not on a fixed clock. There is no "top of the minute" reset - your budget replenishes steadily, so a client that paces its requests evenly rarely hits a limit at all.

Rate limit tiers

Each endpoint group is assigned a tier, and the tier determines the three limits.

🚧

Lower tier numbers are more permissive

Tier 1 allows the most requests, and Tier 6 the fewest. This is the opposite of the convention used by some other APIs - check the number, not just the tier name.

Second is per second, minute is per 60 seconds, hour is per 3,600 seconds.

Checking your usage

Every response - not just a 429 - carries two headers, so you can pace your integration before you hit a limit. Each header is a list of named entries: one per window when an endpoint limit applies to the request, followed by a perclient entry for the per-token limit.

ratelimit-policy: "second";q=5;w=1, "minute";q=60;w=60, "hour";q=300;w=3600, "perclient";q=5040;w=60
ratelimit: "second";r=0;t=1, "minute";r=12;t=48, "hour";r=180;t=1440, "perclient";r=5038;t=16

ratelimit-policy describes the limits that apply: q is the quota, and w is the window in seconds. ratelimit describes what you have left: r is the number of requests remaining.

On an endpoint without an endpoint limit, the headers carry only the perclient entry:

ratelimit-policy: "perclient";q=5040;w=60
ratelimit: "perclient";r=5039;t=17

perclient is a per-token limit: it applies to every API request made with an access token, independently of the endpoint tiers above and for every account. It is currently 5,040 requests per 60 seconds per token (q=5040;w=60). Exhausting it affects every request made with that token.

🚧

Look up entries by name

Both headers are Structured Fields lists (RFC 9651, which obsoletes RFC 8941). Parse them as a list and look up each entry by its name: "second", "minute", "hour" or "perclient". Do not rely on the position of an entry, the number of entries, or the exact separator between them.

🚧

Use Retry-After, not t

The t value is the time in seconds for that window to refill to its full quota - it is not the time until your next request will succeed, which is usually much sooner. After a 429, always schedule your retry from the Retry-After header.

When you exceed a limit

GET /backstage/api/1.0/{account_id}/campaigns/ HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access_token}

HTTP/1.1 429 Too Many Requests
Retry-After: 1
ratelimit-policy: "second";q=5;w=1, "minute";q=60;w=60, "hour";q=300;w=3600, "perclient";q=5040;w=60
ratelimit: "second";r=0;t=1, "minute";r=0;t=48, "hour";r=180;t=1440, "perclient";r=5021;t=33

{
    "http_status": 429,
    "message": "Request cannot be satisfied as assigned quota has been exceeded",
    "violated_policies": ["second", "minute"]
}

Retry-After is the number of seconds to wait before retrying. Use it to schedule your retry.

violated_policies lists every window you exhausted, and contains any combination of second, minute and hour. A request that exhausts only the second window succeeds again within a second; one that exhausts the hourly window does not.

🚧

429 Too Many Requests

A 429 means this request was not processed. Nothing was created, updated or deleted, so the request is always safe to retry.

📘

Limits may change

Quotas are reviewed periodically and each tier's limits are subject to change. Read the ratelimit headers at runtime rather than hard-coding the values on this page.

For the general shape of API error responses, see Errors.