Rate limits

SocialAPI applies a rate limit of its own: a posting velocity cap per publish target. Each platform also applies its own limits. All of them answer HTTP 429. Read the Retry-After header when it is present and wait that many seconds before you send the request again. These limits are the same on every plan, and upgrading does not raise them. Post and interaction allowances per billing period are on Plans and usage. A 429 from SocialAPI’s own limits uses the standard error envelope. error.meta.retry_after_seconds holds the same number of seconds as the Retry-After header:

{
  "error": {
    "code": "publishing.velocity_limit",
    "message": "publishing too fast: this instagram account is limited to 25 posts per hour, retry in 1841s",
    "meta": {
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "window": "hour",
      "limit": 25,
      "retry_after_seconds": 1841
    }
  },
  "request_id": "a1b2c3d4"
}

Every 429 code

Code	What it limits	Retry-After
`publishing.velocity_limit`	Posts per hour and per 24 hours for one publish target	Yes
`platform.{platform}.rate_limit`	The platform’s own limit	When the platform reports a wait
`inbox.sync_rate_limited`	Repeated `POST /v1/inbox/sync` for the same target. See Refresh the inbox manually	Yes
`accounts.sync_rate_limited`	Repeated `POST /v1/accounts/{id}/sync` for the same connected account. See Analytics	Yes
`validation.post_limit_exhausted`, `validation.interaction_limit_exhausted`, `billing.post_limit`, `billing.export_limit`, `billing.export_cooldown`, `billing.export_concurrent`	Plan allowances. See Plans and usage	No

A request refused by publishing.velocity_limit never reaches the platform and spends no credit.

Posting velocity caps

SocialAPI caps how fast one publish target can publish, on top of your plan’s post allowance. A publish target is one connected account, or one Facebook Page or Pinterest board when the account publishes to more than one Page or board. Each Facebook Page of a connection has its own counters.

Platform	Per hour	Per 24 hours
Instagram	25	45
Facebook	25	100
Threads	25	250
X / Twitter	25	50
TikTok	25	13
Pinterest	No hourly cap	1,000
Every other platform	25	50

The hourly window opens with the first publish counted in it and lasts 1 hour. The 24-hour window opens the same way and lasts 24 hours. On TikTok, the 24-hour cap of 13 binds before the hourly cap of 25. On Instagram, SocialAPI’s cap of 45 sits below Instagram’s 50 posts per rolling 24 hours. On TikTok, SocialAPI’s cap of 13 sits below TikTok’s own limit of 15 posts per day per account. Reaching SocialAPI’s cap gives you publishing.velocity_limit and a Retry-After, instead of a platform rejection after the attempt. TikTok also limits publishing to 6 posts per minute per account. SocialAPI does not enforce the 6 per minute: when you send a 7th post within a minute, TikTok refuses it and the target fails with a platform.tiktok.* code.

What happens at a cap

Immediate publish (POST /v1/posts with publish_now: true, POST /v1/posts/{pid}/publish, POST /v1/posts/{pid}/retry): the request returns 429 publishing.velocity_limit and creates nothing. meta.window is hour or day, meta.limit is the cap reached, and meta.account_id is the connected account. A refused request spends no post credit.
More than one target in one request: the request is all or nothing. If one target is at a cap, the whole request is refused and no target’s counter moves.
Scheduled post: a scheduled post is never failed by a velocity cap. SocialAPI holds the target and publishes it once the window clears, so it goes out late. The wait does not count as a failed delivery.

Platform limits

Each platform limits what an app can do for an account. When the platform refuses a request for its own rate limit, SocialAPI returns 429 platform.{platform}.rate_limit, for example platform.instagram.rate_limit. Match on the platform.*.rate_limit pattern to handle every platform. When the platform reports how long to wait, SocialAPI passes it on as Retry-After and error.meta.retry_after_seconds. Without them, wait at least 60 seconds, then retry with exponential backoff.

