API Reference

The official SDKs and the CLI handle these details for you. This page is for calling the API directly over HTTP, or for understanding how requests work.

Requests

Send every capture request to this endpoint, using POST or GET:

https://api.screenshotscout.com/v1/capture

POST

Send the screenshot options as a JSON object in the request body, with a Content-Type: application/json header. The keys are the option names from Screenshot Options. Repeated options, such as cookies or hide_selectors, take an array of strings, and booleans and numbers are plain JSON values. This is the request the SDKs send.

Request example:

curl "https://api.screenshotscout.com/v1/capture" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/",
    "full_page": true,
    "hide_selectors": [".cookie-banner", "#ad-overlay"]
  }' \
  -o "screenshot.png"

For POST requests, we ignore query parameters, so put every option in the body.

GET

Send the screenshot options as query parameters. To pass several values for a repeated option, repeat the parameter. Use GET when something else loads the URL, such as an <img> tag, and sign the request before you share the URL.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&full_page=true&hide_selectors=.cookie-banner&hide_selectors=#ad-overlay

Authentication

Send your access key in the Authorization header:

Authorization: Bearer YOUR_ACCESS_KEY

You can also send it as the access_key option, either as a query parameter for GET or as a field in the JSON body for POST. If you send both, they must match.

You'll find your access key on the API Keys page.

Responses

By default, the response is the screenshot itself, with a Content-Type that matches the format you requested. The Screenshot-Scout-Screenshot-URL header contains a temporary URL of the same screenshot.

To get a JSON object with the screenshot URL instead, set response_type to json:

{
  "screenshot_url": "https://cdn.screenshotscout.com/cdafae824c3a09d30a9660cd6473025b7ec7d9d8828722490502511c97076163.png"
}

Screenshot URLs expire after 4 hours by default. See response_type for how to keep screenshots longer.

Errors

When a capture fails, we return a JSON object with a machine-readable error code and a descriptive message, and the HTTP status code indicates the type of the error:

{
  "error_code": "invalid_options",
  "error_message": "One or more options are invalid.",
  "errors": [
    {
      "option": "url",
      "message": "The \"url\" option is required."
    }
  ]
}

The errors array is only present for invalid_options. See Errors for every error code.

Rate limits

Your plan has a per-minute request limit and a monthly quota. When you exceed either one, we return HTTP 429 with the rpm_limit_exceeded or monthly_quota_exhausted error code, and a Retry-After header with the number of seconds to wait before retrying. Only successful captures that aren't served from the cache count toward your monthly quota.

Timeouts

A capture can take as long as the timeout option allows, which is 120 seconds by default and up to 240 seconds. Set your HTTP client's timeout higher than that, so it doesn't give up before the response arrives.

Next steps