---
title: "Screenshot a page"
method: POST
path: "/v1/web/screenshot"
tags: ["Media"]
---

# Screenshot a page

`POST /v1/web/screenshot`

## Request

- Base URL: `https://api.hydrafetch.com`
- URL: `https://api.hydrafetch.com/v1/web/screenshot`
- Auth: API key in header `X-API-Key`

Capture a full-page PNG screenshot of a rendered page.

## Request body

- ScreenshotRequestDto
  - `url` string, required: The URL to screenshot. Must be http(s).
  - `fullPage` boolean: Capture the entire scrollable page instead of just the viewport. Default off.
  - `waitFor` number: Extra milliseconds to let the page settle before capture.
  - `timeout` number: Overall time budget for the request, in milliseconds.
  - `maxAge` number: Reuse a stored screenshot if it is younger than this many milliseconds. Defaults to 7 days, so a repeated request returns the stored PNG with `cached: true` without re-rendering — which also means it returns immediately and does not apply `waitFor`. Pass 0 to force a fresh capture.
  - `viewport` 'desktop' | 'laptop' | 'tablet' | 'mobile': Screen size to render at. Defaults to desktop (1920x1080). Ignored when width/height are given explicitly.
  - `viewportWidth` number: Exact viewport width in pixels. Overrides `viewport`.
  - `viewportHeight` number: Exact viewport height in pixels. Overrides `viewport`. With fullPage the capture still extends to the full page height.

## Response `200`

- ScreenshotResponseDto
  - `data` WebScreenshotDataDto, required
    - `url` string, required: The URL you requested.
    - `finalUrl` string, required: The final URL after any redirects.
    - `status` number, required: HTTP status of the captured page.
    - `screenshot` string, required: Public URL of the captured PNG. Stable for the same URL and options.
    - `screenshotType` 'fullPage' | 'viewport', required: Whether the capture covers the whole scrollable page or just the viewport.
    - `width` number, required: Image width in pixels.
    - `height` number, required: Image height in pixels.
    - `cached` boolean, required: True when a stored screenshot was reused instead of capturing a new one.

## Other responses

- `400`: The request body or query failed validation.
- `401`: The X-API-Key header is missing, malformed, or names a key that no longer exists.
- `402`: The workspace has no credits left for this request. Nothing was charged and nothing was fetched.
- `403`: The key is valid but the workspace may not make this request.
- `404`: No such job, or the id belongs to another workspace.
- `422`: The target site did not respond, or we could not read that page. This is a fact about that URL rather than a fault on our side, and retrying it will not change the answer. When details.retryAfterSeconds is present, asking again before then returns this same answer. Nothing was charged.
- `429`: The workspace exceeded its per-minute request limit. Read the RateLimit headers, or Retry-After on this response, and retry after the window resets.
- `500`: Unexpected server error. Nothing was charged.
- `503`: A dependency needed for the requested formats is unavailable. Safe to retry.

---

[API](https://skmtc.dev/hydrafetch/apis/hydrafetch-api.md) · [All operations](https://skmtc.dev/hydrafetch/apis/hydrafetch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hydrafetch/apis/hydrafetch-api/revisions/b28322984b4b?raw)