> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Screenshot

> Render a URL in a real browser and get a PNG screenshot back.

Loads the page in the browser engine and returns a PNG of the viewport, or of the whole scrollable page with `full_page`. It is billed like a browser scrape plus the proxy tier, the same as `POST /v1/web/scrape` with `screenshot: true`. If the page loads but no screenshot comes back, the call returns `502` and costs **0 credits**.

## Request Body

**url** `string` *required*

The page to capture. Must be a valid HTTP or HTTPS URL.

**full\_page** `boolean` (default: false)

Capture the whole scrollable page instead of only the viewport.

**width** `integer`

Viewport width in pixels. Range: `320` – `3840`.

**height** `integer`

Viewport height in pixels. Range: `240` – `4320`.

**wait\_for** `string`

CSS selector to wait for before capturing, e.g. `"#main"`.

**country** `string`

ISO 3166-1 alpha-2 country code for the proxy exit, e.g. `"US"`. Country-level only; see [Proxy countries](https://docs.scrapebadger.com/web-scraping/proxy-countries.md) for coverage.

**proxy\_tier** `string` (default: simple)

Proxy pool: `simple`, `premium` or `ultra`. Same pricing as on [`/v1/web/scrape`](https://docs.scrapebadger.com/api-reference/endpoint/web-scraping/scrape).

Unknown fields are rejected with `422`.

## Response

**success** `boolean`

`true` when a screenshot was captured.

**url** `string`

The final URL after redirects.

**status\_code** `integer`

HTTP status code of the captured page.

**content\_type** `string`

Always `image/png`.

**screenshot** `string`

The PNG image, base64-encoded (no `data:` prefix).

**engine\_used** `string`

Browser engine that rendered the page.

**credits\_used** `integer`

Credits charged for this request.

**duration\_ms** `integer`

Total time in milliseconds.

## Examples

```bash cURL theme={null}
curl -X POST "https://scrapebadger.com/v1/web/screenshot" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "full_page": true, "width": 1280}' \
  | jq -r .screenshot | base64 --decode > page.png
```

```python Python theme={null}
import base64
import requests

response = requests.post(
    "https://scrapebadger.com/v1/web/screenshot",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"url": "https://example.com", "full_page": True, "width": 1280},
)
response.raise_for_status()
with open("page.png", "wb") as f:
    f.write(base64.b64decode(response.json()["screenshot"]))
```

```javascript JavaScript theme={null}
import { writeFile } from "node:fs/promises";

const res = await fetch("https://scrapebadger.com/v1/web/screenshot", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com", full_page: true, width: 1280 })
});
const { screenshot } = await res.json();
await writeFile("page.png", Buffer.from(screenshot, "base64"));
```

## Error Responses

| Status | Description |
| - | - |
| `402` | Insufficient credits |
| `422` | Invalid request, or the target blocked the request (not billed) |
| `429` | Rate limit exceeded, or the browser farm is at capacity (not billed) |
| `502` | The page loaded but no screenshot was captured (not billed) |

```json 200 theme={null}
{
  "success": true,
  "url": "https://www.example.com/",
  "status_code": 200,
  "content_type": "image/png",
  "screenshot": "iVBORw0KGgoAAAANSUhEUgAAAyAAAAO/CAIAAA...",
  "engine_used": "cloakbrowser",
  "credits_used": 6,
  "duration_ms": 4210
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.