Guide

How Do Screenshot API Rate Limits Work?

Two limits apply to every Screenshotly request: requests per minute and captures per month. Learn which one you'll hit first and how to pace workers to stay under both.

Asad AliOctober 25, 20258 min read

Every Screenshotly request is checked against two limits. One is a per-minute request limit, which protects the capture fleet from bursts. The other is a capture quota, which is what your plan pays for. Both return HTTP 429, but they need different fixes. Back off from the first. Plan around the second.

This guide covers capacity: the numbers, the headers, which limit you'll hit first, and how to pace several workers so they never hit the per-minute limit. For how to classify and retry every other error, see the error handling guide.

The relevant standards are RFC 6585 §4 for HTTP 429 and RFC 9110 for Retry-After. MDN has readable summaries of 429 and Retry-After.

The limits by plan

Plan Requests per minute Capture quota Quota resets
Free 5 100 total Never (lifetime allowance)
Basic ($14/mo) 40 2,500 / month 1st of the month, 00:00 UTC
Growth ($59/mo) 80 12,000 / month 1st of the month, 00:00 UTC
Scale ($199/mo) 200 50,000 / month 1st of the month, 00:00 UTC

Current prices and feature gates are on the pricing page.

How each limit is counted:

  • The per-minute limit is a fixed 60-second window that starts with your first request and applies to the whole account, across every API key. Each request that passes validation counts toward it, including requests that end in a 500 or are rejected with a 429.
  • The quota counts successful (2xx) captures made by all the API keys in a workspace. Failed captures cost nothing. If you set an optional hard request limit in dashboard settings, the lower of that and the plan quota applies.
  • Server-side caching doesn't save quota. A response served from Screenshotly's cache ("cache": true, Basic and above) is still a 200. It makes repeat captures faster but counts toward both limits. To cut usage, cache on your side. See the caching guide.
  • There are no automatic overages. Once the quota is used up, requests return 429 until it resets or you change plans.

Which limit will you hit first?

Divide the quota by the per-minute limit to see how long a full-speed run takes to use the whole month's allowance:

Plan Quota ÷ rate Minutes at full speed
Free 100 ÷ 5 20
Basic 2,500 ÷ 40 about 63
Growth 12,000 ÷ 80 150
Scale 50,000 ÷ 200 250

On every plan, a workload running at full speed uses up the month's quota in a few hours at most. That changes how you plan:

  • For bursty work (a nightly crawl, a bulk regeneration), the per-minute limit sets how long the burst takes. Pace to it.
  • Over a whole month, the quota is the real constraint. Track usage against it, and if you regularly run out, choose a larger plan rather than tuning concurrency.

Reading the headers

A successful synchronous capture returns:

HTTP/1.1 200 OK
Content-Type: image/png
X-Screenshot-Duration: 2140
X-Screenshot-Size: 48213
X-RateLimit-Limit: 12000
X-RateLimit-Remaining: 9876

Both X-RateLimit-* values describe the monthly capture quota: the effective limit, and the captures left after this one. Neither tells you how much of the current minute's limit is left, so pace per-minute traffic on your side (next section). When storage.enabled is set, the response is JSON, but the headers are the same.

A 429 from POST /api/screenshot looks like one of these:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 80
X-RateLimit-Remaining: 0

{"error":"Rate limit exceeded","message":"Request rate limit exceeded","retryAfter":23}
HTTP/1.1 429 Too Many Requests
Retry-After: 1468800
X-RateLimit-Limit: 0
X-RateLimit-Remaining: 0

{"error":"Rate limit exceeded","message":"Rate limit exceeded. Limit resets at 2026-12-01T00:00:00.000Z","retryAfter":1468800}
  • Per-minute 429: X-RateLimit-Limit is your per-minute limit, and Retry-After is the number of seconds left in the current window, never more than 60. Wait that long and retry.
  • Quota 429: X-RateLimit-Limit is 0, and the message gives the reset time. On paid plans, Retry-After counts down to the next UTC month. On Free it's effectively unbounded, because the allowance never resets. Don't retry. Alert someone or upgrade.

Other endpoints send less:

  • POST /api/jobs (async, Basic and above) sends Retry-After and a retryAfter body field on a 429, but no X-RateLimit-* headers.
  • POST /api/jobs/batch (Growth and above) sends a 429 body with no Retry-After at all. Its message is Request rate limit exceeded, a quota reset notice, or The batch exceeds your remaining allowance. Back off on your own schedule.

There's no X-RateLimit-Reset header. Code ported from other APIs that waits for that header will wait forever.

Pacing several workers with one shared limiter

The per-minute limit applies to the whole account, so a limiter in each process doesn't work. Ten workers that each allow 80 requests per minute add up to 800. Keep one source of truth instead. This Node.js pacer stores the next free send slot in Redis, spaces requests 60,000 / budget milliseconds apart, and uses the Redis server's clock so that workers on different machines agree on the time.

import { createClient } from 'redis';

// Growth plan: 80 requests/minute. Leave headroom for retries and ad-hoc calls.
const PLAN_RPM = Number(process.env.SCREENSHOTLY_RPM || 80);
const BUDGET_RPM = Math.floor(PLAN_RPM * 0.9);
const INTERVAL_MS = Math.ceil(60_000 / BUDGET_RPM);

