Rate Limits & Quotas

The API enforces per-minute rate limits and monthly quotas based on your plan.

Plans

Plan	Monthly Quota	Rate Limit	Price
Free	200 screenshots	5 requests/min	$0
Starter	2,000 screenshots	15 requests/min	$9/month
Pro	5,000 screenshots	30 requests/min	$29/month

Upgrade your plan anytime from the billing page.

Rate Limiting

Rate limits are applied per API key on a 1-minute sliding window. When you exceed the limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

{
  "error": "rate limit exceeded"
}

Monthly Quotas

Your monthly quota resets at the start of each billing period. For paid plans, this matches your Stripe billing cycle. For the Free plan, it resets on the 1st of each month (UTC).

When your quota is exceeded, the API returns 402 Payment Required:

{
  "error": "monthly quota exceeded",
  "plan": "free",
  "limit": 200,
  "used": 200,
  "resetAt": 1706745600,
  "upgrade": "Upgrade your plan at https://app.shotone.io/dashboard/billing"
}

Response Headers

Every API response includes rate limit and quota information in headers:

Header	Description
X-Plan	Your current plan name
X-RateLimit-Limit	Maximum requests per minute for your plan
X-RateLimit-Remaining	Requests remaining in current minute
X-RateLimit-Reset	Unix timestamp when rate limit window resets
X-Quota-Limit	Monthly screenshot quota for your plan
X-Quota-Remaining	Screenshots remaining this billing period
X-Quota-Reset	Unix timestamp when your quota resets

Best Practices

• Check X-RateLimit-Remaining before making batches of requests
• Implement exponential backoff when receiving 429 responses
• Use the Retry-After header to know exactly when to retry
• Queue requests and process them at a steady rate below your limit
• Cache screenshots to avoid duplicate requests for the same URL