Capture Screenshots

Context.dev’s Screenshot API finds and opens any page in a browser, captures a PNG screenshot, hosts it on a CDN, and sends back a URL to access it. It can dismiss cookie banners, capture the full scrollable height, and find standard pages (like pricing, login, etc.) for a given domain without you entering the exact path.

Integrate Context.dev's Screenshot API in your app

Open in Cursor

Prerequisites

A Context.dev API key. Sign up at context.dev/signup, copy the key from the dashboard (prefix ctxt_secret_), and export it:
export CONTEXT_DEV_API_KEY="ctxt_secret_..."

An SDK (optional). Install for your language, or skip the install and call directly with curl:

npm install context.dev

pip install context.dev

gem install context.dev

go get github.com/context-dot-dev/context-go-sdk

composer require context-dev/context-dev-php

Capture a screenshot

There are two ways to point at the page you want to capture:

Give a specific URL: pass directUrl with the full URL (e.g. https://stripe.com/pricing).
Give a domain and a page type: pass domain (e.g. stripe.com) for the homepage. Add a page type (choose from login, signup, blog, careers, pricing, terms, privacy, or contact) to let Context.dev’s resolver find the right URL on the domain.

# 1. Give a specific URL
curl -G https://api.context.dev/v1/web/screenshot \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "directUrl=https://stripe.com/pricing"

# 2. Give a domain and a page type
curl -G https://api.context.dev/v1/web/screenshot \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "domain=stripe.com" \
  --data-urlencode "page=pricing"

import ContextDev from "context.dev";

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

// 1. Give a specific URL
const exact = await client.web.screenshot({
  directUrl: "https://stripe.com/pricing",
});

// 2. Give a domain and a page type
const heuristic = await client.web.screenshot({
  domain: "stripe.com",
  page: "pricing",
});

console.log(exact.screenshot, heuristic.screenshot);

import os
from context.dev import ContextDev

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

# Give a domain (or `direct_url`) and a page type.
response = client.web.screenshot(
    domain="stripe.com",
    page="pricing",
)

print(response.screenshot)

require "context_dev"

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

# 1. Give a specific URL
exact = client.web.screenshot(
  direct_url: "https://stripe.com/pricing",
)

# 2. Give a domain and a page type
heuristic = client.web.screenshot(
  domain: "stripe.com",
  page: :pricing,
)

puts "#{exact.screenshot} #{heuristic.screenshot}"

package main

import (
    "context"
    "fmt"
    "os"

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

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

    // 1. Give a specific URL
    exact, err := client.Web.Screenshot(ctx, contextdev.WebScreenshotParams{
        DirectURL: param.NewOpt("https://stripe.com/pricing"),
    })
    if err != nil {
        panic(err)
    }

    // 2. Give a domain and a page type
    heuristic, err := client.Web.Screenshot(ctx, contextdev.WebScreenshotParams{
        Domain: param.NewOpt("stripe.com"),
        Page:   contextdev.WebScreenshotParamsPagePricing,
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(exact.Screenshot, heuristic.Screenshot)
}

<?php

use ContextDev\Client;

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

// 1. Give a specific URL
$exact = $client->web->screenshot(directURL: 'https://stripe.com/pricing');

// 2. Give a domain and a page type
$heuristic = $client->web->screenshot(domain: 'stripe.com', page: 'pricing');

echo $exact->screenshot, ' ', $heuristic->screenshot, PHP_EOL;

5 credits per successful call Context.dev finds and opens the page, closes any cookie consent pop-ups (when handleCookiePopup is set to "true"), takes a screenshot, uploads it to a CDN and returns the public URL.

Captures are cached for one day by default; pass maxAgeMs: 0 to force a fresh render, or up to 30 days for longer reuse.

Request Parameters

Pass either domain or directUrl, not both.

Parameter	Type	Default	Description
`domain`	string	—	Required unless `directUrl` is provided. Domain to screenshot (e.g. `stripe.com`).
`directUrl`	string (URI)	—	Required unless `domain` is provided. Exact URL to screenshot.
`fullScreenshot`	string enum (`"true"` / `"false"`)	`"false"`	`"true"` captures the full scrollable height; otherwise a single viewport frame.
`handleCookiePopup`	string enum (`"true"` / `"false"`)	`"false"`	When `"true"`, dismisses the cookie/consent banner before capture.
`viewport`	object `{ width, height }`	`{ width: 1920, height: 1080 }`	Browser viewport in pixels. `width` 240–7680, `height` 240–4320.
`page`	enum (`login` / `signup` / `blog` / `careers` / `pricing` / `terms` / `privacy` / `contact`)	—	Resolve the right URL for the page type via link-scraping heuristics. Only valid with `domain`, not `directUrl`.
`maxAgeMs`	integer	`86400000` (1 day)	Return a cached capture younger than this. `0` forces fresh. Max `2592000000` (30 days).
`waitForMs`	integer	`3000`	Browser wait after page load before capture. Min `0`, max `30000` (30 seconds).
`timeoutMS`	integer	—	Abort with 408 if the request exceeds this many milliseconds. Min `1000`, max `300000` (5 min).

Response

{
  "status": "ok",
  "code": 200,
  "domain": "stripe.com",
  "screenshot": "https://media.brand.dev/screenshots/cache/f7d1dab4f1fd942032eeb849f1ad9df7.png",
  "screenshotType": "viewport",
  "width": 1920,
  "height": 1080
}

Field	Type	Description
`status`	string	`"ok"` on success.
`code`	integer	HTTP status code, echoed for convenience.
`domain`	string	Normalized domain that was processed. For `directUrl` requests, the host parsed out of the URL.
`screenshot`	string	Public CDN URL of the captured PNG. Content-addressed: the same query against the same target returns the same URL until `maxAgeMs` expires.
`screenshotType`	enum	`"viewport"` or `"fullPage"`. Mirrors what was actually captured.
`width`	integer	Width of the captured image in pixels.
`height`	integer	Height in pixels. With `fullScreenshot: "true"`, this is the full scrollable height (often 5–20× the viewport).

Handle errors

The endpoint surfaces four failure modes:

Status	Meaning	What to do
400	Validation error: neither `domain` nor `directUrl` provided, both provided at once, `page` combined with `directUrl`, or a malformed value	Surface as a user-facing error. The response body’s `error_code` distinguishes `INPUT_VALIDATION_ERROR`, `WEBSITE_ACCESS_ERROR`, etc.
401	Missing or invalid API key	Re-check the env var and the dashboard.
408	`REQUEST_TIMEOUT`: the page didn’t render before `timeoutMS` elapsed (typically a cold hit)	Retry once with backoff, or prefetch the capture ahead of time.
500	Transient renderer or server error	Retry with exponential backoff.

A retry pattern that covers 500:

import ContextDev from "context.dev";

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

async function screenshotWithRetry(domain: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.web.screenshot({ domain });
    } catch (err: any) {
      if (err.status === 500 && i < maxRetries - 1) {
        await new Promise((r) => setTimeout(r, 2 ** i * 1000));
        continue;
      }
      throw err;
    }
  }
}

import os
import time
from context.dev import ContextDev, APIError

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

def screenshot_with_retry(domain, max_retries=3):
    for i in range(max_retries):
        try:
            return client.web.screenshot(domain=domain)
        except APIError as e:
            if e.status_code == 500 and i < max_retries - 1:
                time.sleep(2 ** i)
                continue
            raise

require "context_dev"

def screenshot_with_retry(domain, max_retries: 3)
  client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))
  max_retries.times do |i|
    return client.web.screenshot(domain: domain)
  rescue ContextDev::Errors::APIError => e
    raise unless e.status == 500 && i < max_retries - 1
    sleep(2 ** i)
  end
