# Screenshots

Capture full-page or viewport screenshots. Accessed via `client.screenshots`.

## create

```ts
client.screenshots.create(opts: ScreenshotCreateRequest, params?: { async?: boolean }, requestOptions?: RequestOptions): Promise<ScreenshotCreateResponse>
```

POST /v1/screenshots — capture a screenshot.

`params.async` maps to the `?async=true` query param (queued 202 capture). The API also
accepts `async: true` in the request body, on screenshots and scrape alike; either one turns
it on. `params` is optional and `async` omitted-when-absent: `create(opts)` with no second argument posts to the
bare `/v1/screenshots` URL unchanged — existing single-arg callers are unaffected.

`requestOptions` is the THIRD positional parameter (after `params`) so both existing call
shapes stay unaffected. It carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
optional caller `signal`; both override the constructor's `timeoutMs` default.

## get

```ts
client.screenshots.get(id: ScreenshotId, requestOptions?: RequestOptions): Promise<ScreenshotGetResponse>
```

GET /v1/screenshots/\{id\} — poll a screenshot by ID.

A terminal-`failed` screenshot returns the `Error` envelope on a 200,
so narrow the result before reading `image_url`.

## createWithResponse

```ts
client.screenshots.createWithResponse(opts: ScreenshotCreateRequest, params?: { async?: boolean }, requestOptions?: RequestOptions): Promise<ApiResponse<ScreenshotCreateResponse>>
```

POST /v1/screenshots, returning the header set alongside the body.

Same request as `screenshots.create` — same method, path, body and
`RequestOptions` precedence — and `data` is exactly what `create()` resolves to.
`create()`'s own return type is UNCHANGED; this is an additive sibling.

The spec documents the `X-Screenshot-*` family (`ID`, `Status`, `URL`,
`Credits-Charged`, `Duration-Ms`, `Created-At`, `Completed-At`, `Expires-At`,
`Status-Code`, `Cache`, `Cache-Age`) plus `X-Raw-Bytes` / `X-Billable-Bytes` /
`X-Billing-Multiplier`; every one of them is on `headers`.

## getWithResponse

```ts
client.screenshots.getWithResponse(id: ScreenshotId, requestOptions?: RequestOptions): Promise<ApiResponse<ScreenshotGetResponse>>
```

GET /v1/screenshots/\{id\}, returning the header set alongside the body.

Same request as `screenshots.get`, and `data` is exactly what `get()`
resolves to (including the failed-envelope arm). `get()`'s own return type is
UNCHANGED; this is an additive sibling.

Call it for the typed body, NOT for header metadata: the spec declares
`GET /v1/screenshots/\{id\}` with NO `X-*` response headers, and a live GET returns
none, so `headers` carries only the transport's own entries (`Content-Type`, …).
The `X-Screenshot-*` / `X-Raw-Bytes` / `X-Billable-Bytes` / `X-Billing-Multiplier`
family is emitted by `POST /v1/screenshots` — use `screenshots.createWithResponse`
to read it. This matches `ByteKit.requestWithResponse` and the README,
which are the truth for what this endpoint emits.