Ruby Screenshot API: Capture a Page, Full Page, or Element
A screenshot request can return three different kinds of image from the same target URL.
You choose which one by adding a single parameter to a Ruby HTTP GET request. This guide walks through each mode, shows how the viewport size changes the result, and gives you a checklist for picking the right capture for your task.
What a screenshot request can return
The screenshot API accepts a target URL plus an API key and returns image bytes. The response is written straight to a file in the Ruby examples. Three capture modes are available:
- Viewport capture — set
screenshottotrueorfalse. The image covers only the part of the page that fits inside the browser viewport. - Full-page capture — set
screenshot_full_pagetotrueorfalse. The image extends over the entire page height. - Element capture — set
screenshot_selectorto the CSS selector of the element you want. The image is cropped to that element.
All three are passed as query parameters on the same API endpoint. You do not need a different route for each mode.
Choosing a capture mode
Use this checklist before writing the request:
- Do you need the page as a visitor first sees it? Use
screenshot. This is the right choice for above-the-fold previews, hero sections, and layout checks. - Do you need everything below the fold, including the footer? Use
screenshot_full_page. The result can be very tall, so plan how you will store or display it. - Do you need one component, such as a header, card, or footer? Use
screenshot_selectorwith a CSS selector that matches exactly one element. - Do you need a specific frame size? Add
window_widthandwindow_heightto the request.
A common mistake is to expect screenshot to include content below the fold. It will not, because the viewport is fixed at the default size unless you change it.
Viewport capture with the screenshot parameter
The first example sends a GET request to the API endpoint with api_key, url, and screenshot set to true. The response body is written to screenshot.png.
With the default viewport, the captured image is 1920 by 1080 pixels. That covers only the visible portion of the page. Blog posts and the footer are outside that frame and will not appear in the image.
To change the frame, add window_width and window_height to the query. Setting them to 1280 and 720 produces a 1280 by 720 pixel image. The viewport size is the single factor that determines which parts of the page are visible in a viewport capture.
Full-page capture with the screenshot_full_page parameter
For a capture that includes the entire page, replace screenshot with screenshot_full_page set to true. The request structure stays the same: API key, target URL, and the capture parameter.
The result is a single image covering the whole page. Because the page can be long, the image can be much taller than a viewport capture. Store it as a file and open it in an image viewer rather than assuming it will fit on screen at full size.
Element capture with the screenshot_selector parameter
To capture one HTML element, pass its CSS selector as screenshot_selector. For example, screenshot_selector="footer" returns an image of the footer section only.
The selector must match the element you want. If the selector is too broad, the capture may include more than intended; if it matches nothing, the request cannot produce the element image you asked for. Test the selector in a browser's developer tools before sending the request.
This mode is useful for component-level previews, visual regression checks on a single block, and documentation images that should not include the surrounding page.
Parameter reference
| Parameter | Type | Effect |
|---|---|---|
api_key | string | Authenticates the request |
url | string | Target page to capture |
screenshot | boolean | Captures the visible viewport |
screenshot_full_page | boolean | Captures the entire page |
screenshot_selector | string | Captures the element matching the CSS selector |
window_width | number | Sets the viewport width in pixels |
window_height | number | Sets the viewport height in pixels |
Use one capture parameter per request. The viewport parameters apply to viewport captures and affect how much of the page is visible.
Failure distinction: viewport vs. full page
If a screenshot looks truncated, first check which capture parameter you sent. A screenshot request is not a failure when the footer is missing; it is behaving as designed because the viewport only covers the visible area. A screenshot_full_page request that still looks short may indicate that the page had not finished loading when the capture was taken.
If an element capture returns the wrong region, the selector is the likely cause. Confirm that the selector matches the intended element and that only one element matches it.
| Goal | Parameter | Result |
|---|---|---|
| Above-the-fold preview | screenshot | Viewport-sized image, default 1920x1080 |
| Whole page including footer | screenshot_full_page | Full-height page image |
| Single component | screenshot_selector | Image cropped to the matched element |
| Custom frame size | window_width + window_height | Viewport-sized image at the chosen dimensions |
Dimensions refer to the default viewport and the example values shown in the captured evidence. Actual output size depends on the page and the parameters you send.
Frequently asked questions
What is the default viewport size for a screenshot?
The default viewport is 1920 pixels wide and 1080 pixels high. You can change it with window_width and window_height.
Why is the footer missing from my screenshot?
A screenshot request captures only the visible viewport. To include the footer, use screenshot_full_page instead.
Can I capture a single element instead of the whole page?
Yes. Pass the element's CSS selector as screenshot_selector, for example screenshot_selector="footer".
Do I need a different endpoint for each capture mode?
No. All three modes use the same API endpoint and differ only in the query parameters you send.