API Reference

Rate Limits

Creagency applies rate limits to ensure platform stability and fair usage across all organizations. Limits vary by subscription plan and are enforced per API key.

Response Headers

Every API response includes rate limit information in the headers:

Plan	Requests/Minute	Time Window	Burst
Starter	60	60 seconds	60
Growth	180	60 seconds	180
Scale	600	60 seconds	600
Enterprise	1,200	60 seconds	1,200

Note: Limits apply individually to each API key. Using multiple keys does not increase your organization's total rate limit capacity.

Endpoint-Specific Limits

Certain endpoints have additional constraints regardless of plan:

Posts Creation

Limit: 10 posts per minute

Applies to: POST /api/posts

Rationale: Prevents spam and ensures quality content moderation

Media Upload Signing

Limit: 20 signed URLs per minute

Applies to: POST /api/media/uploads/sign

Rationale: Object storage signing is computationally expensive

AI Caption Generation

Starter: 15 requests/day

Growth: 50 requests/day

Scale: 125 requests/day

Enterprise: Unlimited

Global API Limit

All endpoints share your plan's request/minute pool

Redis-backed enforcement ensures consistency

No burst capacity beyond stated limits

Rate Limit Error Response

HTTP/1.1 429 Too Many Requests

Content-Type: application/json

ratelimit-limit: 60

ratelimit-remaining: 0

ratelimit-reset: 45

retry-after: 45

{

"success": false,

"error": "RATE_LIMITED",

"message": "Rate limit exceeded. Please retry after 45 seconds."

}

Handling Rate Limits

Implement exponential backoff with jitter when you receive a 429 response:

async function apiCallWithRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries) {
        const resetSeconds = parseInt(
          error.headers['ratelimit-reset'] || '60'
        );
        const jitter = Math.random() * 1000;
        const delay = (resetSeconds * 1000) + jitter;
        
        console.log(`Rate limited. Retrying after ${delay}ms...`);
        await new Promise(resolve => 
          setTimeout(resolve, delay)
        );
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Best Practices

Monitor Headers Proactively

Check ratelimit-remaining before batch operations. If below 5, pause until reset to avoid hitting the limit.

Use Efficient Pagination

Default limits return 20 items. Use ?limit=100 to reduce API calls when fetching many posts or assets.

Cache Discovery Data

Connected social accounts rarely change. Cache results for 5 minutes to avoid unnecessary API calls.

Combine Operations

Create posts with media in one request when possible. Avoid create asset → create post → attach as separate calls.

API Limits by Feature

Feature	Starter	Growth	Scale	Enterprise
API Keys	2	5	20	Unlimited
Social Accounts	10	35	80	300
Scheduled Posts/Month	300	Unlimited	Unlimited	Unlimited
Storage	5 GB	15 GB	50 GB	1 TB
API Access	✓	✓	✓	✓

FAQ

Do rate limits apply to webhooks?

No, webhooks from social platforms (Stripe webhooks, etc.) are exempt from rate limiting.

What happens if I hit the limit during a batch operation?

The request is rejected with 429. Previous successful requests in the batch are preserved. Wait for the reset window and continue from where you left off.

Can I purchase additional rate limit capacity?

Rate limits are tied to plans. Upgrade to Growth, Scale, or Enterprise for higher limits. Enterprise plans can request custom limits.

How do I monitor my usage?

Check response headers on every request. The dashboard also shows aggregate API usage for workspace owners in the billing section.