Usage and limits

Ask the API how much of your allowance is left. This call is free.

curl "https://curlshot.com/api/v1/usage" \
  -H "X-Access-Key: YOUR_ACCESS_KEY"

{
  "plan": { "slug": "free", "name": "Free" },
  "period": { "start": "2026-10-02T23:09:55.000Z", "end": "2026-11-01T23:09:55.000Z" },
  "quota": 100,
  "used": 12,
  "remaining": 88,
  "bonus_remaining": 25,
  "rate_limit_per_minute": 10,
  "concurrency": 1,
  "full_page_max_height": 10000,
  "full_page_max_scale": 1,
  "video_max_seconds": 10
}

The numbers above are a sample. Yours depend on your plan.

What you can still take in total is remaining plus bonus_remaining. In the sample that is 88 + 25 = 113.

#The three limits

Every plan has three limits. They protect different things, so it helps to keep them apart.

We do not print the numbers here, because they differ per plan. You find them on the pricing page, and your own values in the GET /usage answer above.

A plan also limits how large one full-page screenshot can be. That is not a fourth counter: a request above the size limit is not refused, the screenshot is made at the limit. A full-page screenshot always counts as one. See Limits of your plan.

#What counts against your quota

The rule is short: one successful render uses one screenshot.

The size of the screenshot does not matter. A full-page capture of a long article counts the same as a small thumbnail.

On top of your plan's quota you can have bonus screenshots, from things like referrals. The plan's own screenshots are used first. When they are gone, renders keep working until the bonus is used up too.

#Read your limits from any response

You do not have to call /usage to keep track. Every answer to a request with a valid key carries these headers:

curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com" \
  --output example.png -D -

The -D - part tells curl to print the response headers. Here are the ones about limits, for the sample account from the top of this page:

HTTP/1.1 200 OK
content-type: image/png
cache-control: private, no-store
x-cache: MISS
x-concurrency-limit: 1
x-concurrency-remaining: 1
x-image-height: 1024
x-image-width: 1280
x-quota-limit: 100
x-quota-remaining: 112
x-quota-reset: 2026-11-01T23:09:55.000Z
x-ratelimit-limit: 10
x-ratelimit-remaining: 9
x-ratelimit-reset: 1791069120
x-reference-id: bcf05dcd0aae40cc84d621758c44e4f8
x-render-ms: 1240
x-request-id: bcf05dcd0aae40cc84d621758c44e4f8

Header names are not case-sensitive. curl prints them in lower case. We write them as X-Quota-Limit in the text because that is easier to read.

X-Quota-Remaining includes your bonus screenshots, so it can be larger than X-Quota-Limit. In the sample, 87 are left of the plan and 25 of the bonus, which makes 112.

Note the two date styles. X-Quota-Reset is a readable date. X-RateLimit-Reset is a plain number of seconds.

#Status calls have their own rate limit

Some calls render nothing. They only report on something:

• GET https://curlshot.com/api/v1/usage
• GET https://curlshot.com/api/v1/jobs/:id, the status of an async job
• GET https://curlshot.com/api/v1/batches/:id, the status of a bulk batch
• GET https://curlshot.com/api/v1/files/:id with an access key, a download of a stored file

These are free, and they are counted in a separate bucket. So checking on your jobs never uses up the requests you need for renders.

The bucket allows 10 times your plan's per-minute limit, and never less than 300 per minute. On a plan with 10 requests per minute, that is 300 status calls per minute. On a plan with 100, it is 1000.

On the answers to these calls, the three X-RateLimit-* headers describe this bucket, not your render limit:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-ratelimit-limit: 300
x-ratelimit-remaining: 299
x-ratelimit-reset: 1791069120

Your render limit is always in the body of GET /usage, as rate_limit_per_minute.

A stored file opened through its own url, the link with a token in it, is not counted at all.

#When the quota runs out

When remaining and bonus_remaining are both zero, the next render is refused:

{
  "error_code": "quota_exceeded",
  "error_message": "The screenshot quota for this billing period is used up.",
  "documentation_url": "https://curlshot.com/docs/errors#quota_exceeded"
}

