Screenshots

POST /v1/screenshots loads a URL in a real browser and returns an image of the page. Send a URL and you get back a jpeg (the default) or png, plus the page title and the image dimensions. Everything else — device, viewport, how long to wait, what to hide — is optional.

Capture a screenshot

curl -X POST https://api.bytekit.com/v1/screenshots \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

By default the call is synchronous: the request is held open for up to 28 seconds and returns 200 with the finished screenshot. The response is JSON — image_url is a link to the image, not the image bytes:

{
  "id": "ss_01a1210c210477f6838a6256629087e6",
  "status": "completed",
  "url": "https://example.com",
  "image_url": "https://<storage-host>/.../screenshot.jpeg?X-Amz-Signature=...",
  "page_title": "Example Domain",
  "image_width": 1440,
  "image_height": 900,
  "file_size_bytes": 62635,
  "credits_charged": 1,
  "billing": {
    "raw_bytes": 334,
    "factors": [
      {
        "name": "phase1_render",
        "value": 1.5,
        "reason": "phase 1 proxy fetch + render overhead"
      }
    ],
    "multiplier": 1.5,
    "billed_bytes": 501
  },
  "error_code": null,
  "error_message": null,
  "created_at": "2026-10-09T14:23:25.417Z",
  "completed_at": "2026-10-09T14:23:33.047Z",
  "expires_at": "2027-10-09T14:23:25.407Z",
  "poll_url": "https://api.bytekit.com/v1/screenshots/ss_01a1210c210477f6838a6256629087e6"
}

This response was returned by a real request. Two values are edited for the page: the signed image_url is shortened, and poll_url shows the production host.

The 200 response also carries X-Screenshot-* headers (the same id, status and timestamps as the JSON) and X-Quota-* headers reporting your quota.

If the capture is still running when the 28 seconds are up, the call returns 202 with status: "processing" and the same id. The capture keeps running in the background — poll it as described in Async captures.

Options

Send any of these alongside url. All are optional and the defaults suit most pages. Unknown fields are rejected with 422 validation_error.

curl -X POST https://api.bytekit.com/v1/screenshots \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "viewport": {"width": 1280, "height": 720},
    "dark_mode": true,
    "wait_until": "networkidle"
  }'

This request was run for real and returned 200 with "image_width": 1280 and "image_height": 720.

Output

Device

Page readiness

wait_until and wait_for_selector are Screenshot options. They are not POST /v1/scrape options — sending either there returns 422. See the Scraping guide.

Clean-up

Geo and language

Other

cookies and headers are not request options on any capture endpoint. Sending either returns 400 validation_error.

Async captures

For pages that take a while, add ?async=true to the URL, or send "async": true in the request body. Either one is enough, and false in one never cancels true in the other. The call returns 202 immediately with an ss_ id and status: "pending", and the capture runs in the background. POST /v1/scrape accepts the same two spellings.

# Start an async capture
curl -X POST "https://api.bytekit.com/v1/screenshots?async=true" \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Poll for the result
curl https://api.bytekit.com/v1/screenshots/ss_... \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE"

The first call returns:

{
  "id": "ss_01a1210d0e3a719589e9c3d70c4791d2",
  "status": "pending",
  "url": "https://example.com",
  "image_url": null,
  "page_title": null,
  "image_width": null,
  "image_height": null,
  "file_size_bytes": null,
  "credits_charged": 1,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-10-09T14:24:26.172Z",
  "completed_at": null,
  "expires_at": "2027-10-09T14:24:26.149Z",
  "poll_url": "https://api.bytekit.com/v1/screenshots/ss_01a1210d0e3a719589e9c3d70c4791d2"
}

This response was returned by a real request; poll_url shows the production host.

GET /v1/screenshots/{id} answers by state:

A failed capture is a successfully retrieved terminal state, so check status before reading image_url.

Cost

Screenshots are billed on bandwidth, not credits. A capture is billed on the bytes of the initial page fetch, multiplied by 1.5 — the extra 0.5 covers rendering the page. The size of the image file is not the basis. If that initial fetch is skipped or fails, the capture bills nothing.

In the example above, the page fetch transferred 334 bytes (raw_bytes), so the capture was billed 501 bytes (billed_bytes). The billing object is the authoritative breakdown; its factors[].reason text is descriptive and may change, so read value and multiplier rather than parsing it. The same figures arrive in the X-Raw-Bytes, X-Billing-Multiplier, and X-Billable-Bytes response headers.

The credits_charged field and the X-Screenshot-Credits-Charged header carry a legacy weight (1, 2 or 4, doubling for full_page and again for retina or mobile). It is recorded for reporting only and is not what you are billed. For how capture bandwidth is billed, see Bandwidth billing.

Errors

Errors use the unified envelope described in the Errors guide. These are the ones you are most likely to meet on this endpoint:

A 422 has two shapes. A validation failure carries the error envelope, where error is an object. A failed capture carries the screenshot resource instead — no error object, but flat error_code and error_message fields and an id you can look up later. Tell them apart by whether the top-level error key exists, not by status: both carry "status": "failed".

A validation failure looks like this (returned by a real request with "quality": 150):

{
  "status": "failed",
  "error": {
    "code": "validation_error",
    "message": "Invalid request body.",
    "http_status": 422,
    "failed_at": "2026-10-09T14:24:39.662Z",
    "details": {
      "formErrors": [],
      "fieldErrors": { "quality": ["Number must be less than or equal to 100"] }
    }
  }
}

Next steps

• Scraping — get page content instead of an image
• Monitors — capture a page on a schedule and be notified when it changes
• Errors — error codes and retry guidance
• Rate Limits — usage counting and concurrency slots
• API Reference: Screenshots — full request and response schema