Skip to content

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.

OUTPUT FORMATSHTMLJSONMarkdown

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 screenshot to true. 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_page to true. The service captures the whole scrollable document, so the resulting image is taller than the viewport.
  • Single element. Set screenshot_selector to a CSS selector string, for example footer. 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

GoalParameter to setExpected output
Capture above-the-fold layout at a specific breakpointscreenshot plus window_width / window_heightPNG matching the requested window size
Capture the entire document including footerscreenshot_full_pageTall PNG covering the full scroll height
Capture one component such as a footer or cardscreenshot_selector with a CSS selectorPNG cropped to that element
Capture a full page at a narrower widthscreenshot_full_page plus window_widthFull-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.

  1. 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.
  2. 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.
  3. 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

ParameterType in requestEffect
screenshotbooleanCaptures the visible viewport
screenshot_full_pagebooleanCaptures the full scrollable page
screenshot_selectorCSS selector stringCaptures one matched element
window_widthstring pixel valueSets viewport width; default 1920
window_heightstring pixel valueSets 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.