---
title: "Take a screenshot"
method: POST
path: "/screenshot"
---

# Take a screenshot

`POST /screenshot`

## Request

- Base URL: `https://localscreenshot.com/v1`
- URL: `https://localscreenshot.com/v1/screenshot`
- Auth: HTTP bearer

Waits for the screenshot and returns the image. A failed screenshot is not charged. Send an Idempotency-Key header to make a retry safe: the same key returns the same screenshot without charging twice.

## Headers

- `Idempotency-Key` string

## Request body

- ScreenshotRequest
  - `url` string, uri, required: The public http or https page to capture.
  - `country` string: Load the page from this country (ISO 3166-1 alpha-2 code, see /v1/countries). The response reports the country actually observed. If it cannot be obtained, the request fails and is not charged. Costs 2 credits instead of 1.
  - `viewport` string: Screen size as WIDTHxHEIGHT, for example 1440x900. Shortcut for viewport_width and viewport_height.
  - `viewport_width` integer: Width of the browser window, in pixels.
  - `viewport_height` integer: Height of the browser window, in pixels. With full_page, the image is taller than this.
  - `device_scale_factor` number: Pixel density. 2 gives a sharper, larger image.
  - `device` 'desktop' | 'desktop_hd' | 'laptop' | 'ipad' | 'ipad_pro' | 'ipad_mini' | 'iphone_15' | 'iphone_15_pro_max' | 'iphone_se' | 'pixel_8' | 'galaxy_s24': Capture as this device (screen size, pixel density, mobile browser).
  - `orientation` 'portrait' | 'landscape': Hold a phone or a tablet upright (portrait) or on its side (landscape). Needs a phone or tablet device.
  - `full_page` boolean: Capture the whole scrollable page instead of the visible part.
  - `selector` string: Capture only the first element matching this CSS selector.
  - `format` 'png' | 'jpeg' | 'webp' | 'pdf': File format. pdf saves the whole page as a document; it cannot be combined with selector or max_width.
  - `quality` integer: Quality for jpeg and webp. Ignored for png and pdf.
  - `color_scheme` 'light' | 'dark': Ask the page for its light or dark theme.
  - `language` string: Browser language, for example fr or fr-FR. Without it, a screenshot from a country uses the main language of that country.
  - `timezone` string: Browser time zone, for example Europe/Paris. Without it, a screenshot from a country uses the main time zone of that country.
  - `user_agent` string: User-Agent the page receives. A preset (googlebot, googlebot_mobile) or your own string. Useful to compare what a site shows to a crawler and to a visitor. A site that checks the crawler's IP address is not fooled.
  - `wait_for` string: Wait until an element matching this CSS selector is visible.
  - `click_selector` string: Click this one element before the screenshot, to open a menu, a tab or a dialog. A CSS selector matching exactly one element: use it when you know the code of the page. One click, no typing. Costs 1 more credit. Not with pdf, not with click_text.
  - `click_text` string: Same click, pointed at by the text a visitor reads on the element, for example "Show all": use it when you do not know the code of the page. The whole text of exactly one visible button, tab or other clickable element, upper or lower case. Not a part of it, not a pattern. One click, no typing. Costs 1 more credit. Not with pdf, not with click_selector.
  - `delay_ms` integer: Extra wait before the capture, in milliseconds.
  - `hide_selectors` string[]: Hide every element matching these CSS selectors. In a URL, separate them with commas.
  - `disable_animations` boolean: Freeze animations and transitions.
  - `hide_sticky_elements` boolean: Hide headers, bars and buttons that stay fixed on screen.
  - `block_cookie_banners` boolean: Removes most cookie banners. A banner the filters do not know stays in the picture.
  - `block_ads` boolean: Block ads. Screenshots taken from a country block ads by default: set block_ads to false to see them. Without a country, ads stay unless you set it to true.
  - `block_chat_widgets` boolean: Hide chat bubbles.
  - `close_popups` boolean: Close pop-ups and newsletter overlays.
  - `max_width` integer: Scale the image down to this width. Useful to keep it small for a vision model.
  - `response` 'image' | 'json': image returns the picture itself. json returns its link, the page details and the attestation.
  - `async` boolean: Return an id right away instead of waiting. Read the result at /v1/screenshots/{id}.

## Response `200`

The image, or the JSON document when response=json.

- Screenshot
  - `id` string
  - `status` 'queued' | 'running' | 'succeeded' | 'failed'
  - `image` object, nullable
    - `url` string: Short-lived link to the image.
    - `mime` string
    - `bytes` integer
    - `width` integer, nullable
    - `height` integer, nullable
    - `pages` integer, nullable: Number of pages, for a pdf.
    - `sha256` string
    - `truncated` boolean
    - `available_until` string, date-time
  - `page` object, nullable
    - `status` integer, nullable: HTTP status of the page. A page that answers 404 or 451 is still captured and charged.
    - `final_url` string, nullable
    - `title` string, nullable
    - `redirects` object[]
    - `load_incomplete` boolean: true when the image was taken before the page finished loading. It shows what was on screen at that moment.
    - `network_stopped` 'load_timeout' | 'visual_ready' | 'soft_byte_cap' | 'null', nullable: Why loading was stopped before the image was taken. "load_timeout": the page was displayed but never finished loading. "visual_ready": the page was displayed and stable. "soft_byte_cap": the page was displayed and had already loaded a lot of data. null when the page finished loading.
  - `country` object, nullable
    - `requested` string
    - `observed` string, nullable: The country observed at capture time, never the one requested.
  - `attestation` object, nullable: Signed technical attestation, only when a country was requested. It is not legal proof.
  - `credits` object
    - `charged` integer, nullable
    - `reserved` integer
    - `remaining` integer, nullable
  - `click` object: Present only when a click was asked for. What we observed, not what the page did with the click.
    - `verdict` string: "clicked" when the click was made.
    - `measurement_requests_held` integer: Analytics requests the page tried to send after the click. They were held back, never sent, and did not fail the screenshot.
  - `error` object, nullable

## Other responses

- `202`: Still running (async=true, or it took longer than the wait). Read it again at the Location header.
- `default`: An error. "code" is stable; "retryable" says whether trying again as is can work.

---

[API](https://skmtc.dev/localscreenshot/apis/screenshot-api.md) · [All operations](https://skmtc.dev/localscreenshot/apis/screenshot-api/llms.txt) · [OpenAPI document](https://skmtc.dev/localscreenshot/apis/screenshot-api/revisions/6027b204b742?raw)