Capture a screenshot

The Screenshot API opens a page in a browser, captures a PNG, and returns image data through a JSON response. Standard requests return a hosted image URL; eligible zero-data-retention requests return an in-memory data URL.

Capture an exact URL

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

curl --get https://api.context.dev/v1/web/screenshot \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "directUrl=https://example.com/pricing" \
  --data-urlencode "viewport[width]=1440" \
  --data-urlencode "viewport[height]=900" \
  --data-urlencode "handleCookiePopup=true"

import ContextDev from "context.dev";

const client = new ContextDev({
  apiKey: process.env.CONTEXT_DEV_API_KEY,
});

const result = await client.web.screenshot({
  directUrl: "https://example.com/pricing",
  viewport: { width: 1440, height: 900 },
  handleCookiePopup: true,
});

console.log(result.screenshot, result.width, result.height);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

result = client.web.screenshot(
    direct_url="https://example.com/pricing",
    viewport={"width": 1440, "height": 900},
    handle_cookie_popup=True,
)

print(result.screenshot, result.width, result.height)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

result = client.web.screenshot(
  direct_url: "https://example.com/pricing",
  viewport: {width: 1440, height: 900},
  handle_cookie_popup: true,
)

puts result.screenshot
puts "#{result.width} × #{result.height}"

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
    "github.com/context-dot-dev/context-go-sdk/v2/packages/param"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    result, err := client.Web.Screenshot(context.Background(), contextdev.WebScreenshotParams{
        DirectURL: param.NewOpt("https://example.com/pricing"),
        Viewport: contextdev.WebScreenshotParamsViewport{
            Width: param.NewOpt[int64](1440),
            Height: param.NewOpt[int64](900),
        },
        HandleCookiePopup: param.NewOpt(true),
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Screenshot, result.Width, result.Height)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$result = $client->web->screenshot(
    directURL: 'https://example.com/pricing',
    viewport: ['width' => 1440, 'height' => 900],
    handleCookiePopup: true,
);

echo $result->screenshot, PHP_EOL;
echo $result->width, ' × ', $result->height, PHP_EOL;

The endpoint costs 1 credit. Pass exactly one of directUrl and domain.

Find a page by type

If you know the domain but not the page URL, provide domain and a supported page type:

curl --get https://api.context.dev/v1/web/screenshot \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "domain=example.com" \
  --data-urlencode "page=pricing"

const result = await client.web.screenshot({
  domain: "example.com",
  page: "pricing",
});

console.log(result.screenshot);

result = client.web.screenshot(domain="example.com", page="pricing")
print(result.screenshot)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

result = client.web.screenshot(domain: "example.com", page: :pricing)
puts result.screenshot

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
    "github.com/context-dot-dev/context-go-sdk/v2/packages/param"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    result, err := client.Web.Screenshot(context.Background(), contextdev.WebScreenshotParams{
        Domain: param.NewOpt("example.com"),
        Page: "pricing",
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Screenshot)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$result = $client->web->screenshot(domain: 'example.com', page: 'pricing');
echo $result->screenshot, PHP_EOL;

Supported page types are login, signup, blog, careers, pricing, terms, privacy, and contact. Page resolution uses site links and heuristics. Use directUrl when the exact page is known or the resolved page must be deterministic.

Choose the capture mode

Need	Parameters	Behavior
One browser frame	`viewport`	Captures the configured viewport, 1920 × 1080 by default.
Entire scrollable page	`fullScreenshot: "true"`	Returns a full-page image.
A vertical slice	`scrollOffset`	Returns a viewport-sized slice beginning at the offset; takes precedence over `fullScreenshot`.
A light or dark site theme	`colorScheme`	Emulates the selected browser color scheme.
More time for client rendering	`waitForMs`	Waits 0 to 30 seconds after initial page load.
A regional page variant	`country`	Routes browser traffic through the selected country.

Viewport width can be 240 to 7,680 pixels and height can be 240 to 4,320 pixels. scrollOffset accepts 0 to 100,000 pixels. The final offset slice can be shorter than the viewport near the bottom of a page. fullScreenshot is a string query enum in the HTTPS API, so use "true" or "false" in SDK calls when required by the generated type.

Handle overlays

Two controls address obstructive UI:

handleCookiePopup=true asks the browser to dismiss detected cookie or consent UI.
clearPopups=true asks for broader cleanup of detected overlays and also includes consent UI.

Cleanup is heuristic. It can miss a custom dialog or change the state you intended to document. Compare a capture with and without cleanup when visual fidelity matters.

Control freshness

Screenshots are cached for one day by default. Use:

maxAgeMs=0 when the image must be captured again;
a larger value, up to 30 days, when reuse matters more than freshness;
cache_metadata in the response to record whether the result was a cache hit.

Parameters that change the rendered result should be part of your own application cache key, including target, viewport, mode, popup handling, country, wait time, and scroll offset.

Read the response

{
  "status": "ok",
  "code": 200,
  "domain": "example.com",
  "screenshot": "https://media.example/screenshot.png",
  "screenshotType": "viewport",
  "width": 1440,
  "height": 900,
  "cache_metadata": {
    "status": "miss",
    "age_ms": 0
  }
}

The response is JSON, not raw PNG bytes. screenshotType is viewport or fullPage; inspect the returned width and height rather than assuming the requested size was produced. With zdr=enabled, the screenshot field is a data:image/png;base64,... URL instead of a hosted image URL. ZDR must be enabled for your organization, and a successful response includes X-Context-ZDR: true. See Zero data retention.

Screenshot URLs or data URLs may contain sensitive rendered content. Do not put authenticated pages, personal data, or secrets into a public asset pipeline without appropriate access controls and retention rules.

Common failures

Symptom	What to check
`400`	Provide one target, use a supported page type, and validate viewport or offset bounds.
`WEBSITE_BLOCKED`	The page returned a challenge, CAPTCHA, or login shell. Try an authorized regional route or surface a fallback.
Capture is too early	Increase `waitForMs` within your latency budget.
Wrong page	Replace `domain` plus `page` with an exact `directUrl`.
Overlay remains	Try `clearPopups`, then verify that cleanup did not hide intended content.
`408` or `429`	Use bounded retries and honor `Retry-After`.

The Screenshot endpoint does not accept browser actions.

Next steps

Screenshot API reference

Review capture options and the full response contract.

Branded campaign assets

Use captured images in a branded campaign workflow.

Use browser actions

Interact with a page before extracting text or page images.

Set timeoutOpts.milliseconds for the end-to-end deadline. Partial mode requires at least 15,000 ms and marks an interrupted capture with finalDOMState: "still-loading". See Timeouts and partial results.

Get started

Web data

Brand data

Automation

Account and billing

Production

Capture an exact URL

Find a page by type

Choose the capture mode

Handle overlays

Control freshness

Read the response

Common failures

Next steps

Screenshot API reference

Branded campaign assets

Use browser actions

​Capture an exact URL

​Find a page by type

​Choose the capture mode

​Handle overlays

​Control freshness

​Read the response

​Common failures

​Next steps

Screenshot API reference

Branded campaign assets

Use browser actions

Capture an exact URL

Find a page by type

Choose the capture mode

Handle overlays

Control freshness

Read the response

Common failures

Next steps