Full-Page Screenshot API: Capture an Entire Web Page
Last updated:
URLBooth captures an entire scrolling web page as one image when you send "fullPage": true to POST /v1/screenshots. Without it you get only the first screen of the chosen device. Output is PNG, JPEG or WebP, and the request is rejected if the page is larger than the size limits below.
What does fullPage do?
The browser loads the page at the width of the device you chose, then captures the full scrollable height instead of just the visible viewport. The page width stays the device width, so a mobile preset gives a tall, narrow image and a desktop preset a wide one. The default device is desktop (1440 pixels wide).
Full-page captures are rendered at 1x pixel density, even on devices that normally render at 2x. That keeps very tall pages inside the size limits, but the image is less sharp on Retina screens than a viewport capture of the same device.
How do I take a full-page screenshot with the API?
Add fullPage to the JSON body. Everything else works as in the options reference: pick a device, a format, and leave cleanup on to remove cookie banners and ads. WebP or JPEG usually keeps long pages well under the size cap.
curl --fail-with-body "https://urlbooth.com/v1/screenshots" \-H "Authorization: Bearer $URLBOOTH_API_KEY" \-H "Content-Type: application/json" \-d '{"url":"https://example.com","device":"desktop","format":"webp","fullPage":true}' \-o full-page.webp
The API needs a Pro plan at $20 per month; see pricing. For a first walkthrough, read how to take a website screenshot with an API.
How large can a full-page screenshot be?
- At most 4,096 CSS pixels wide and 10,000 pixels tall.
- The total area is also capped at 24 million pixels, so a page that is within both edges can still be refused.
- The encoded image must be 10 MB or smaller. Over that, the capture fails.
URLBooth measures the page after it loads. If it is over a limit, the request is rejected rather than cropped or scaled down, so you never receive a silently truncated image.
Can I combine fullPage with a device frame?
No. Device frames are always disabled for full-page captures. If you send both fullPage and frame, the frame is dropped and you get the plain full-page image. See device frame screenshots for framed viewport captures.
What does the response look like?
The response body is the image itself in the format you asked for. The X-Screenshot-Id and X-Expires-At headers identify the stored copy, which you can fetch again for two days. Long pages are the main reason to pick webp or jpeg over png: they encode much smaller for typical page content, which keeps you further from the 10 MB cap.
What about lazy-loaded content?
Before capturing, the service waits for the network to go quiet (up to 1.5 seconds) and for the page fonts and every image already in the document to decode (up to 2 seconds). It does not scroll the page. Content that only loads when a visitor scrolls to it, such as infinite feeds or some scroll-triggered images, may be missing or blank. Pages that never stop loading are captured as they are when the wait ends.
When should I use a viewport capture instead?
- You want a sharp, above-the-fold image: viewport captures keep the device pixel ratio, for example 2x on iPhones and MacBooks.
- You want a device frame for a mockup.
- The page is very long or has an endless feed, where a full-page image would hit the limits anyway.
- You are comparing layouts on phone and tablet viewports and only need the first screen.
Limits and caveats
- Plan limits apply to every capture: 10,000 a day (UTC), 60 a minute and 10 at once. Stored images are kept for 2 days. See the API reference.
- Requests time out after about 45 seconds.
- Sites that block automated browsers may return an error or a challenge page. Cleanup is best effort.