Rate limits

Screenshotly enforces rate limits to ensure fair usage and service reliability.

Limits by plan

Plan	Monthly screenshots	Storage	Rate limit	Price
Free	100	500 MB	5 req/min	Free
Starter	5,000	5 GB	20 req/min	$29/mo
Pro	25,000	15 GB	60 req/min	$79/mo
Business	75,000	50 GB	120 req/min	$199/mo

Rate limits are applied per API key within a 60-second sliding window. Check your current usage in the dashboard.

Rate limit headers

Every API response includes headers to help you track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your plan
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

When you hit the rate limit, a Retry-After header is also included indicating how many seconds to wait.

429 Too Many Requests

When you exceed your per-minute rate limit, the API returns a 429 status code:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again later."
  }
}

402 Usage Limit Exceeded

When you exceed your monthly screenshot quota, the API returns a 402 status code:

{
  "error": {
    "code": "usage_limit_exceeded",
    "message": "Monthly screenshot limit reached. Please upgrade your subscription."
  }
}

Checking your usage

Use the usage endpoint to check your remaining credits programmatically:

curl https://api.screenshotly.dev/v1/screenshots/usage \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY"

When using response_type: "json" for captures, the response includes a remaining_credits field.

Handling rate limits

Exponential backoff

When you receive a 429 response, wait before retrying:

async function captureWithBackoff(url, options) {
  const maxRetries = 5;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.screenshotly.dev/v1/capture', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.SCREENSHOTLY_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ url, options }),
    });

    if (response.ok) return response;
    if (response.status !== 429) throw new Error(`HTTP ${response.status}`);

    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
    console.log(`Rate limited. Retrying in ${delay}ms...`);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Rate limit retry attempts exhausted');
}

Best practices

Monitor usage — check the X-RateLimit-Remaining header or the usage endpoint before large operations
Stagger requests — spread requests over time instead of sending them all at once
Use batch processing — the batch endpoint processes up to 50 URLs per request
Respect Retry-After — use the header value for optimal retry timing
Upgrade your plan — if you consistently hit limits, consider upgrading at pricing
Cache results — store screenshot URLs and reuse them instead of recapturing the same pages

Overview

Capture

Screenshots

Resources

Limits by plan

Rate limit headers

429 Too Many Requests

402 Usage Limit Exceeded

Checking your usage

Handling rate limits

Exponential backoff

Best practices

​Limits by plan

​Rate limit headers

​429 Too Many Requests

​402 Usage Limit Exceeded

​Checking your usage

​Handling rate limits

​Exponential backoff

​Best practices

Limits by plan

Rate limit headers

429 Too Many Requests

402 Usage Limit Exceeded

Checking your usage

Handling rate limits

Exponential backoff

Best practices