Rate limits

The ScreenshotBuddy API limits how many requests an account may make per minute. This page explains what your limit is, how to read it off a response, and what happens when you go over it.

Your limit

An account may make up to 20 requests per minute by default. Larger plans carry a higher limit, and an account can be given a limit of its own, so treat 20 as the floor rather than the number your integration should hard-code.

The limit counts requests, not successful renders. A request that fails validation or comes back as 422 still uses one of the minute's attempts, even though it costs no credit.

Reading your limit off a response

Rather than keeping count yourself, read the headers the API sends back.

The two sets answer two different questions. Credits are how many you have; the rate limit is how fast you may spend them. Running out of credits is not fixed by waiting a minute, and hitting the rate limit costs you nothing.

The headers only arrive with an answer, so they tell you where you stand after you have spent a request. To find that out before you send one, ask the usage endpoint.

Checking your usage

A GET to /api/v1/usage reports where your account stands: the credits you have left, used and were granted this period, the plan you are on, the date the period resets, and the requests_per_minute your account is actually held to.

It describes your account rather than refusing on it. An account with no plan, or one that has spent every credit, is answered 200 with the numbers that say so, where a render would come back as 402.

It carries a limit of its own of 60 requests per minute, separate from the limit above. Checking your usage therefore never spends anything you were saving for a render, so you are free to ask before every batch.

curl "https://screenshotbuddy.io/api/v1/usage" \
  -H "Authorization: Bearer {token}"

{
    "credits": {
        "remaining": 8432,
        "used": 1568,
        "total": 10000
    },
    "plan": {
        "name": "Business",
        "slug": "business"
    },
    "period": {
        "started_at": "2026-08-01T00:00:00+00:00",
        "resets_at": "2026-09-01T00:00:00+00:00"
    },
    "rate_limit": {
        "requests_per_minute": 40
    }
}

plan and period are null for an account that has neither yet, so read them before you use them. The OpenAPI document describes the response in full.

Going over the limit

A request that goes over the limit is answered with HTTP status 429 and a Retry-After header. Nothing is rendered and no credit is spent, so waiting the stated number of seconds and sending the request again is all it takes. The errors page lists the other statuses worth retrying.

If you are working through a queue of pages, spread the requests out instead of firing them all at once. A short pause between calls keeps you inside the limit and finishes the batch sooner than a burst that spends most of its time being refused.

The playground

The playground has a limit of its own: one capture per minute, whatever your account may do through the API. It is there to try options out by hand, so the pace is set for a person rather than for a script.