How to Set a Custom Viewport Size in Urlbox Screenshots

Set the width and height render options to choose the browser viewport for a Urlbox screenshot. Both values are in pixels. For example, width: 390 and height: 844 create a mobile-style viewport. Urlbox documents defaults of 1280 × 1024. These dimensions control the browser window; they are separate from output resizing options such as thumb_width and thumb_height.

1. Set the viewport dimensions

Include both dimensions in the render options when you need a predictable viewport. This JSON shape shows the relevant options:

{
  "url": "https://example.com",
  "format": "png",
  "width": 390,
  "height": 844
}

The API accepts option names in camelCase or snake_case. Use the naming convention required by the particular Urlbox endpoint or SDK you are calling. The dimensions are pixel values for the browser viewport, not a guarantee that a particular device’s exact browser behavior is reproduced.

Urlbox documents width as the browser viewport width in pixels, and lists defaults of 1280 for width and 1024 for height. See the Urlbox render options and its quick start for the documented settings and example.

2. Decide whether you need a viewport or a full-page image

A viewport screenshot captures the browser’s visible area at the selected dimensions. full_page is a separate option that asks Urlbox to capture the page’s scrollable content. It does not mean that height becomes only a final-image limit.

Urlbox documents that when height is set with full_page, the height sets the browser viewport and also caps the height of individual screenshot sections. If you need a full-page capture, use the full-page option and check the resulting image dimensions for your page and configuration. See Urlbox screenshots documentation.

3. Keep viewport size separate from output resizing

Use width and height to control how the page is laid out in the browser. Use thumb_width and thumb_height when you want to resize the rendered image afterward. A thumbnail size does not change responsive layout or cause the page to render as though the browser had that viewport.

This distinction matters for responsive breakpoints: if a page should render in its narrow layout, set the browser viewport to the narrow width. Resizing a desktop screenshot to a small output image only scales the desktop layout.

4. Choose dimensions for your capture

Goal	Settings to consider	What to check
Capture a particular browser window	Set both width and height	Confirm the page’s responsive layout at that viewport.
Capture a mobile-style layout	Use a narrow viewport, such as the documented quick-start example of 390 × 844	This is an example size, not a claim that it matches every phone.
Capture the full scrollable page	Enable full_page; set viewport dimensions as needed	With an explicit height, Urlbox also uses it for viewport and screenshot-section behavior.
Make the final image smaller	Use thumbnail resizing options	Resizing affects output dimensions, not the page’s browser layout.

For reproducible captures, record the URL, viewport dimensions, and whether full-page capture or thumbnail resizing is enabled. If you compare screenshots across runs, keep those settings consistent.

5. Troubleshooting

The page still looks like a desktop layout

Check that the request sets the browser’s width, rather than only thumbnail dimensions. Responsive layout is selected during rendering, so output resizing cannot trigger a mobile breakpoint.

The screenshot is taller or segmented differently than expected

Check whether full_page is enabled. With full-page capture, an explicit height also affects the viewport and the height cap for individual screenshot sections. Consult the full-page behavior documentation.

The output dimensions do not match the viewport dimensions

The final image can differ from the viewport when full-page capture or thumbnail resizing is used. Check each option independently: viewport dimensions, full_page, and thumb_width/thumb_height.

The request ignores the dimensions

Verify that width and height are included in the render options object accepted by your integration, that their values are numeric pixel dimensions, and that the option spelling matches the endpoint or SDK usage. Urlbox documents camelCase and snake_case option names in its API reference.

6. Reliability, performance, and cost considerations

Viewport size changes the browser’s layout and the dimensions of a viewport screenshot. Full-page capture can produce a much taller output, while thumbnail resizing changes output size after rendering. Plan storage, transfer, and downstream image processing around the output you actually need. The supplied Urlbox documentation does not establish a universal performance or cost relationship for particular dimensions, so check the applicable Urlbox plan and current API documentation for your own workload.

For repeatable captures, use fixed dimensions, keep viewport and output-resizing settings explicit, and distinguish viewport captures from full-page captures in stored metadata. This makes later comparisons easier to interpret.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a screenshot or PDF; its viewport options include presets and custom viewports. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.

FAQ

Are width and height measured in pixels?

Yes. They specify the browser viewport dimensions in pixels.

What are Urlbox’s documented default dimensions?

The options reference lists a default width of 1280 and height of 1024.

Does a 390 × 844 viewport exactly reproduce a specific phone?

No. It is a mobile-style viewport example in Urlbox’s quick start, not a claim of exact device emulation.

Should I set both dimensions?

Set both when you need a specific viewport shape. This makes the intended browser window explicit and repeatable.