---
title: "Capture a page screenshot"
method: POST
path: "/websitePreview/capture"
tags: ["Publishing"]
---

# Capture a page screenshot

`POST /websitePreview/capture`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/websitePreview/capture`
- Auth: HTTP bearer

Renders one page of the site in a real browser and returns the image, so you can check layout, spacing, and responsive behaviour that source-level checks cannot see. `path` is site-relative and may include a query string, so dynamic routes are captured with real values rather than placeholders. Focus the capture with `selector` (plus optional `padding` for surrounding context) or a `clip` rectangle in CSS pixels from the top-left of the page; the region is scrolled into view and captured within the configured viewport, so it must fit inside it, and these options exclude each other and `fullPage`. Fonts, images, and (for `fullPage`) lazy content are awaited before the capture, and CSS animations are fast-forwarded to their end state by default. Fails with 409 when the draft build is still in progress or has failed; poll `websiteSourceCode.deployment.status` and retry.

## Request body

- object
  - `websiteId` string, required
  - `path` string: Site-relative path to render, including any query string, e.g. `/blog/my-post`.
  - `target` 'head' | 'published': `head` renders the current draft; `published` renders the live site.
  - `viewport` 'desktop' | 'tablet' | 'mobile': Device class to render at.
  - `colorScheme` 'dark' | 'light': Browser color preference to emulate. Omit it to use the renderer default.
  - `fullPage` boolean: Capture the whole scrollable page instead of just the viewport. Excludes `selector` and `clip`.
  - `selector` string: Crop to the first element matching this CSS selector, scrolled into view. Preferred: it follows the layout at every viewport.
  - `padding` integer: CSS pixels of surrounding page to include on every side of the `selector` match.
  - `clip` object: Crop to this rectangle, in CSS pixels from the top-left of the rendered page at the chosen viewport; it is scrolled into view and must fit within the viewport. Only for regions no selector frames.
    - `x` number, required
    - `y` number, required
    - `width` number, required
    - `height` number, required
  - `scrollTo` union: Scroll to a CSS selector or an absolute Y offset before capturing.
    - string
    - integer
  - `waitForSelector` string: Wait for this CSS selector to match before capturing.
  - `delayMs` integer: Extra settle time before capturing, in milliseconds.
  - `freezeAnimations` boolean: Fast-forward CSS animations and transitions to their end state so captures are deterministic.

## Response `200`

Rendered page image.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `409`: The request conflicts with the current state of the resource.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

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