Screenshot API reference: parameters, answers and errors

Every parameter of the Screenshot API, what it answers and what each error means. To get started, see Screenshot API.

The request

GET https://api.monity.ai/v1/screenshot with the parameters in the query, or POST to the same address with a JSON body (the query counts too; the body wins). Send an API key with write access as Authorization: Bearer YOUR_API_KEY or X-Api-Key: YOUR_API_KEY. A key in the address is not accepted, because addresses end up in logs. The same endpoints also answer at https://api.monity.ai/api/v1/screenshot, beside the REST API.

Parameters

Parameter	Default	Meaning
`url`	Required, unless `setup` is given	The page: http or https, at most 2,048 characters. `https://` is added when no scheme is written. Private and local addresses, names that resolve to them, and addresses with a user name or password are refused.
`setup`	None	A saved setup’s id (see setups): its page, options and workspace. Other parameters override them.
`full_page`	`true`	The whole page, stitched, cut at 25,000 pixels tall. An image has at most 36 million pixels, so a wider page is cut sooner: at 1,920 pixels wide after 18,750, at 3,840 after 9,375. `false`: the viewport only.
`width`	`1440`	The viewport’s width, 320 to 3,840 pixels.
`height`	`900`	The viewport’s height, 320 to 2,160 pixels; the image’s height with `full_page=false`.
`device`	`desktop`	`mobile`: a phone-sized viewport, 390 × 844, unless `width` or `height` are given. The browser does not pretend to be a phone, so a site that picks its phone pages by browser shows its desktop page at phone width.
`format`	`png`	`png`, `jpeg` (or `jpg`) or `webp`. A WebP image is at most 16,383 pixels a side and 16 million pixels: a larger page is scaled down to fit, whole (a page 1,440 wide and 25,000 tall comes back 944 × 16,383).
`quality`	`80`	1 to 100, for JPEG and WebP. Ignored for PNG.
`delay`	`0`	Whole seconds, 0 to 10, to wait after the page has loaded, before the capture.
`block_ads`	`true`	Cookie and consent banners dismissed and ads blocked. `false`: the page as a first visit shows it.
`output`	`image`	`image`: the image’s bytes. `json`: the run, with the image’s address.
`cache`	`0`	Seconds, 0 to 10,800 (3 hours). Reuse a screenshot of the same page with the same options that your account took in this window, while its image is kept. A cached answer costs nothing; it is a run of its own and counts toward the 60 a minute.
`workspace`	The setup’s, or the account’s default	The id of the workspace whose checks pay: one of your account’s, not archived. Without it: the setup’s workspace, else the account’s oldest active team workspace, else its personal one.

Booleans are true or false (or 1 and 0). A value outside its range is refused with a 400, never changed to fit. Parameters Monity does not know are ignored. fullPage, blockAds, setupId and workspaceId are read as the same parameters.

Answers

The image

With output=image (the default), a 200 with Content-Type: image/png, image/jpeg or image/webp and the image’s bytes, and these headers:

Header	Says
`X-Monity-Run`	The run’s id, to find it later.
`X-Monity-Credits`	The credits this request used: `1`, or `0` from the cache.
`X-Monity-Credits-Remaining`	The paying workspace’s credits left.
`X-Monity-Cached`	`true` when the answer came from the cache.

JSON

With output=json, a 200 with the run (below), plus credits (1 or 0), cached and creditsRemaining, and the same headers:

{
  "id": "…",
  "status": "done",
  "source": "api",
  "url": "https://example.com/",
  "setupId": null,
  "workspaceId": 123,
  "options": {
    "full_page": true, "width": 1440, "height": 900, "device": "desktop",
    "format": "png", "quality": 80, "delay": 0, "block_ads": true
  },
  "imageUrl": "https://…",
  "imageExpired": false,
  "format": "png",
  "width": 1440,
  "height": 3210,
  "bytes": 845120,
  "durationMs": 7400,
  "credits": 1,
  "refunded": false,
  "cached": false,
  "cachedFrom": null,
  "error": null,
  "createdAt": "2026-11-03T09:00:00.000Z",
  "takenAt": "2026-11-03T09:00:06.900Z",
  "finishedAt": "2026-11-03T09:00:07.400Z",
  "expiresAt": "2026-11-03T12:00:07.400Z",
  "creditsRemaining": 9874
}

status is queued, running, done or failed; source is api or app.
imageUrl is a public address nobody can guess, kept for 3 hours (expiresAt). After that it is null and imageExpired is true.
width and height are the image’s. durationMs runs from the request to the image.
credits is 0 for a refunded run and for a cache hit, whose cachedFrom is the run it reused. error says in plain words why a run failed, and whether the check was refunded.

Still running

A screenshot not done within 90 seconds answers 202 with { id, status: "running", url, createdAt, poll }, a Location header and Retry-After: 5. It is paid and finishes on its own (or fails and is refunded). Ask for it with:

curl https://api.monity.ai/v1/screenshot/runs/RUN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Runs

Request	Answers
`GET /v1/screenshot/runs/{id}`	One run, with any key of the account.
`GET /v1/screenshot/runs`	`{ runs, nextBefore }`, newest first. `limit` 1 to 100 (20 by default); `before` the previous page’s `nextBefore` or a date; `setup` and `status` to filter.

Errors

An error answers JSON with statusCode, error and a message in plain words:

Status	`error`	Means
400	`invalid_parameter`	A value is wrong or out of range, or the address is private or local. `parameter` says which one.
401		No key, the key is not valid, or the key was sent in the address.
403		The key has no write access, or it is an old key with no owner recorded (make a new one).
405	`method_not_allowed`	`HEAD` takes no screenshot: use `GET` or `POST`.
402	`out_of_credits`	The workspace has no credits left.
404	`setup_not_found`, `run_not_found`	Not on this key’s account.
429	`too_many_running`	A screenshot of the account is already being taken: one at a time.
429	`rate_limited`	More than 60 screenshots in a minute for the account, cached ones included.
429	`too_many_failures`	10 of the account’s screenshots failed in the last hour. Check the pages, then try again later.
429	`queue_full`	Monity is taking as many screenshots as it can. Try again shortly.
502	`capture_failed`	The page could not be captured. The check is refunded; the answer has the run’s `id`, `refunded` and `creditsRemaining`.
502	`image_unavailable`	The screenshot was taken but its image could not be read back. Get it from the run.
503	`unavailable`	The service is not taking screenshots right now. The check is refunded; the answer has the run’s `id` and `refunded`.

A key also has the REST API’s limit of 120 requests a minute.