How to Use ScreenshotMachine CLI to Capture a Responsive Webpage at Mobile Width
Capture a responsive webpage at mobile width with ScreenshotMachine’s curl-based CLI workflow. Learn how to choose dimensions, configure the request, and troubleshoot common issues.
Use curl to call ScreenshotMachine’s HTTP API and save its image response. For the documented phone example, set dimension=480x800 and device=phone. Choose a width that exercises the responsive layout you want to inspect; 480 pixels is an example, not a universal mobile breakpoint.
The command below follows ScreenshotMachine’s documented Bash workflow and has not been run or independently tested here. You need a ScreenshotMachine customer key from its signup process. The API documentation lists width limits of 100–1920 pixels and height limits of 100–9999 pixels. ScreenshotMachine API documentation
1. Capture a mobile-width page from the command line
Save this as a Bash script or paste it into a Bash-compatible shell. Replace the key and target URL. It writes the returned image to mobile.png.
#!/usr/bin/env bash
set -euo pipefail
CUSTOMER_KEY="YOUR_CUSTOMER_KEY"
URL="https://example.com"
DIMENSION="480x800"
DEVICE="phone"
FORMAT="png"
DELAY="2000"
ARGS=(
--data-urlencode "key=$CUSTOMER_KEY"
--data-urlencode "dimension=$DIMENSION"
--data-urlencode "device=$DEVICE"
--data-urlencode "format=$FORMAT"
--data-urlencode "delay=$DELAY"
--data-urlencode "url=$URL"
)
curl -fGs "https://api.screenshotmachine.com" "${ARGS[@]}" -o mobile.pngcurl -G sends the options as query parameters. --data-urlencode encodes values such as URLs that contain query strings or special characters. -o saves the response body to a file. The -f option makes curl return an error for HTTP error responses instead of quietly treating an error page as an image.
Quick one-line form
curl -fG "https://api.screenshotmachine.com" \
--data-urlencode "key=YOUR_CUSTOMER_KEY" \
--data-urlencode "dimension=480x800" \
--data-urlencode "device=phone" \
--data-urlencode "format=png" \
--data-urlencode "delay=2000" \
--data-urlencode "url=https://example.com" \
-o mobile.pngKeep the key out of source control and shared shell history. For repeated use, read it from a secret manager or a protected environment variable rather than committing it in a script.
2. Choose the width and height for the responsive state
A responsive screenshot is determined by the viewport width used for rendering. Start with the breakpoint or layout state you need to test: for example, a width just below a breakpoint can reveal the mobile layout, while a width just above it can reveal the next layout. ScreenshotMachine’s API documentation does not specify a single correct mobile width for every site.
| Setting | What it controls | How to choose it |
|---|---|---|
dimension |
Requested width and height, formatted as widthxheight |
Use a width that corresponds to the responsive state under inspection. The documented phone example is 480x800. Widths are documented from 100 to 1920 px; heights from 100 to 9999 px. Use full as the height for a full-length page. |
device |
Rendering category: desktop, phone, or tablet |
Use phone for the documented phone mode. This setting does not establish that the result exactly matches a particular handset and browser. |
user-agent |
User-agent value sent for the page request | Set it only when the target behavior depends on a chosen user-agent. A user-agent string alone does not reproduce all device behavior. |
For a full-page capture, change the height to full, for example dimension=480xfull. ScreenshotMachine advises considering a delay of 2000 ms or more for long full-page captures with images or animations. A delay is only a wait before capture; it is not a guarantee that every script, image, or animation has finished.
3. Tune the capture options
Keep the request small while you determine the right responsive width. Add options only when they address a specific rendering need.
format: Select the returned image format. The example uses PNG. Ensure the filename extension matches the requested format.delay: Wait before capture. Increase it when the page needs extra rendering time; ScreenshotMachine suggests 2000 ms or more for long full-page pages with images or animations.cacheLimit: The official example includes this configurable field. Set it according to whether a cached result is acceptable for your task; consult the current API documentation for its accepted values and behavior.zoom: The documentation describes zoom as a percentage. Its optimization may ignore zoom for screenshots smaller than the typical device dimension associated with the selected device mode.accept-language: Select a language when the page varies by request language.user-agent: Supply a user-agent when you need to test a particular server-side or client-side response. It does not, by itself, emulate a complete physical device.
Parameter names and accepted values can change. Check the official API parameter reference before relying on an option not shown in the basic command.
4. Check the saved result
- Confirm curl completed successfully and the output file is non-empty.
- Open the image and check that its width matches the requested viewport and that the intended mobile layout is visible.
- If the page is taller than the viewport and you need all of it, request a full height and allow more time for lazy-loaded images or animation.
- Repeat at widths around the site’s relevant breakpoints when you need to compare layout transitions.
Do not infer exact physical-phone rendering from device=phone or a custom user-agent alone. The documented options establish a requested size, a device category, and optional request settings; they do not promise a named hardware and browser combination.
5. Troubleshoot common problems
| Symptom | Likely cause | What to try |
|---|---|---|
| curl reports an HTTP error | The key, URL, parameter, or API request may be invalid, or the service returned an error. | Check the key and URL, then inspect the HTTP response without -f in a secure terminal to see the error body. Avoid publishing output that may contain credentials. |
| The output file is not a viewable image | An error response may have been saved with an image extension, or the requested format and extension do not match. | Use -f, inspect the response status and content type, and align format with the file extension. |
| The page shows its desktop layout | The requested width may not cross the site’s responsive breakpoint, or the site may respond differently to the selected device category. | Try a narrower explicit dimension and compare around the breakpoint. Use device=phone for phone mode. A user-agent override is not a complete device emulator. |
| Images or animated content are missing | Content may load after the capture, or lazy loading may require additional time or scrolling. | Increase delay; for long full-page pages with images or animations, the provider suggests trying 2000 ms or more. Recheck whether the target page requires interaction. |
| The page is cropped | The requested height captures only the viewport. | Use a larger numeric height within the documented limit, or request full height. |
| The result does not match a particular phone | Viewport dimensions and a phone category do not establish an exact device and browser match. | Use the required viewport width and, if needed, a user-agent setting; treat the result as a responsive viewport capture, not proof of pixel-identical hardware rendering. |
6. Performance, reliability, and cost considerations
Use the shortest delay that gives the page enough time to render, then increase it for pages with late-loading content. Full-page captures can take longer because the page is taller and may include images or animations. A longer delay can help with rendering but does not guarantee completion of network activity or page scripts.
For a reliable command-line workflow, use a fixed width and height, encode query values with curl, fail on HTTP errors, and verify the output file before consuming it downstream. Retry only errors that appear transient, and avoid rapid repeated requests with the same parameters until you understand the service’s current limits. The dossier does not establish ScreenshotMachine’s current quotas, prices, or availability guarantees; check its current account and API pages for those details.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. Its API can return an image or PDF with one GET request; for a mobile-width capture, use the viewport parameters in the ScreenshotNeo API documentation. Example request:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com \
-d width=480 \
-d height=800 \
-o shot.webpScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Every feature is available on every plan. Sign up for 1,000 free screenshots a month, with no card.
FAQ
Is 480 pixels the standard mobile width?
No. It is ScreenshotMachine’s documented phone example. Choose a width that tests the responsive layout or breakpoint relevant to your page.
Does device=phone emulate a specific phone?
The documentation lists a phone rendering category, but does not identify it as an exact handset and browser configuration.
Can I capture the entire page?
Yes. The documented dimension syntax accepts full as the height. For long pages with images or animations, consider the provider’s suggested delay of 2000 ms or more.