// Reserve the next send slot. Redis TIME keeps every worker on one clock.
const RESERVE = `
  local t = redis.call('TIME')
  local now = t[1] * 1000 + math.floor(t[2] / 1000)
  local nextSlot = tonumber(redis.call('GET', KEYS[1]) or '0')
  local slot = math.max(now, nextSlot)
  redis.call('SET', KEYS[1], slot + tonumber(ARGV[1]), 'PX', 120000)
  return slot - now
`;

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

export async function acquireSlot(key = 'screenshotly:next-slot') {
  const waitMs = await redis.eval(RESERVE, { keys: [key], arguments: [String(INTERVAL_MS)] });
  if (waitMs > 0) await new Promise((resolve) => setTimeout(resolve, waitMs));
}

Call await acquireSlot() right before every fetch to the capture endpoint, retries included. Why spacing instead of counting per minute:

  • The server's window starts with your first request, not on the clock minute. A client that counts requests per calendar minute can send a full minute's allowance at 12:00:59 and another at 12:01:00, both inside one server window. Evenly spaced requests can't line up that way.
  • The 10% headroom leaves room for retries, a developer testing by hand, or a second service that shares the account. Whatever else uses the account has to fit inside that margin.
  • This controls when requests start, not how many are in flight. Captures take seconds, so also cap concurrency (for example with p-limit) to keep memory and open connections bounded.

We tested this pacer with three concurrent workers against a local Redis, using a high limit so the test ran quickly. Thirty requests never exceeded the budget in any one-second window.

When a 429 arrives anyway, honor Retry-After as the error handling guide describes, and treat it as a sign that something outside the pacer is using the account.

Getting more done within the limits

  • Batch jobs (Growth and above). POST /api/jobs/batch queues up to 20 captures in one call, and the call counts once against the per-minute limit. The batch is rejected with a 429 if it contains more captures than your remaining quota. Each capture still uses quota when it succeeds. See the batch processing guide.

    {
      "captures": [
        { "url": "https://example.com", "format": "png" },
        { "url": "https://example.com/pricing", "format": "webp", "fullPage": true }
      ]
    }
    
  • Async jobs (Basic and above). Queuing with POST /api/jobs counts once per job against the per-minute limit, and quota is used only when the worker finishes the capture successfully. You get results by polling or by webhook instead of holding a connection open. See async screenshots for when to use each mode, and the async jobs reference for the contract.

  • Don't capture the same thing twice. Store results keyed by URL and options, and skip captures whose source hasn't changed. This is the only kind of caching that saves quota.

Watching the quota

  • Log X-RateLimit-Remaining from successful responses. It's the most direct reading of how much quota is left. Under concurrency the value can be a request or two out of date, so treat it as a trend.
  • In dashboard settings, you can set a warning threshold (50 to 100% of the effective limit, 80% by default), an optional hard request limit below your plan's quota, and a usage notification webhook. The webhook receives usage.warning and usage.limit events containing { "usage", "limit" }. These events aren't signed, so treat them as a prompt to check the dashboard, not as an authoritative signal.
  • Alert on quota 429s right away. Per-minute 429s are a tuning problem. Quota 429s mean captures have stopped until the reset.

Summary

  • Two limits: 5/40/80/200 requests per minute, and 100 lifetime or 2,500/12,000/50,000 captures per month.
  • X-RateLimit-* headers on success describe the monthly quota. Pace per-minute traffic yourself.
  • A short Retry-After means wait and retry. X-RateLimit-Limit: 0 with a reset date means stop.
  • Share one pacer across every worker on the account, and stay about 10% under the limit.
  • Batch and async jobs get more done per request counted. Only caching on your side saves quota.

The full request reference is in the screenshot API docs.

rate limits
optimization
api
performance

About the Author

Asad Ali

Asad Ali

CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.

Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients

Frequently Asked Questions

What are Screenshotly's rate limits?

There are two. The per-minute request limit is 5 on Free, 40 on Basic, 80 on Growth and 200 on Scale. The capture quota is 100 captures in total on Free, then 2,500, 12,000 or 50,000 per month on Basic, Growth and Scale. Hitting either one returns HTTP 429. No overage is billed automatically.

Which rate limit headers does Screenshotly send?

Successful synchronous captures include X-RateLimit-Limit and X-RateLimit-Remaining. Both describe the monthly capture quota, not the per-minute limit. A 429 from the capture endpoint includes Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining: 0. There's no X-RateLimit-Reset header. The async jobs endpoint sends only Retry-After on a 429, and the batch endpoint sends neither.

Do failed or cached requests count against my quota?

Failed requests don't. Only 2xx responses use quota. Responses served from Screenshotly's cache (cache: true) are still 200 responses, so they use quota and count toward the per-minute limit. To save quota, cache images on your side.

How do I share a rate limit across several workers?

The per-minute limit applies to the whole account, across all API keys, so per-process limiters don't add up correctly. Keep the pacing state in one place, such as a Redis key that hands out send slots spaced 60,000 / budget milliseconds apart, and set the budget about 10% under your plan's limit.

When does the monthly quota reset?

Paid quotas reset at 00:00 UTC on the first day of each calendar month. The Free plan's 100 captures are a lifetime allowance and don't reset. You can set a lower hard limit, a warning threshold and a usage notification webhook in dashboard settings.

Ready to capture your first screenshot?

Get started with 100 free screenshots. No credit card required.

Related Articles