# Screenshot API

Source: https://docs.screenshotlens.com/docs/api/screenshots
Summary: Capture a still image of a public page as binary output or a JSON asset URL.

```http
GET /v1/screenshots
```

The target `url` must be absolute and use `http` or `https`.

## Basic request

**cURL**

```bash
curl -G "https://api.screenshotlens.com/v1/screenshots" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "response_type=json"
```

**JavaScript**

```ts
const params = new URLSearchParams({
  url: "https://example.com",
  api_key: process.env.SCREENSHOTLENS_API_KEY!,
  response_type: "json",
})

const response = await fetch(
  `https://api.screenshotlens.com/v1/screenshots?${params}`,
)

const capture = await response.json()
```

## Common parameters

| Parameter              | Type               | Default  | Limits                                                                                                                                                                                                     |
| ---------------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                  | absolute URL       | none     | Required. Must use `http` or `https`.                                                                                                                                                                      |
| `api_key`              | string             | none     | Required unless the request carries a dashboard session.                                                                                                                                                   |
| `response_type`        | `binary` or `json` | `binary` | Use `json` while integrating.                                                                                                                                                                              |
| `viewport_device`      | string             | none     | A Playwright device name, e.g. `iPhone 13` or `Pixel 5`. Emulates that device's viewport, scale factor, user agent, and touch support, overriding `viewport_width`, `viewport_height`, and `scale_factor`. |
| `viewport_width`       | integer            | `1280`   | `1` to `7680` pixels                                                                                                                                                                                       |
| `viewport_height`      | integer            | `720`    | `1` to `4320` pixels                                                                                                                                                                                       |
| `scale_factor`         | integer            | `1`      | `1` to `5`                                                                                                                                                                                                 |
| `delay`                | integer            | `0`      | `0` to `10` seconds, waited before capture                                                                                                                                                                 |
| `timeout`              | integer            | `30`     | `0` to `30` seconds                                                                                                                                                                                        |
| `wait_until`           | enum               | `Load`   | `Load`, `DomContentLoaded`, `NetworkIdle0`, `NetworkIdle2`                                                                                                                                                 |
| `dark`                 | boolean            | `false`  | Emulates a dark color scheme                                                                                                                                                                               |
| `block_ads`            | boolean            | `true`   | Blocks common ad resources                                                                                                                                                                                 |
| `block_cookie_banners` | boolean            | `true`   | Blocks and dismisses common cookie banners                                                                                                                                                                 |
| `block_chat`           | boolean            | `false`  | Blocks common chat widgets                                                                                                                                                                                 |
| `locale`               | string             | `en-US`  | BCP 47 language tag (e.g. `en-US`, `fr-FR`, `de`). Sets the browser's `Accept-Language` header and `navigator.language`, controlling which language i18n sites render in.                                  |

## Image parameters

| Parameter       | Type    | Default | Limits                                          |
| --------------- | ------- | ------- | ----------------------------------------------- |
| `image_format`  | enum    | `Png`   | `Png`, `Jpeg`, `Webp`                           |
| `image_quality` | integer | `80`    | `0` to `100`, applied to `Jpeg` and `Webp` only |

## Full-page parameters

| Parameter      | Type    | Default | Limits                                                                 |
| -------------- | ------- | ------- | ---------------------------------------------------------------------- |
| `full_page`    | boolean | `false` | Captures the whole page instead of the viewport                        |
| `scroll`       | boolean | `false` | Scrolls before capture to trigger lazy content, needs `full_page=true` |
| `scroll_delay` | integer | `200`   | `0` to `5000` milliseconds between scroll steps                        |
| `scroll_by`    | integer | `500`   | `100` to `10000` pixels per scroll step                                |
| `max_height`   | integer | none    | `1` to `50000` pixels, caps a tall page                                |

## Response modes

### JSON

`response_type=json` returns the stored asset URL.

```json
{
  "screenshot_url": "https://cdn.screenshotlens.com/captures/example.png",
  "credits_charged": 1
}
```

### Binary

The default `response_type=binary` returns the image file itself, with `Content-Type` set from `image_format`.

```bash
curl -G "https://api.screenshotlens.com/v1/screenshots" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --output capture.png
```

When ScreenshotLens can read the target page status, the binary response carries it in `X-Page-Status-Code`.

## Pricing

A viewport screenshot costs 1 credit and a full-page screenshot costs 2. See [Credits and Billing](https://docs.screenshotlens.com/docs/dashboard/credits-billing) for when the charge lands and when it does not.