end

<?php

use ContextDev\Client;
use ContextDev\Core\Exceptions\APIStatusException;

function screenshotWithRetry(string $domain, int $maxRetries = 3) {
    $client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

    for ($i = 0; $i < $maxRetries; $i++) {
        try {
            return $client->web->screenshot(domain: $domain);
        } catch (APIStatusException $e) {
            if ($e->status === 500 && $i < $maxRetries - 1) {
                usleep((2 ** $i) * 1_000_000);
                continue;
            }
            throw $e;
        }
    }
}

For the full error code catalog, see Troubleshooting.

Use cases

Auto-generate on-brand campaign and preview images for every page.
Give your coding agent screenshotting tools to do QA or classification tasks.
Archive dated visual snapshots of pages for compliance or audits.
Power server-side link-preview / share-card generation for chat apps, comments, and any paste-a-URL flow.

Next steps

Prefetch for Faster Response

Hide cold-hit latency from your users.

Handle Rate Limits

Backoff strategies, client cache, and prefetch fallbacks.

Best Practices

Caching, error handling, and key hygiene.

Troubleshooting

Status codes, retry patterns, and common errors.

Get Started

Give it to your Agent

What can Context.dev do

Optimizations

No-code Integrations

Prerequisites

Capture a screenshot

Request Parameters

Response

Handle errors

Use cases

Next steps

Prefetch for Faster Response

Handle Rate Limits

Best Practices

Troubleshooting

​Prerequisites

​Capture a screenshot

​Request Parameters

​Response

​Handle errors

​Use cases

​Next steps

Prefetch for Faster Response

Handle Rate Limits

Best Practices

Troubleshooting

Prerequisites

Capture a screenshot

Request Parameters

Response

Handle errors

Use cases

Next steps