ScreenshotMachine CLI Times Out on Slow Websites: How to Fix It

If a Screenshot Machine screenshot request times out on a slow website, first identify which part is timing out. Screenshot Machine documents a delay parameter that waits before taking the screenshot; that is different from the deadline your HTTP client gives the API request. Increase delay when the screenshot arrives too early. Adjust the caller’s request timeout only when curl, a script, CI runner, or another wrapper gives up before receiving the response.

The available documentation describes Screenshot Machine as an HTTP GET API called with query parameters, and shows a Bash script using curl. It does not document a standalone ScreenshotMachine CLI timeout flag. If you use a separately installed wrapper called “ScreenshotMachine CLI,” check that wrapper’s own help and documentation for its timeout option. Screenshot Machine API documentation

1. Identify what timed out

Record the exact command and error before changing settings. These symptoms point to different causes:

What you see	Likely issue	What to change
A screenshot is returned, but images or page content are missing	The capture happened before the page finished rendering	Increase Screenshot Machine’s delay and inspect the resulting image
curl or a language client reports a timeout and no image is saved	The caller’s request deadline expired	Adjust the timeout in the client or wrapper that emitted the error
The API returns an error response	The request, account, selector, crop, or service may have a problem	Read X-Screenshotmachine-Response and correct the reported issue
A wrapper prints a timeout message	The wrapper may impose its own deadline	Check that wrapper’s documentation; do not assume a Screenshot Machine API option applies

2. Run a baseline request with curl

Screenshot Machine’s documented interface is an HTTP GET request to https://api.screenshotmachine.com/, with the required customer key and target URL in the query string. This shell example saves the response body so you can check whether you received an image or an error:

curl -sS -D response-headers.txt -G 'https://api.screenshotmachine.com/' \
  --data-urlencode 'key=YOUR_SCREENSHOTMACHINE_KEY' \
  --data-urlencode 'url=https://example.com' \
  -o screenshot.png

cat response-headers.txt

Replace the key and URL with your own values. URL-encode the target URL, especially if it contains reserved characters such as & or ?. The vendor’s documentation includes a Bash/curl example and recommends URL encoding. Request format and shell example

3. Increase capture delay when content is missing

The API’s delay parameter controls how long the capture engine waits before creating the screenshot. The documented default is 200 milliseconds. Documented values are 0, 200, 400, 600, 800, 1000, and each whole second from 2 through 10 seconds. The documentation recommends a longer delay for long pages with many images or animations. This wait does not guarantee that every asynchronous page task will finish.

Try a small increase first, then inspect the output. Increase again only if the content you need is still missing. For example, request a 2-second capture delay:

curl -sS -D response-headers.txt -G 'https://api.screenshotmachine.com/' \
  --data-urlencode 'key=YOUR_SCREENSHOTMACHINE_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'delay=2000' \
  -o screenshot.png

The request parameter controls capture timing; it is not documented as a timeout setting for curl or for the client waiting on the API response. Screenshot Machine parameter reference

4. Adjust the caller’s request timeout only when it aborts

If curl, a language HTTP library, a CI runner, or a wrapper reports that its request deadline expired, identify that client’s timeout setting. The Screenshot Machine API page demonstrates curl but does not specify a universal client timeout flag, a vendor-side maximum processing time, or a guarantee that waiting longer will make a failed capture succeed. Use the documentation or help output for the exact client that emitted the error.

For curl, inspect the installed version’s help or manual for its connection and overall transfer timeout options. Set a deadline that fits your job and retry policy. Avoid copying a timeout value from another tool: wrappers and HTTP libraries can name and interpret their timeout options differently.

5. Check the API response and request values

Screenshot Machine documents the X-Screenshotmachine-Response header for API errors. Check it before concluding that a slow target site caused the failure. Documented error codes include:

Response code	What to check
missing_key	Include the required customer key parameter.
missing_url	Include the target URL parameter.
invalid_key, invalid_hash	Verify the credentials and any request signature or hash your integration uses.
invalid_url	Check that the target URL is valid and correctly encoded.
no_credits	Check the account’s available credits.
invalid_selector	Correct the selector if the request asks to capture a selected element.
invalid_crop	Correct the crop values if the request specifies a crop.
system_error	Treat it as a service-side error; preserve the response details when investigating or retrying.

The API reference documents required values, response errors, and URL encoding guidance. Screenshot Machine API error reference

6. Keep capture dimensions within the documented limits

Dimensions affect the requested capture, but they are not timeout controls. The documented width range is 100–1920 pixels. Height can be 100–9999 pixels, or full for full-page height. For a full-page capture, the documentation suggests allowing more delay because a long page may contain more images or animations. Screenshot Machine capture options

Common problems and fixes

Problem	Cause to investigate	Fix
Screenshot is incomplete, but the request succeeds	The capture delay is too short for the content you need	Increase delay within the documented range, one step at a time, and inspect the image.
curl exits with a timeout	The curl request deadline is shorter than the time needed for the response	Inspect curl’s own timeout configuration and adjust the caller’s deadline for the job.
A scheduled job fails while the same request works manually	The scheduled environment may run a wrapper, CI limit, or different client configuration	Capture the full command and error in that environment, then inspect the timeout setting of the process that aborts.
The response is an API error rather than an image	Missing or invalid request parameters, exhausted credits, selector/crop issue, or service error	Inspect X-Screenshotmachine-Response and fix the corresponding request or account issue.
The URL works in a browser but the API reports it as invalid	The request URL may not be encoded correctly	Pass it as a URL-encoded query parameter; curl’s --data-urlencode handles query encoding.
Increasing delay does not stop a client timeout	Capture delay and caller request timeout are separate controls	Configure the HTTP client’s deadline independently; a longer capture delay can make the request take longer.

Performance, reliability, and cost considerations

• Use the smallest delay that captures the required content. A larger delay makes each capture wait longer and does not ensure all asynchronous content has loaded.
• Keep the caller deadline above the expected request duration. If the client deadline is shorter than the configured capture wait plus request processing, the caller may abort before receiving a response. The available documentation does not specify a universal processing-time estimate or maximum.
• Retry selectively. A timeout can leave the result unknown to the caller. Before retrying in bulk, check whether the first request produced a response or saved a file, and avoid unbounded retry loops.
• Separate service errors from target-page slowness. Read the response header and validate the key, URL, credits, selector, and crop before adding delay.
• No timeout benchmark is available in the reviewed documentation. Do not assume a particular success rate or typical completion time.

Or skip the browser setup

If you want a single API call for screenshots, ScreenshotNeo is a website screenshot API and MCP server for developers. Send a GET request with a URL to receive a PNG, JPEG, WebP, or PDF. The API supports options including full-page captures with lazy images loaded, element capture, wait conditions, custom headers and cookies, and async jobs. 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.webp

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses identify page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, with no card required.

FAQ

Does Screenshot Machine have a documented CLI timeout flag?

The reviewed vendor documentation describes an HTTP GET API and provides a curl shell example. It documents a capture delay, but no vendor CLI timeout flag. Check the documentation for any separate wrapper you installed.

Will setting delay=10000 prevent a request timeout?

No. It requests a longer wait before the capture and may make the response take longer. It does not change the timeout configured in the caller.

What should I share when investigating a failure?

Keep the exact command, the client’s error, the response headers, and the API response code. Remove or redact your API key before sharing logs.

Can I use a longer delay for every page?

You can choose a documented delay value per request, but using a longer wait for every capture adds waiting time even when pages render quickly. Tune it against the content your capture needs.