Retrying does not help here. The quota comes back when the period resets, at the time in X-Quota-Reset. To continue sooner, move to a larger plan on the pricing page.

#When you send requests too fast

Send more requests in a minute than your plan allows, and you get this:

HTTP/1.1 429 Too Many Requests
content-type: application/json; charset=utf-8
retry-after: 12
x-ratelimit-limit: 10
x-ratelimit-remaining: 0
x-ratelimit-reset: 1791069120

{
  "error_code": "rate_limited",
  "error_message": "Too many requests. Slow down and retry after the indicated delay.",
  "documentation_url": "https://curlshot.com/docs/errors#rate_limited"
}

You get the same status 429 with the code concurrency_limit when too many of your renders are running at once.

Neither one is a real failure. Nothing was rendered and nothing was counted. Wait, then send the request again.

#Fair use limits

The renderers are shared by all customers. Three more rules keep one account from slowing down the others. Most accounts never notice them.

So with rate_limit_per_minute 60 and concurrency 5 from GET /usage, your queue holds 500 jobs and 30 renders may fail per minute. A plan can set its own numbers.

#A bulk call counts per item

A batch of 25 uses 25 requests of the current minute. When fewer are left, the call is refused and nothing is queued. A batch larger than your whole per-minute limit is accepted only when you have sent nothing else for a minute or two, and it uses the whole minute.

#The queue has a size

Jobs you start with async=true or with a bulk call wait in a queue. When the queue of your account is full, new jobs are refused:

{
  "error_code": "queue_limit",
  "error_message": "This account already has 500 jobs waiting to render; your plan allows 500 at a time. Nothing was queued. Wait for some to finish, then retry.",
  "documentation_url": "https://curlshot.com/docs/errors#queue_limit"
}

A job leaves the queue when it is done or has failed. Sync requests, the ones that return the screenshot directly, are not jobs and do not count.

Two more things hold for jobs:

• Your jobs render at most concurrency at once, across all our renderers. This is separate from the slots of your sync requests.
• The queue serves accounts in turn: everyone's first waiting job, then everyone's second, and so on. A large batch from another customer does not delay your single job.

#Failed renders are free, up to a point

A failed render costs you nothing, but it used a browser on our side. So the number of renders that may fail per minute is capped. What counts is a render that started and did not finish: a timeout, a page that could not be loaded, a selector that was not found, a request you cancelled half-way. A request that is refused before anything renders, such as invalid_options, does not count. Neither does a problem on our side.

When the cap is reached, new renders are refused for the rest of that minute:

{
  "error_code": "failure_limit",
  "error_message": "Too many renders of this account failed in the last minute (the limit on your plan is 30). Check the failing requests, then retry after the indicated delay.",
  "documentation_url": "https://curlshot.com/docs/errors#failure_limit"
}

The Retry-After header says how long to wait. Cache hits and status calls are still answered, because they use no browser. Jobs that are already queued are not thrown away: they wait until the minute has passed, then continue.

If you see this error, something in your requests fails again and again. Fix that first. Waiting alone brings the same error back.

#Back off with Retry-After

Backing off means waiting before you retry, so you do not hit the limit again right away. The Retry-After header tells you how many seconds to wait.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function fetchWithBackoff(url, tries = 5) {
  for (let attempt = 1; attempt <= tries; attempt++) {
    const response = await fetch(url)
    if (response.status !== 429) return response

    // Wait as long as the API asks. Fall back to a growing pause if the header is missing.
    const seconds = Number(response.headers.get('retry-after')) || attempt * 2
    await sleep(seconds * 1000)
  }
  throw new Error('Still rate limited after several tries')
}

A fuller version, which also retries temporary render errors, is on the errors page.

#Where to go next

• Errors: every error code, and which ones are safe to retry.
• Caching: the simplest way to use fewer screenshots.
• Bulk screenshots: start many renders with one request.
• Pricing: the quota, rate limit and concurrency of each plan.