# Taking screenshots

This guide will show you how to take screenshots using the ScreenshotBuddy API.

> Make sure you have read the [quickstart guide](https://screenshotbuddy.io/documentation.md). It will help you understand how to authenticate and make requests to the API.

## Options

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `url` | string | yes |  | The URL of the page to render. It must start with `http://` or `https://`, be at most `2048` characters long, and point at a publicly reachable host. Private, loopback and internal addresses are refused. |
| `fullPage` | boolean | no | `false` | Whether to capture the entire scrollable page instead of just the viewport. Defaults to `false`. Screenshots only; sending it with `pdf` is rejected, because a PDF always prints the whole document. |
| `pdf` | boolean | no | `false` | Set this to `true` to render a PDF instead of an image. It changes which other parameters are accepted, so see [creating PDFs](https://screenshotbuddy.io/documentation/creating-pdfs.md) for the options that belong to that mode. Defaults to `false`. |
| `format` | string | no | `png` | The image format to return. Possible values are `png`, `jpeg` and `webp`. Defaults to `png`. Screenshots only; sending it with `pdf` is rejected. Use `paperFormat` to set the paper size of a PDF. |
| `quality` | integer | no |  | The quality of the image, between `1` and `100`. It applies to lossy formats only, so `format` has to be `jpeg` or `webp`; sending it with `png` is rejected. Screenshots only; sending it with `pdf` is rejected. |
| `width` | number | no |  | The viewport width of a screenshot, or the paper width of a PDF, between `1` and `10000`. Must be used together with `height`. For a PDF it overrides `paperFormat` and is read in the unit set by `marginUnit`. |
| `height` | number | no |  | The viewport height of a screenshot, or the paper height of a PDF, between `1` and `10000`. Must be used together with `width`. For a PDF it overrides `paperFormat` and is read in the unit set by `marginUnit`. |
| `scale` | integer | no | `1` | In this mode, between `1` and `3`. The scale of the rendering, between `1` and `3` for screenshots and between `0.1` and `2` for PDFs. Screenshots take whole numbers only, because the browser renders at whole device scale factors; PDFs take fractions. Defaults to `1`. A value outside the range of the mode you are in is rejected. |
| `delay` | integer | no |  | How long to wait before capturing, in milliseconds, between `0` and `10000`. Useful for pages that animate on load. Screenshots only; sending it with `pdf` is rejected, because the PDF renderer has no way to wait a fixed amount of time before it prints. |
| `selector` | string | no |  | A CSS selector. Only the first element that matches it is captured, instead of the page. At most `512` characters, and it may not contain single quotes, backslashes or control characters, so write attribute selectors with double quotes: `a[href="/pricing"]`. It chooses what to capture, so it cannot be combined with a clip region or with `fullPage`. Screenshots only; sending it with `pdf` is rejected. |
| `clipX` | integer | no |  | The distance from the left edge of the page to the region to capture, in pixels, between `0` and `10000`. All four clip parameters (`clipX`, `clipY`, `clipWidth`, `clipHeight`) have to be set together. A clip region chooses what to capture, so it cannot be combined with `selector` or with `fullPage`. Screenshots only; sending it with `pdf` is rejected. |
| `clipY` | integer | no |  | The distance from the top edge of the page to the region to capture, in pixels, between `0` and `10000`. Set it together with the other three clip parameters. Screenshots only; sending it with `pdf` is rejected. |
| `clipWidth` | integer | no |  | The width of the region to capture, in pixels, between `1` and `10000`. Set it together with the other three clip parameters. Screenshots only; sending it with `pdf` is rejected. |
| `clipHeight` | integer | no |  | The height of the region to capture, in pixels, between `1` and `10000`. Set it together with the other three clip parameters. Screenshots only; sending it with `pdf` is rejected. |
| `omitBackground` | boolean | no | `false` | Whether to render the page background transparent. Defaults to `false`. The format has to be able to hold transparency, so `png` or `webp`; sending it with `jpeg` is rejected rather than answered with a black background. Screenshots only; sending it with `pdf` is rejected. |
| `waitForSelector` | string | no |  | A CSS selector to wait for before capturing. The render continues once an element matching it exists. At most `512` characters, and under the same character restriction as `selector`: no single quotes, backslashes or control characters. Screenshots only; sending it with `pdf` is rejected. |
| `waitUntil` | string | no | `networkidle2` | The load event to wait for before capturing. Possible values are `load`, `domcontentloaded`, `networkidle0` (no network connections for half a second) and `networkidle2` (at most two). Defaults to `networkidle2`. Screenshots only; sending it with `pdf` is rejected. |
| `cache` | boolean | no | `true` | Whether an identical repeat of this request may be answered with the rendering we already made, and whether this rendering is kept for the next one. Defaults to `true`. A cached answer costs no credit, says so with `X-Cache: HIT`, and is counted against the account's cached-answer limit rather than against its renders; send `cache=0` to render the page again, which costs a credit and a render slot as any render does. Entries belong to your own account. See [caching](https://screenshotbuddy.io/documentation/caching.md) for the whole picture. |
| `cacheTtl` | integer | no | `86400` | How long the rendering is kept, in seconds, between `60` and `2592000` (thirty days). Defaults to `86400`. Sending it with `cache=0` is rejected, because there is no lifetime to set on a rendering that is not being kept. |

The PDF options are a different set, listed on the [creating PDFs](https://screenshotbuddy.io/documentation/creating-pdfs.md) page.

## What the target answered

A login wall renders. So does a `404` page, and a "too many requests" notice. The capture comes back as a crisp `200` with a real image in it, because that is genuinely what the page served, and nothing about the file itself says it is not the page you had in mind.

A screenshot answer therefore carries `X-Target-Status`: the status the page itself answered while we were loading it, which is a different thing from the status of our response to you. A rendered `404` page is a `200` from us carrying `X-Target-Status: 404`. Read it before you store a capture, and you will not quietly fill a bucket with pictures of a sign-in form.

A `4xx` or `5xx` target still costs a credit. We loaded the page and rendered what the server served, which is the work you asked for, and capturing an error page on purpose is a perfectly ordinary thing to want. The header is there so you can tell the two apart, not so you can be refunded for one of them.

A challenge page is the case the header cannot flag for you. A bot check, Cloudflare's "checking your browser" interstitial or anything shaped like it, is usually served as a `200`, so `X-Target-Status: 200` is a truthful answer about a page that is not the one you meant. A consent wall or a cookie banner covering the content is the same shape. Nothing failed when a capture comes back as a picture of a challenge: the site served that to us because we arrived as automated traffic, and the render is billed like any other. `delay` and `waitForSelector` help when the interstitial clears on its own; when it does not, there is nothing you can send that gets us past it, because the API carries neither your credentials nor your cookies. A login wall that answers a real `401` or `403` at least says so in the header.

The header is absent when we were not told a status, and absent means not known rather than `200`. [PDFs](https://screenshotbuddy.io/documentation/creating-pdfs.md) never carry it: the renderer reports nothing at all about the page behind a PDF render. An element capture, one that names a `selector`, carries none either, and for a close cousin of that reason: the one renderer endpoint that can capture a single element is the one that says nothing about the page it loaded. Neither do captures we cached before this header existed, until they lapse and are rendered again.

## The playground

The most common options on this page are controls in the playground at https://screenshotbuddy.io/playground. Change the viewport, switch the image type, and choose what the capture covers: the viewport, the whole page, one element named by a CSS selector, or a pixel region. The result appears next to the code that produces it. The options with no control of their own, `waitForSelector` and `omitBackground` among them, you add to the query string of the generated snippet yourself.