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

# Take a screenshot

`GET /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.

## Query parameters

- `url` string, uri, required
- `country` string
- `viewport` string
- `viewport_width` integer
- `viewport_height` integer
- `device_scale_factor` number
- `device` 'desktop' | 'desktop_hd' | 'laptop' | 'ipad' | 'ipad_pro' | 'ipad_mini' | 'iphone_15' | 'iphone_15_pro_max' | 'iphone_se' | 'pixel_8' | 'galaxy_s24'
- `orientation` 'portrait' | 'landscape'
- `full_page` boolean
- `selector` string
- `format` 'png' | 'jpeg' | 'webp' | 'pdf'
- `quality` integer
- `color_scheme` 'light' | 'dark'
- `language` string
- `timezone` string
- `user_agent` string
- `wait_for` string
- `click_selector` string
- `click_text` string
- `delay_ms` integer
- `hide_selectors` string[]
- `disable_animations` boolean
- `hide_sticky_elements` boolean
- `block_cookie_banners` boolean
- `block_ads` boolean
- `block_chat_widgets` boolean
- `close_popups` boolean
- `max_width` integer
- `response` 'image' | 'json'
- `async` boolean

## Headers

- `Idempotency-Key` string

## 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)