API rate limits

SocialScalr's public REST API and outbound webhook layer have per-plan rate limits. The defaults are generous for normal integration patterns; custom limits available on request for high-volume Agency workspaces.

By Mark Gabrielli · Last updated May 24, 2026

Per-plan limits

Limits are scoped per workspace (not per API token). Multiple tokens within the same workspace share the same bucket.

Rate limit headers

Every API response includes:

• X-RateLimit-Limit - your plan's per-minute ceiling.
• X-RateLimit-Remaining - requests remaining in the current 60-second window.
• X-RateLimit-Reset - Unix timestamp when the window resets.

Use these in client code to back off proactively before hitting 429.

When you hit the limit

The API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/json

{ "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 18 seconds.",
  "retry_after_seconds": 18 }

Recommended client behavior:

• Respect the Retry-After header - don't immediate-retry.
• Use exponential backoff with jitter for sustained burst periods.
• Implement a token bucket on your side to stay under the limit proactively.
• For batch jobs, paginate with reasonable page sizes (100 leads/page typical) rather than max-out per request.

Webhook delivery limits

Outbound webhook deliveries (events SocialScalr fires to your endpoint) are also rate-limited per workspace per minute. Behavior at the cap:

• Deliveries above the cap queue, they're not dropped.
• Queue drains at the cap rate as the 60-second window rolls.
• If queue depth exceeds 10,000 events, SocialScalr emails the workspace Owner with a warning to upgrade or batch on the receiver side.

Per-endpoint limits within the API

A few endpoints have stricter limits because they're expensive server-side:

• POST /campaigns with scrape source: 5/minute (each scrape kicks off a job).
• POST /leads bulk import (over 100 leads/request): 10/minute.
• GET /leads with no filters (workspace-wide): 30/minute (use filters to scope).
• POST /webhooks/test (manual delivery test): 10/minute per endpoint.

All other endpoints share the global per-minute bucket.

Best practices for high-volume integrations

1. Use webhooks instead of polling. If you want to react to new replies, subscribe to lead.replied instead of polling GET /leads?stage=replied every minute. Webhooks are push and don't count against API limits.
2. Paginate. Default page size is 50, max 250. Don't request 250 if you only need 50.
3. Cache. Lead data doesn't change every second. Cache 5-15 minutes on your side for read-heavy patterns.
4. Use the since= filter. GET /leads?since=15m is much cheaper than fetching everything and filtering client-side.
5. Batch writes. POST /leads with an array of 100 leads is one request; sending 100 separate requests is 100. Use the array form.

Requesting a higher limit

Email [email protected] with:

• Workspace ID
• Current usage pattern (requests/min average, peak)
• Why the standard limit doesn't fit
• What integration you're building

Standard custom limits available: 2,400 API req/min, 400 webhook deliveries/min on Agency. Anything beyond requires architecture review.

Related

• REST API + webhooks reference - full endpoint documentation.
• Integration recipes - Zapier, Make, Slack, HubSpot, etc.
• API + webhooks feature deep-dive - the product overview.