Platform	Limit
Instagram	50 posts per rolling 24 hours per account
Threads	250 posts and 1,000 replies per rolling 24 hours per account
TikTok	15 posts per day and 6 per minute per account
YouTube	A daily quota per Google Cloud project: 100 video uploads and 10,000 units for other calls, reset at midnight Pacific Time
Google Business Profile	10 location updates per minute per Business Profile
Facebook, X / Twitter	No single fixed number: the platform limits each app and each account, and reports usage in its response headers

Read a platform’s remaining quota

GET /v1/accounts/{id}/limits returns the quota the platform reports for one connected account, as an object of numbers. It needs the accounts:read scope and costs no credits.

curl https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/limits \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200) for an Instagram account:

{
  "posts_remaining": 47
}

Platform	Keys
Instagram	`posts_remaining`: posts left in Instagram’s rolling 24 hours
Threads	`posts_remaining`, `posts_total`, `replies_remaining`, `replies_total`
YouTube	`daily_quota_units`, `daily_upload_quota_calls`, and the unit cost of each operation (keys ending in `_cost` or `_cost_per_page`)
WhatsApp	`quality_rating`: `3` high, `2` medium, `1` low, `0` unknown. `messaging_tier_cap`: unique recipients allowed per 24 hours, `-1` for unlimited
Bluesky	`write_points_per_hour` (5,000) and `write_points_per_day` (35,000)
X / Twitter	An empty object

Zalo no longer reports its message quota: do not rely on remain and total. Every platform that is neither in the table nor Zalo returns 501 resource.not_supported.

Reads and platform limits

Reading comments, reviews, mentions, and posts costs no credits, and SocialAPI applies no rate limit of its own to ordinary reads. The two sync endpoints in the table above have their own cooldowns. Reads still count against the platform’s limit for the account. To detect new comments and messages, subscribe to webhook events instead of polling. If your interface fetches the same page of results repeatedly, cache it on your side.

Handling 429

Read Retry-After

When the response has a Retry-After header, wait that many seconds. The same value is in error.meta.retry_after_seconds.

Back off when there is no Retry-After

For platform.*.rate_limit without Retry-After, wait 60 seconds, then double the wait on each further 429.

Do not retry plan allowances

validation.post_limit_exhausted, validation.interaction_limit_exhausted, and the billing.* codes do not clear within minutes. Check GET /v1/usage and wait for period_end, or change your plan.

async function callWithRetry(url, options, maxAttempts = 4) {
  let waitSeconds = 60;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const resp = await fetch(url, options);
    if (resp.status !== 429) return resp;

    const body = await resp.json();
    const code = body.error.code;
    if (code.startsWith("validation.") || code.startsWith("billing.")) {
      return resp; // an allowance or daily cap: retrying does not help
    }

    const retryAfter = Number(resp.headers.get("Retry-After"));
    const delay = retryAfter > 0 ? retryAfter : waitSeconds;
    await new Promise((resolve) => setTimeout(resolve, delay * 1000));
    waitSeconds *= 2;
  }
  throw new Error("Still rate limited after " + maxAttempts + " attempts");
}

Use from an AI agent

Tool	What it does
`social_api_get_account_limits`	Returns the same keys as `GET /v1/accounts/{id}/limits`

Plans and usage: post, interaction, storage, and export allowances per plan
Errors: every error code with its HTTP status
Track post delivery: what a refused or held publish looks like on the post
Scheduling: how scheduled posts go out
Webhook events: receive new comments and messages instead of polling

Get started

Connect accounts

Inbox

Automations

Publish

Webhooks

API essentials

Every 429 code

Posting velocity caps

What happens at a cap

Platform limits

Read a platform’s remaining quota

Reads and platform limits

Handling 429

Use from an AI agent

​Every 429 code

​Posting velocity caps

​What happens at a cap

​Platform limits

​Read a platform’s remaining quota

​Reads and platform limits

​Handling 429

​Use from an AI agent

​Related

Every 429 code

Posting velocity caps

What happens at a cap

Platform limits

Read a platform’s remaining quota

Reads and platform limits

Handling 429

Use from an AI agent

Related