How to take a website screenshot with an API

The reliable workflow has four parts

A screenshot API accepts a webpage URL and rendering options, opens the page in a controlled browser, captures an image, and returns the result. The simplest integrations hide those steps behind one request, but production systems still need to account for navigation delays, retries, large pages, and artifact storage.

For that reason, an asynchronous job is usually a better contract than holding an HTTP connection open while Chromium works. The create request can return immediately with a stable job ID. Your application can then poll that resource until it succeeds, fails, or is canceled.

• Create a screenshot job with a public HTTP or HTTPS URL.
• Render the page in an isolated browser with explicit limits.
• Store the resulting image privately instead of returning a huge response body.
• Retrieve bounded metadata and a short-lived download URL.

Start with a small, explicit request

A useful first request contains the target URL, a viewport preset, the capture mode, and the image format. Avoid accepting arbitrary browser scripts or unlimited dimensions. A narrow schema is easier to document, meter, reproduce, and secure.

The example below shows the Screenshot API development-preview contract. Customer API access is not live yet, so treat it as an integration design rather than a production endpoint.

curl -X POST "https://your-domain.example/v1/screenshots" \
  -H "Authorization: Bearer shot_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: homepage-2026-07-30" \
  -d '{
    "url": "https://example.com",
    "preset": "desktop",
    "full_page": true,
    "format": "png"
  }'

Poll the job instead of guessing render time

Webpages do not finish at a predictable instant. Some render immediately, while others wait for fonts, client-side data, or a delayed consent interface. A queued job model lets the renderer use bounded waits without forcing your API client to choose a fragile timeout.

Poll with backoff, stop on a terminal state, and record the request ID when support is needed. A successful response should describe the final URL, image dimensions, format, byte size, timing, and artifact expiry. A failure should use a stable error category rather than leaking browser internals.

• Use an idempotency key so a network retry does not create two paid jobs.
• Back off between status checks instead of polling in a tight loop.
• Treat succeeded, failed, canceled, and deleted as terminal outcomes.
• Download the artifact before its signed URL or retention window expires.

A screenshot API is also a network-security boundary

The renderer follows customer-selected URLs, redirects, scripts, images, frames, and other subrequests. Checking the first URL in application code is not enough. The browser network must independently block localhost, private networks, cloud metadata, and special-use addresses after DNS resolution and on every redirect.

Chromium should run as a non-root process with its sandbox enabled, inside disposable contexts with hard CPU, memory, time, byte, viewport, popup, and download limits. The browser should not share credentials or a control network with the public API.

What to compare when choosing a provider

Compare the contract and failure behavior, not only the number of screenshot options. The most useful provider is the one your application can call repeatedly without ambiguous state, accidental duplicate charges, or public artifacts.