Wayfern
Start building Sign in

Full-page screenshots

Capture a whole web page in one image with the Screenshot API: how lazy images load, where tall pages are cut at 20,000 px, and how to set the viewport size.

Updated

This guide shows how the Screenshot API captures a whole page, what it does before the capture so that lazy images appear, and how the viewport size changes the result.

Take a full-page screenshot

POST /api/v1/screenshot captures the full scrollable page by default. One capture costs 5 credits. A capture that fails is not charged.

curl -X POST https://api.wayfern.com/api/v1/screenshot \
  -H "Authorization: Bearer $WAYFERN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "capture": {
      "fullPage": true,
      "format": "png"
    }
  }'

The response has the image in data.screenshot and the page metadata in data.metadata:

{
  "success": true,
  "data": {
    "screenshot": {
      "url": "https://...",
      "urlExpiresAt": "2026-10-29T10:15:00.000Z",
      "key": "screenshots/USER_ID/9c1f4d02-7ab8-4e51-9d3f-2c60ba17e8c4.png",
      "contentType": "image/png",
      "bytes": 418223,
      "expiresAt": "2026-11-05T10:00:00.000Z"
    },
    "metadata": { "title": "Example Domain", "statusCode": 200, "sourceUrl": "https://example.com/" }
  },
  "credits": 5
}

url is a signed download link. It stops working at urlExpiresAt. The image itself is kept until expiresAt, 7 days after the capture. To get a new link for the same image, send its key to POST /api/v1/artifacts/link. The bulk screenshots guide shows that call.

Set fullPage to false to capture only the viewport.

How lazy images get loaded

Many pages load images only when they scroll into view. A capture of a page that was never scrolled shows empty boxes in their place. Before a full-page capture, Wayfern scrolls the page:

  1. It scrolls down one viewport height at a time, at least 200 px per step.
  2. It waits 120 ms after each step, so that the page can request its images.
  3. It stops at the bottom, or after 60 steps on a page that keeps growing.
  4. It scrolls back to the top and waits 300 ms.

Then it waits capture.settleMs milliseconds, 250 by default and at most 10,000. Increase settleMs when images or animations need more time after the scroll. Use waitFor (up to 30,000 ms) for a page that fills in its content after load, and waitForSelector for a page whose content appears in one known element.

The scroll runs only when fullPage is true.

The 20,000 px limit

A very tall page makes a very large image, and the browser cannot allocate an image of any height. Wayfern measures the page first. When the page is taller than 20,000 px, the capture is the top 20,000 px of the page. The request does not fail.

For a long page that you want to read in parts, ask for slices. The slices guide explains fullPageSlices. The slices cover the same 20,000 px.

Set the viewport size

The page renders at 1440 × 900 CSS pixels by default. Set width and height to change it, from 320 to 3840 each. With mobile: true the default is 390 × 844.

curl -X POST https://api.wayfern.com/api/v1/screenshot \
  -H "Authorization: Bearer $WAYFERN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "height": 800,
    "capture": { "fullPage": true }
  }'

The width sets the layout, so it changes where a responsive page breaks its columns. The height sets the size of one scroll step and of a viewport-only capture. For a full page, the image height is the page height, not the viewport height.

Clean pages by default

Cookie banners are dismissed before the capture (blockCookieBanners, on by default). Wayfern clicks an accept, dismiss or reject control, hides what is left of the banner, and turns scrolling back on, so that a full-page capture is not stuck at the viewport height. To remove ads too, set capture.blockAds. The ad and cookie banner guide explains both.

Limits

  • One capture: 5 credits.
  • Rate limit: 30 requests a minute to POST /api/v1/screenshot.
  • Timeout: 60 seconds by default, from 1 to 120 seconds with timeout.

All limits are on the limits page. Every field is in the Screenshot API reference.

Related guides