Python Screenshot Requests: Viewport, Full Page, or Element
A rendering service can return a PNG instead of HTML when you add screenshot parameters to a normal GET request.
The three capture modes are independent: a viewport capture uses the browser window size, a full-page capture expands to the document height, and a selector capture crops to one element. This guide maps each mode to its parameter, shows the default viewport dimensions, and explains how to tell a request failure apart from a capture that simply missed the region you wanted.
Three capture modes and the parameters that select them
Every screenshot request starts from the same Python call: create a client with an API key, then call get() on the target URL with a params dictionary. The dictionary decides the output shape.
- Visible viewport. Set
screenshottotrue. The service renders the page at the current window size and returns only what fits on screen. Content below the fold, including footers and later posts, is not included. - Full page. Set
screenshot_full_pagetotrue. The service captures the whole scrollable document, so the resulting image is taller than the viewport. - Single element. Set
screenshot_selectorto a CSS selector string, for examplefooter. The service locates that element and returns an image cropped to it.
These are request parameters, not Python library features. The Python client simply forwards them. The exact request and response-handling code for each mode is provided in the accompanying protected code modules; treat those modules as the authoritative implementation rather than retyping the calls from memory.
Viewport size: defaults and overrides
A plain screenshot request uses the renderer's default window, which is 1920 pixels wide and 1080 pixels high. That default explains why a viewport capture of a long blog page shows the header and hero area but not the article list or footer.
To change the framing, add window_width and window_height to the same params dictionary. Supplying 1280 and 720 produces a 1280x720 PNG. Both values are passed as strings in the request dictionary, matching the form shown in the code modules.
A quick sanity check: open the returned file and confirm its pixel dimensions match the window values you sent. If they do not, the request likely fell back to defaults because a parameter name was misspelled or placed outside the params dictionary.
Choosing a mode: a short decision table
| Goal | Parameter to set | Expected output |
|---|---|---|
| Capture above-the-fold layout at a specific breakpoint | screenshot plus window_width / window_height | PNG matching the requested window size |
| Capture the entire document including footer | screenshot_full_page | Tall PNG covering the full scroll height |
| Capture one component such as a footer or card | screenshot_selector with a CSS selector | PNG cropped to that element |
| Capture a full page at a narrower width | screenshot_full_page plus window_width | Full-height PNG rendered at the narrower width |
If your goal is layout regression testing, viewport captures at fixed widths are usually easier to diff than full-page images, because full-page height changes whenever content length changes.
Failure distinction: request error, blank image, or wrong region
Three different problems can look similar when a screenshot does not match expectations.
- Request error. The response is not OK. The code modules print the response body in this branch. Read that body: it usually names the rejected parameter or the authentication problem. Do not write the response to a PNG file in this branch.
- Successful request, blank or default-sized image. The request returned 200 but the PNG is 1920x1080 when you asked for another size, or the page looks unstyled. This points to parameters that were not applied, for example a key placed at the top level of the call instead of inside
params. - Successful request, wrong region. The image is valid but shows the header when you wanted the footer. With
screenshot_selector, confirm the selector actually matches an element on the rendered page; a selector that matches nothing cannot produce a crop.
Separating these three cases before changing code saves time, because each has a different fix.
Parameter reference map
| Parameter | Type in request | Effect |
|---|---|---|
screenshot | boolean | Captures the visible viewport |
screenshot_full_page | boolean | Captures the full scrollable page |
screenshot_selector | CSS selector string | Captures one matched element |
window_width | string pixel value | Sets viewport width; default 1920 |
window_height | string pixel value | Sets viewport height; default 1080 |
Use one capture mode per request. Combining a full-page flag with a selector flag is not described here, so pick the mode that matches the output you need and verify the result dimensions before relying on it in a pipeline.
Worked example: capturing a blog footer
Suppose you want a PNG of only the footer on a blog home page. The request sets screenshot_selector to footer and leaves the other screenshot flags out. The service renders the page, finds the footer element, and returns a cropped image. The response is written to screenshot.png only when response.ok is true; otherwise the body is printed so you can see the error.
The corresponding code is in the protected module for the selector mode. The same pattern applies to any other element: replace footer with a selector that matches the component you need, such as a product card class or a main content ID.
Frequently asked questions
What is the default screenshot size?
The default viewport is 1920 pixels wide by 1080 pixels high. A plain screenshot request returns an image at that size unless you override window_width and window_height.
How do I capture content below the fold?
Use screenshot_full_page instead of screenshot. The full-page mode expands the capture to the document's scroll height, so footers and later sections appear in the PNG.
Can I screenshot a single element?
Yes. Set screenshot_selector to a CSS selector string that matches the element, for example footer. The returned image is cropped to that element.
Why is my PNG still 1920x1080 after I set window_width and window_height?
The most common cause is that the size keys were not placed inside the params dictionary, so the renderer used defaults. Confirm both keys are in params and that their names match exactly.