Usage and Rate Limits

The Developer API includes usage limits to ensure fair usage and system stability.

Monthly Usage Cap

Included Usage

• 50,000 requests per month included with Developer API add-on subscription
• Usage is shared across all API keys for your company
• Usage resets automatically on the first day of each month

Additional Usage

If you need more than 50,000 requests per month, subscribe to the Developer API Additional Usage add-on:

• Purchase blocks of 1,000 requests per month
• Your total limit = 50,000 + (blocks × 1,000)
• Example: 5 blocks = 55,000 requests/month total

Usage Tracking

Response Headers

Every API response includes usage information in headers:

• X-Usage-Count: Number of requests made this month
• X-Usage-Limit: Your total monthly limit
• X-Usage-Resets: ISO timestamp when usage resets (first of next month)

Example Response Headers:

X-Usage-Count: 1234
X-Usage-Limit: 50000
X-Usage-Resets: 2025-03-01T00:00:00.000Z

Monitoring Usage

Check your usage in real-time:

1. Look at X-Usage-Count header in any API response
2. Compare to X-Usage-Limit to see remaining requests
3. Use X-Usage-Resets to know when limits reset

Usage Limit Exceeded

When you exceed your monthly limit:

• Status Code: 403 Forbidden
• Error Message: "Monthly usage limit reached. Usage resets on the first of next month."
• Request Logged: The request is still logged but not processed
• Usage Headers: Still included in error response

Example Error Response:

{
  "success": false,
  "error": "Monthly usage limit reached. Usage resets on the first of next month."
}

What Counts Toward Usage

• All API requests to /api/v1/* endpoints
• Successful requests (200, 201, etc.)
• Error responses (400, 401, 403, 404, 500, etc.)
• Idempotent retries: Cached responses (via Idempotency-Key) do not count toward usage

Usage Reset

• Reset Date: First day of each month at 00:00:00 UTC
• Automatic: No action required
• Immediate: New requests are allowed immediately after reset

Mid-Month Changes

Adding Developer API Mid-Month

• Full 50,000 requests available for the remainder of the month
• Usage resets on the first of next month

Adding Additional Usage Mid-Month

• Additional blocks apply immediately
• Usage resets on the first of next month
• Example: Add 5 blocks on the 15th → 55,000 total limit for remainder of month

Removing Developer API Mid-Month

• API access stops immediately
• Existing usage remains in logs
• No refunds for partial month

Best Practices

1. Monitor usage: Check X-Usage-Count headers regularly
2. Plan ahead: Subscribe to Additional Usage before reaching limit
3. Use idempotency: Cached responses don't count toward usage
4. Optimize requests: Batch operations when possible
5. Handle errors: Implement retry logic with exponential backoff

Request Logging

All requests are logged for:

• Usage tracking
• Analytics
• Debugging
• Security monitoring

Logs are retained for 1 year and include:

• Request method and path
• Response status
• Timestamp
• API key used (masked)
• IP address
• User agent

Access request logs in Settings → Developer API → View request logs.