How to Take a Mobile Viewport Screenshot in Browshot
Choose a mobile virtual browser instance in Browshot, capture its visible viewport, or use size=page for a full-page image.
To take a mobile viewport screenshot in Browshot, choose a mobile virtual browser instance and request a screenshot of your URL from that instance. Browshot’s default capture shows the visible screen. Add size=page when you need the whole page. The documented screen_width and screen_height parameters are for desktop browsers; they are not the way to set a mobile viewport.
1. Choose a mobile browser instance
Select an available mobile virtual browser instance in your Browshot dashboard or through its API. Browshot’s command-line guide shows a virtual iPhone 4 portrait instance with ID 22 as an example. Treat that as an example only: check your account for the current device inventory and available instance IDs. [Browshot command-line guide]
A mobile instance determines the browser and device context for the capture. Do not substitute desktop dimension parameters for choosing a mobile device. If you need a particular device or screen configuration, check the documented screen option and the mobile instance choices currently available in your account.
2. Request a viewport screenshot
Use your API key and the selected instance to request a screenshot for the target URL. Here is the command-line pattern from Browshot’s guide, using the documented example instance. Replace the placeholder key and URL before running it:
curl -L "https://api.browshot.com/api/v1/screenshot/create?key=YOUR_BROWSHOT_API_KEY&url=https%3A%2F%2Fexample.com&instance_id=22" -o mobile-viewport.pngThe -L option follows redirects. Browshot may return a 302 redirect when the screenshot is ready, so follow redirects when downloading the result. The exact request and response flow can depend on the API endpoint and client you use; see Browshot’s [API documentation] and [command-line guide] for current details.
cURL with the Simple API
If you use Browshot’s Simple API, provide the key and URL, and allow redirects. Check the API reference for the current parameter names and how to select the mobile instance for your account.
curl -L -G "https://api.browshot.com/api/v1/simple" \\
--data-urlencode "key=YOUR_BROWSHOT_API_KEY" \\
--data-urlencode "url=https://example.com" \\
--data-urlencode "instance_id=22" \\
-o mobile-viewport.pngPython
This example follows redirects and saves the returned image bytes. Install the dependency with python -m pip install requests. Confirm the endpoint and instance parameters against Browshot’s current API documentation before using it.
import requests
params = {
"key": "YOUR_BROWSHOT_API_KEY",
"url": "https://example.com",
"instance_id": "22",
}
response = requests.get(
"https://api.browshot.com/api/v1/simple",
params=params,
allow_redirects=True,
timeout=120,
)
response.raise_for_status()
with open("mobile-viewport.png", "wb") as image:
image.write(response.content)Node.js
This example uses the built-in fetch available in current Node.js releases. Fetch follows redirects by default. Verify the endpoint and parameters in Browshot’s API documentation.
const params = new URLSearchParams({
key: 'YOUR_BROWSHOT_API_KEY',
url: 'https://example.com',
instance_id: '22',
});
const response = await fetch(
`https://api.browshot.com/api/v1/simple?${params}`
);
if (!response.ok) {
throw new Error(`Browshot request failed: ${response.status} ${response.statusText}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('mobile-viewport.png', image));3. Choose viewport or full page
The default screenshot is the visible screen, which is the mobile viewport capture. To capture the full document, add size=page to the screenshot request. The option controls image extent; it does not choose the device or set the viewport dimensions. [Browshot API reference]
| Need | What to use | What it changes |
|---|---|---|
| Visible mobile screen | Mobile virtual browser instance; default screen capture | Captures the visible viewport |
| Whole page | Add size=page |
Captures beyond the visible viewport |
| Desktop browser dimensions | screen_width and screen_height |
Sets dimensions for desktop browsers, according to the API reference |
| Mobile device context | Choose an available mobile instance and use the documented screen option where applicable |
Selects the mobile capture setup; confirm supported choices in your account |
4. Configure the capture carefully
- Device: choose a mobile virtual browser instance that matches the device context you need. Instance availability and IDs may change.
- Portrait or landscape: use an instance or documented screen configuration that supports the orientation you need. Do not assume that desktop width and height parameters configure a mobile instance.
- Viewport or page: leave the default for the visible screen; use
size=pagefor the full document. - Output file: save the response as a PNG, as in Browshot’s command-line examples. Ensure your client follows redirects when the response is a redirect to the finished capture.
- Credentials: keep your API key out of source control and public client-side code. Supply it from a protected environment variable in scripts and services.
- Availability and cost: confirm the current instance list, account access, and credit requirements in the Browshot dashboard. Its features page mentions mobile virtual devices and credit-based premium instances; terms can change. [Browshot features]
The API reference lists screen_width from 1 to 5000 and screen_height from 1 to 10000 for desktop browsers. Those ranges are not mobile viewport guidance. [Browshot API reference]
5. Troubleshoot common problems
| Symptom | Likely cause | What to check |
|---|---|---|
| The result is a desktop screenshot | The request used a desktop instance or did not select a mobile instance | Choose a mobile virtual browser instance in the dashboard or API request, then retry. |
| The image shows only the top of the page | The default screen capture is a viewport capture | Add size=page if you need the full document. |
| The capture does not have the dimensions expected | screen_width/screen_height were treated as mobile controls |
Those parameters are documented for desktop browsers. Check mobile instance and screen options instead. |
| The downloaded file contains a redirect response or is not the image | The client did not follow Browshot’s 302 redirect | Use curl -L, enable redirect following in your HTTP library, or follow the redirect URL returned by the API. |
| The API rejects the request | The API key, URL, instance ID, or parameter combination may be invalid or unavailable | Check the key, URL encoding, current account instance list, and endpoint-specific parameters in the API reference. |
| The example instance ID is unavailable | The guide’s instance ID is illustrative; inventory can change | Select an instance currently listed in your account rather than assuming ID 22 is available. |
6. Performance, reliability, and cost
Screenshot completion time can depend on the target site and the selected browser instance. Use a sensible client timeout, handle HTTP errors, and avoid treating an initial redirect as an image. For repeatable captures, keep the URL, instance selection, and requested extent consistent, and record which instance you used alongside the resulting file.
Browshot describes its service as using real desktop and mobile browsers to support web technologies such as HTML5 and CSS3. [Browshot features] That description does not guarantee that every site will render identically across devices or capture attempts; dynamic content, network behavior, and account-specific instance availability can affect the result. Check the current dashboard for credit use and pricing rather than relying on old or example prices.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF, and its parameter names also work with those used by other screenshot APIs. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners are accepted like a visitor would accept them, and 60+ known consent platforms, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, and failed loads are never billed, and the response says what happened. An MCP server lets AI agents use screenshot tools. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up free for 1,000 screenshots a month, with no card.
FAQ
Does Browshot use a physical phone?
The documented approach is to select a mobile virtual browser instance. Browshot’s features page describes real mobile browsers; check its current device and instance details in your account.
Does size=page make the mobile viewport larger?
No. It requests a full-page image rather than only the visible screen; it does not set mobile viewport dimensions.
Can I use the iPhone 4 instance ID from the guide?
Only if it is available to your account. The command-line guide’s instance ID is an example, not a promise of current availability.
Where do I find current device availability and pricing?
Check your Browshot dashboard and its current features and API pages. Instance inventory, account access, and credit terms can change.
