Urlbox screenshot API timeout: how to diagnose slow pages

Direct answer: A Urlbox screenshot timeout can come from the target page, the readiness condition, extra work from a full-page capture, or the connection between your application and Urlbox. First inspect the complete error and request options. Then align the readiness wait with the content you need, simplify full-page capture if it is the bottleneck, and use asynchronous rendering for jobs that are routinely long. Raising timeout helps only when the render needs more time and remains within Urlbox’s documented limit; it does not make a consistently expensive render faster.

Urlbox documents timeout as 5,000–100,000 milliseconds, with a 30,000 ms default. Its readiness controls include wait_until, wait_for, wait_to_leave, and wait_timeout. Full-page stitching and asynchronous rendering can change how a slow job behaves. See the Urlbox render options, screenshots guide, and async guide for current details.

1. Identify which timeout happened

Do not treat every failed screenshot request as a slow target page. Preserve the full response or CLI error, the exact request options, and any request ID. Urlbox distinguishes timeout errors from network or DNS failures, rate limits, authentication errors, forbidden responses, and server errors. An API error can include a message, error code, and requestId; retain these details if you need support to investigate. See the API reference and CLI troubleshooting.

If the response includes queueTime and renderTime, compare them. High render time points toward page loading or capture work; queue time indicates time spent waiting before rendering. Those fields help localize a delay when present, but an example response is not a performance guarantee. See the quickstart.

What you observe	Likely area to inspect	Next step
`timeout` after a long render	Target load, readiness wait, or capture workload	Review `timeout`, readiness options, and full-page mode.
`network` or DNS error	Connection or name resolution	Check the target hostname and whether the caller can reach Urlbox.
`rate_limit`	Request volume or plan limits	Reduce request pressure and inspect the applicable account limits.
`auth` or `forbidden`	Credentials or access policy	Check the request signature, credentials, and target access requirements.
A returned screenshot shows an error page	The page response may have rendered successfully	Configure HTTP failure handling if 4xx or 5xx pages should count as failures.

2. Check timeout and page readiness settings

The timeout option controls how long Urlbox waits for the requested URL to load. Its documented range is 5,000–100,000 ms, and the default is 30,000 ms. Set it deliberately after determining that the page needs more navigation time; do not automatically set the maximum for every request.

wait_until determines the readiness event. The default is loaded; alternatives include domloaded, mostrequestsfinished, and requestsfinished. The latter waits until there are no network connections for at least 500 ms. mostrequestsfinished allows up to two connections during that period. Analytics, streaming, or long-polling requests can keep a strict network-idle condition from being reached promptly.

When the screenshot depends on a specific element, prefer a targeted wait_for selector over an unnecessarily long generic wait. A bounded delay can help with content that appears shortly after the ordinary load event. Check wait_timeout as well; its documented default is 30,000 ms. By default, a missing wait_for selector or a wait_to_leave element that remains present until timeout does not necessarily fail the render. Urlbox has options to make these conditions fail explicitly. Avoid stacking long waits without a reason: wait for the signal that means the content you need is ready.

3. Determine whether full-page capture is the expensive work

Full-page capture can do substantially more than capture the current viewport. Urlbox’s default stitch mode scrolls through the page, captures sections, and stitches them together. This supports lazy-loaded content and varied page structure, but adds work. The native mode uses browser-native full-page capture and is faster, though it may be less reliable on some sites.

skip_scroll: true can avoid the initial scroll and may save time depending on page height. It can also leave lazy-loaded content unloaded. Compare the output against the completeness you require: a quicker image that omits below-the-fold images may be wrong for your use case. See the Urlbox screenshots guide for full-page mode details.

4. Choose synchronous, asynchronous, or retry behavior

A synchronous request is appropriate when the render reliably finishes within the time your caller can keep a connection open. For routinely long renders—especially large full-page captures, video, or slow sites—Urlbox recommends asynchronous rendering. The async endpoint returns a renderId and statusUrl; follow completion by polling the status or receiving a webhook. This lets the caller return promptly instead of holding one HTTP connection open for the whole render. See the async guide and API reference.

Retries are useful when failures are plausibly transient. Urlbox supports configured retry conditions including timeouts and selected HTTP statuses, subject to plan availability. A consistently heavy render will still be heavy on each attempt; the CLI guidance warns that retrying may not help. For repeatable long jobs, reduce capture work or queue them asynchronously instead.

