Skip to content

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.

OUTPUT FORMATSHTMLJSONMarkdown

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 screenshot to true or false. The image covers only the part of the page that fits inside the browser viewport.
  • Full-page capture — set screenshot_full_page to true or false. The image extends over the entire page height.
  • Element capture — set screenshot_selector to 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:

  1. 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.
  2. 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.
  3. Do you need one component, such as a header, card, or footer? Use screenshot_selector with a CSS selector that matches exactly one element.
  4. Do you need a specific frame size? Add window_width and window_height to 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

ParameterTypeEffect
api_keystringAuthenticates the request
urlstringTarget page to capture
screenshotbooleanCaptures the visible viewport
screenshot_full_pagebooleanCaptures the entire page
screenshot_selectorstringCaptures the element matching the CSS selector
window_widthnumberSets the viewport width in pixels
window_heightnumberSets 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.

Capture mode decision table
GoalParameterResult
Above-the-fold previewscreenshotViewport-sized image, default 1920x1080
Whole page including footerscreenshot_full_pageFull-height page image
Single componentscreenshot_selectorImage cropped to the matched element
Custom frame sizewindow_width + window_heightViewport-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.