How to Set the Viewport Size and Device Scale Factor in Browshot
Set Browshot desktop screenshot dimensions with screen_width and screen_height. Learn what its scale field means, what it does not configure, and how to capture a page another way.
To set the browser-window dimensions for a Browshot desktop screenshot, pass screen_width and screen_height in the screenshot request. The documented ranges are 1–5000 pixels wide and 1–10000 pixels high. Browshot’s reviewed API documentation does not list a request parameter for setting device scale factor. Its scale field is returned screenshot information: it is 1 for desktop browsers, while mobile instances may adjust it to fit the page.
This distinction matters: the documented dimensions are inputs for desktop browser-window size; scale is output metadata, not a documented control for requesting a particular device pixel ratio. See the Browshot API documentation for the endpoint’s current parameter details.
Set desktop screenshot dimensions
A Browshot screenshot-create request requires a target url and an instance_id. For a desktop instance, add screen_width and screen_height to choose the browser-window dimensions. The endpoint and authentication details depend on your Browshot account and API version; use the official API documentation for the exact request format and credentials.
- Choose a desktop instance that supports the capture you need.
- Set
screen_widthto an integer from 1 through 5000 andscreen_heightto an integer from 1 through 10000. - Submit the URL and instance identifier with those dimensions.
- Inspect the resulting screenshot at the intended display size. The documentation excerpt does not establish that output image pixels always equal CSS viewport pixels.
Use the documented parameter names exactly. Do not substitute a generic width, height, or deviceScaleFactor unless the API version you use explicitly documents it.
What the scale field means
Browshot documents scale among returned screenshot details. For desktop browsers it is always 1. For mobile instances, it may change to fit the page on screen. That describes capture output behavior; it does not document a caller-controlled device scale factor.
| Need | Documented approach |
|---|---|
| Choose desktop browser-window dimensions | Send screen_width and screen_height. |
| Set a specific device scale factor | No such request parameter appears in the reviewed parameter list. Do not assume scale sets it. |
| Capture with a mobile instance | Select an appropriate mobile instance; its reported scale may be adjusted to fit the page. |
If you need a specific device pixel ratio, verify whether your particular Browshot instance or API version documents a supported control. The cited documentation does not provide a parameter or workaround for forcing one.
Choosing dimensions for common captures
Pick dimensions based on the layout you want to inspect, while staying within Browshot’s documented ranges. These examples are illustrative choices, not required presets:
- Desktop layout: choose a width that triggers the site’s desktop breakpoints and a height that shows the region you need.
- Tablet-like layout: use a narrower desktop window only if the selected desktop instance supports the requested dimensions; the documentation identifies these inputs as desktop browser parameters.
- Mobile behavior: choose a mobile instance for its device behavior rather than assuming desktop dimensions reproduce mobile emulation.
- Long pages: window height and full-page capture are separate concerns. Check the endpoint documentation for the relevant full-page option; the available research does not establish its parameter name or interaction with dimensions.
Responsive sites can change layout at CSS breakpoints. If a result appears unexpected, capture at widths just above and below the suspected breakpoint. The supplied documentation does not specify CSS viewport semantics, browser emulation fidelity, or a formula converting requested dimensions into output image pixels, so verify the resulting image rather than relying on an undocumented assumption.
Validation and edge cases
- Keep width and height within the documented inclusive limits.
- Send integer pixel values, not unit strings such as
1280px. - Use a desktop instance when relying on
screen_widthandscreen_height; the documentation labels them desktop-browser parameters. - Do not interpret returned
scale: 1as proof that the page used a particular CSS viewport or device pixel ratio. - Mobile scale may be adjusted to fit the page, so do not expect it to remain fixed across mobile captures.
- The supplied documentation does not specify behavior for out-of-range values, fractional dimensions, or unsupported instance combinations. Correct values to the documented ranges and consult the current API response and documentation for instance-specific constraints.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The requested size is rejected | A dimension is outside its documented range, malformed, or unsupported for the chosen instance. | Use integer values within width 1–5000 and height 1–10000, and check that the instance is a desktop browser instance. |
| The page looks like a different responsive layout | The selected width crosses a CSS breakpoint, or the chosen instance has different behavior than expected. | Capture at nearby widths and verify the selected instance. Do not infer device scale factor from layout alone. |
| The output image dimensions differ from the requested dimensions | The available documentation does not promise a one-to-one mapping between browser-window dimensions and image pixels. | Inspect the actual returned image and check the current endpoint documentation for output sizing behavior. |
A scale request parameter has no effect or is rejected |
The reviewed docs describe scale as returned information rather than a request control. |
Remove the assumed control and use the documented desktop dimension parameters. Confirm any additional supported control in the current API docs. |
| A mobile capture has an unexpected scale | Browshot says mobile instances may change scale to fit the page. | Use the mobile instance behavior that matches your goal and treat returned scale as capture metadata, not a fixed input. |
| The response does not contain the expected screenshot | The URL, required instance identifier, credentials, or request syntax may be wrong. | Check the current screenshot-create endpoint requirements and inspect the API response for its specific error details. |
Performance, reliability, and cost considerations
The supplied Browshot material identifies it as a real-time website screenshot service and lists screen resolution among its features, but it provides no suitable benchmark, latency guarantee, reliability figure, or current price details. Avoid estimating capture speed or cost from the dimension parameters alone. Larger screenshots can create larger image files as a general consequence of capturing more pixels, but the reviewed sources do not quantify the effect on Browshot processing time or billing.
For repeatable comparisons, keep the URL, instance type, dimensions, and other request settings consistent. Record the returned screenshot details, including scale, so you can distinguish a changed input from mobile scaling behavior. Check Browshot’s current official pages for service and pricing details before making purchasing decisions: Browshot service and features and pricing.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call endpoint accepts a URL and returns an image or PDF. The API has viewport and device preset options; see the ScreenshotNeo API documentation for the supported parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);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 say 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, and paid plans start at $5 for 3,000 shots. Every feature is on every plan. Learn more at ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.
FAQ
Can I set Browshot’s device scale factor directly?
The reviewed screenshot-create parameter list does not document a device scale factor request parameter.
Is Browshot’s scale field the device scale factor input?
No. The cited docs describe it as returned screenshot information, with desktop value 1 and mobile scaling that may change to fit the page.
What are the valid desktop dimension limits?
The documented range is 1–5000 pixels for screen_width and 1–10000 pixels for screen_height.
Do these settings guarantee a specific output image size?
The supplied documentation does not establish that requested browser-window dimensions equal output image pixel dimensions. Check the returned image and current API documentation.