A render may also successfully capture a page that returned an HTTP error. If a 4xx or 5xx response should be treated as a failed job, configure fail_on_4xx, fail_on_5xx, or selected statuses through fail_on. Retry rules can target selected statuses too. See the render options and common problems documentation.

5. Make a minimal reproducible request

Start with the same target and only the options needed to reproduce the issue. Add the wait condition, full-page option, headers, or other configuration back one at a time. That isolates whether the delay follows the page itself or a particular rendering choice. Use the exact parameter names from the live options reference; the example below illustrates the structure, and credentials/signing should follow Urlbox’s current authentication documentation.

curl -G 'https://api.urlbox.io/v1/render' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'timeout=60000' \
  --data-urlencode 'wait_until=loaded' \
  -o screenshot.png

This example is not a substitute for the account-specific request signature or authentication parameters required by Urlbox. Add those as documented for your account. Use a real target that reproduces the delay, and retain the response headers and body when the request fails.

6. Troubleshooting common symptoms

Symptom	Cause to check	Fix
The request always expires near the same duration	The configured timeout or caller/proxy connection deadline	Compare Urlbox’s `timeout` with your HTTP client, reverse proxy, and job runner deadlines. Align them so the caller does not disconnect first.
Render times out only with `requestsfinished`	Persistent background network requests	Use a less strict readiness condition such as `loaded` or `mostrequestsfinished` when it still captures the required content.
Images are missing in a full-page screenshot	Lazy content was not triggered, possibly because scrolling was skipped	Use the stitch mode and avoid `skip_scroll` when below-the-fold content must load; add a targeted wait if needed.
Full-page capture is much slower than viewport capture	Scrolling, multiple section captures, and stitching	Test native mode if its reliability is adequate, or capture only the needed element/viewport if that meets the requirement.
Screenshot returned, but it contains a 403/500 page	HTTP error pages may be returned as rendered output	Enable the appropriate `fail_on` behavior so your workflow recognizes the response as an error.
Retry attempts all time out	The workload is predictably longer than the allowed window	Reduce capture work or switch to async rendering; reserve retries for intermittent failures.
Client reports timeout but no Urlbox render error is available	The caller, proxy, or network may have ended the connection	Inspect client-side timeout settings and logs, and use async rendering when the request cannot stay open long enough.
Failure is actually auth, forbidden, rate limit, or network	Misclassified error	Follow the specific error category, preserve its code and request ID, and avoid changing render timeout without evidence.

7. Performance, reliability, and cost considerations

Measure before increasing waits. Record the URL, options, response/error, and available queue/render timing fields. This makes changes attributable and prevents indefinite waiting.
Use the narrowest readiness signal that works. Waiting for all network activity can be counterproductive on pages with persistent requests. A target element is often a clearer readiness condition.
Choose capture fidelity intentionally. Stitching supports lazy-loaded content; native capture can be faster but may be less reliable. Skipping scroll can reduce work while omitting unloaded content.
Bound caller resources. A long synchronous request occupies a connection and can exceed a client or proxy deadline. Async jobs avoid holding that connection open while rendering completes.
Keep retries limited to transients. Retrying a deterministic slow page repeats the same expensive work and delays the final result. Check whether retry settings are available on your plan.
Confirm current plan and option limits. Urlbox settings and eligibility can change; consult the live documentation and account plan before relying on a limit.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF; the API also supports waits, full-page capture, element capture, custom headers, cookies, and async jobs. See the ScreenshotNeo API docs for the complete options and request behavior.

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

import 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}`);

Cookie banners and consent notices, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify page verdict and billing status in headers.
An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

How do I increase the Urlbox timeout?

Set the timeout render option in milliseconds, within the documented 5,000–100,000 ms range. Also make sure your client and any proxy allow the request to remain open for at least as long.

Which `wait_until` value should I use?

Use the least strict condition that captures the content you need. Start with the default loaded; use a network-idle option only when network completion is a meaningful readiness signal for that page.

Should I retry a timed-out screenshot?

Retry when the failure may be temporary. If the same heavy page regularly exceeds the time limit, change the capture workload or use async rendering.

Does a timeout mean Urlbox could not reach the website?

No. A timeout is distinct from the documented network/DNS error category. Read the full error and request ID before deciding whether the target or connection caused the failure.