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.
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-Limitis your per-minute limit, andRetry-Afteris the number of seconds left in the current window, never more than 60. Wait that long and retry. - Quota 429:
X-RateLimit-Limitis0, and the message gives the reset time. On paid plans,Retry-Aftercounts 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) sendsRetry-Afterand aretryAfterbody field on a 429, but noX-RateLimit-*headers.POST /api/jobs/batch(Growth and above) sends a 429 body with noRetry-Afterat all. Its message isRequest rate limit exceeded, a quota reset notice, orThe 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/batchqueues 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/jobscounts 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-Remainingfrom 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.warningandusage.limitevents 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-Aftermeans wait and retry.X-RateLimit-Limit: 0with 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.
About the Author

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.