Python SDK

The official Python SDK for the Screenshot Scout screenshot API. It is distributed on PyPI as screenshotscout and developed in the screenshotscout-python repository.

Sign up for Screenshot Scout or sign in. We automatically create a default API key for you when you sign up. Open the API Keys page, copy the access key and secret key, and store them in a safe place.

Capture a screenshot

Create a client with your access key and call capture() with the URL of the page you would like to take a screenshot of:

from pathlib import Path

from screenshotscout import (
    BinaryCaptureResponse,
    CaptureOptions,
    ScreenshotScoutClient,
)

with ScreenshotScoutClient("YOUR_ACCESS_KEY") as client:
    response = client.capture(
        "https://example.com",
        CaptureOptions(full_page=True),
    )

if not isinstance(response, BinaryCaptureResponse):
    raise RuntimeError("Expected a binary capture response")

Path("screenshot.png").write_bytes(response.bytes)

capture() sends a POST request by default. The response_type capture option selects the response format. When you leave it unset, the call returns a BinaryCaptureResponse: the image data is in bytes, and the exact screenshot URL is in screenshot_url when available.

Request a JSON result

Set response_type to CaptureResponseType.JSON to receive a JSON object with the screenshot URL instead of the image bytes:

from screenshotscout import (
    CaptureOptions,
    CaptureResponseType,
    JsonCaptureResponse,
    ScreenshotScoutClient,
)

with ScreenshotScoutClient("YOUR_ACCESS_KEY") as client:
    response = client.capture(
        "https://example.com",
        CaptureOptions(response_type=CaptureResponseType.JSON),
    )

if not isinstance(response, JsonCaptureResponse):
    raise RuntimeError("Expected a JSON capture response")

print(response.result.screenshot_url)

The parsed JSON body is in result.

Async client

Use AsyncScreenshotScoutClient in applications built on asyncio. Awaiting capture() waits for and returns the completed capture; it does not create a background job:

import asyncio

from screenshotscout import AsyncScreenshotScoutClient, BinaryCaptureResponse, CaptureOptions


async def main() -> None:
    async with AsyncScreenshotScoutClient("YOUR_ACCESS_KEY") as client:
        response = await client.capture(
            "https://example.com",
            CaptureOptions(full_page=True),
        )

    if isinstance(response, BinaryCaptureResponse):
        print(len(response.bytes))


asyncio.run(main())

Set capture options

CaptureOptions accepts every option in the screenshot option reference, with the same snake_case names: full_page, block_cookie_banners, and so on. Options with a fixed set of documented values have constants, such as CaptureFormat.WEBP and CaptureWaitUntil.LOAD; plain strings are also accepted.

Build a capture URL

Use build_capture_url() when a browser, an HTML <img> element, or another application needs to load the screenshot directly. Building the URL does not make an API request:

from screenshotscout import CaptureOptions, ScreenshotScoutClient

with ScreenshotScoutClient("YOUR_ACCESS_KEY") as client:
    capture_url = client.build_capture_url(
        "https://example.com",
        CaptureOptions(full_page=True, block_ads=True),
    )

print(capture_url)

The generated URL contains your access key. If the client has a secret key (see Signed requests), the URL is signed automatically; otherwise, it is unsigned. Treat generated URLs as sensitive. Before exposing one to a browser or user, add your secret key to the client and enable Require signed requests on the API Keys page.

Signed requests

Pass the API key's secret key as the secret_key argument when creating the client:

from screenshotscout import ScreenshotScoutClient

with ScreenshotScoutClient(
    "YOUR_ACCESS_KEY",
    secret_key="YOUR_SECRET_KEY",
) as client:
    response = client.capture("https://example.com")

The secret key stays in your application and is never transmitted. The client signs capture requests and generated capture URLs automatically. See the signed requests guide for details.

Errors

When the API returns a non-2xx response, the SDK raises ScreenshotScoutAPIError, with the machine-readable error code in error_code and the descriptive message in error_message. The SDK does not retry failed requests automatically. The repository README documents all error classes.

Full reference

This page covers installation and your first captures. For everything else, see:

The repository README: GET requests, timeouts, response types, error handling, and development setup.
The standalone examples: binary capture, JSON capture, the async client, and capture URL construction.
The screenshot option reference: service behavior and allowed values for every option.