Rate limits

The API rate-limits per user. Every token that belongs to the same user draws from the same budget. There are two tiers, applied to different endpoint groups:

Tier	Limit	Applied to
Standard	60 requests / minute	Workspaces, profiles, analytics, hashtags
High-volume	1,000 requests / minute	Posts, media library, folders

The high-volume tier covers the endpoints you are most likely to hammer during bulk imports. The MCP server has its own limit of 60 requests per minute per user.

Headers

Responses to requests that reach the rate limiter include the current rate-limit state:

Header	Meaning
`X-RateLimit-Limit`	The cap for the current window.
`X-RateLimit-Remaining`	How many requests you have left in the current window.
`Retry-After`	(Only on `429` responses) seconds to wait before retrying.

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 947

Requests turned away before the rate limiter carry none of these headers and don’t count toward your limit:

401: the token is missing or invalid.
404: the path doesn’t match any endpoint.
405: the endpoint doesn’t accept the HTTP method.

Every other response carries them and counts, errors included. That covers a 402 when a plan check fails (see Plans), a 403 when the token lacks the ability the endpoint needs or you can’t act on the resource, a 404 for an ID in the URL that doesn’t exist, and 422 validation errors.

When you hit the limit

The API returns 429 Too Many Requests:

{
  "message": "Too Many Attempts."
}

With:

Retry-After: 23

Wait the suggested number of seconds and retry. Do not keep hammering. Repeated 429s during a single window can extend the cool-off.

Daily post creation cap

On top of the per-minute limits, POST /workspaces/{workspace}/posts is capped over a rolling 24-hour window. The cap belongs to the workspace owner: requests from every team member’s token count toward it, at the owner’s plan’s rate.

Plan	Create requests per 24 hours
Pro	200
Business	500

Each request counts once, whatever the number of items in its posts array (up to 10), so batching posts stretches the cap. The window is rolling: a request made at 09:00 stops counting at 09:00 the next day. Posts created in the dashboard or through the MCP server do not count. When the cap is reached the API returns 429 with:

{
  "message": "You have reached the maximum number of posts you can create through the API in a 24-hour period. Please try again later."
}

This response carries no Retry-After header. Back off until the oldest request in your window is 24 hours old, or spread bulk creation across the day.

Patterns for staying inside the limit

Concurrency limiting

For bulk operations, cap concurrent in-flight requests instead of firing everything at once. A p-limit(20) in Node, or ThreadPoolExecutor(max_workers=20) in Python, keeps you well inside the 1,000/min tier without coordination overhead.

Exponential backoff with jitter

On 429, wait Retry-After. On 5xx, retry with exponential backoff (for example 1s, 2s, 4s) plus 10 to 20% jitter to avoid thundering-herd retries from multiple workers.

Batch where you can

The upload endpoint takes up to 10 files per request, which counts as one request against the rate limit. For files too large for the request body, one presign call plus one confirm call covers a batch of 10 and counts as 2 requests; the PUT uploads themselves go directly to storage and do not count at all. Post creation takes up to 10 items per request, which counts as one request against both the per-minute limit and the daily cap.

Cache list responses

If your code repeatedly fetches the same workspace’s profile list (for example in a polling loop), cache it for a few minutes instead of refetching every cycle. Profile membership rarely changes.

Reference retry helper

async function fetchWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429 && res.status < 500) return res;

    const retryAfter =
      Number(res.headers.get('Retry-After')) ||
      Math.min(60, 2 ** attempt) + Math.random();
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('Exceeded retry budget');
}

Asking for more

If your production workload genuinely needs higher limits (for example a large agency syncing thousands of profiles), email hello@publishbuddy.com with your use case and average request profile.

Getting started

Core concepts

How-to guides

API essentials

Headers

When you hit the limit

Daily post creation cap

Patterns for staying inside the limit

Reference retry helper

Asking for more

​Headers

​When you hit the limit

​Daily post creation cap

​Patterns for staying inside the limit

​Reference retry helper

​Asking for more

Headers

When you hit the limit

Daily post creation cap

Patterns for staying inside the limit

Reference retry helper

Asking for more