How to Fix a Website Screenshot API Timing Out on Large Pages

A screenshot API can time out while opening the page, waiting for content, rendering a full-page image, or returning the response to your application. First identify which stage is failing. Then use the least strict readiness condition that still captures the content you need, reduce the capture area if possible, and adjust the relevant timeout only if the page is making progress.

There is no universal screenshot API timeout setting. For example, Cloudflare documents a maximum of 60,000 ms for its gotoOptions.timeout, while ScreenshotAPI.net documents a 1–30 second whole-render timeout. Those settings cover different things and apply only to those providers. Check your provider’s documentation before changing a limit.

1. Identify which stage is timing out

“Timeout” is not a diagnosis. A request can spend time in several stages, and increasing a navigation timeout will not fix a caller-side HTTP deadline or a page that never satisfies a network-idle condition.

Stage	Typical clue	What to check
Navigation	The target page does not finish opening	Provider error details, target page status, and whether the URL is accessible from the provider’s browser
Readiness wait	Navigation succeeds, but capture waits for network quiet, a selector, or a delay	The configured wait condition and whether the page can satisfy it
Rendering	The page is ready, but a tall or complex screenshot takes too long	Full-page height, capture scope, and render-time diagnostics
Response delivery	The provider may finish, but your application reports a timeout	Your HTTP client deadline, proxy or gateway deadline, and response size handling

Start with the provider’s response body and headers. Some providers expose final page status or render time; for example, ScreenshotAPI.net documents X-Page-Status and X-Render-Time-Ms. Field names and error formats vary. Record the request parameters, HTTP status, provider diagnostics, and your caller’s elapsed time for a failed request.

2. Choose a readiness condition that can finish

Readiness settings describe different conditions. Pick the one tied to the content your image needs; do not assume the strictest wait produces the best screenshot.

Condition	Use it when	Trade-off
Navigation commit or equivalent	You need a very early view and can tolerate content arriving later	May capture an incomplete page
`domcontentloaded`	The document structure is enough to begin capture	Images, fonts, and client-rendered content may still be loading
`load`	You need normal document load completion	Some pages load optional resources slowly
Network idle	The page becomes quiet and you need resources loaded before capture	Analytics, polling, streams, and other background activity can keep it from completing
Wait for a selector	A particular component indicates the content you need is present	Fails if the selector changes, never appears, or is hidden behind a state the page has not reached
Fixed delay	The provider lacks a suitable readiness condition or content appears shortly after navigation	Always spends the configured time, even when the page is ready sooner

Cloudflare’s screenshot example documents networkidle0 with a bounded timeout. If a page keeps background requests open, try a less strict wait such as domcontentloaded or load, if your provider supports it. If a specific element matters, use a selector wait where available. Provider option names and supported conditions differ; consult the linked provider documentation before copying settings.

3. Reduce the amount of page the browser must capture

Large pages can take longer to lay out and rasterize, especially for full-page captures. If the task allows it, capture the viewport or the relevant component instead of the entire document. Cloudflare supports fullPage and selector options. ScreenshotAPI.net documents a 4,320 px full-page height cap; that limit is specific to that service.

Ask whether the use case really needs every section below the fold.
Use a selector capture for a chart, invoice, dashboard panel, or article body when the provider supports it.
Check the provider’s maximum full-page height and any image dimensions or file-size limits.
For a page with lazy-loaded images, confirm whether the provider scrolls to load them during full-page capture. A shorter viewport may omit content that has not loaded.
Test the same URL with the smallest required capture scope, then expand it only if the result needs more content.

4. Tune timeouts as a budget, not a single number

There may be more than one deadline: navigation, readiness, rendering, the provider’s total request, and your own HTTP client or gateway. Your outer deadline must allow time for the provider to finish and return the image. If the caller gives up first, raising a browser navigation timeout alone cannot help.

Find the timeout field and what it governs in your provider’s docs.
Check whether the value is in milliseconds or seconds, and whether the provider imposes a maximum.
Set a bounded wait appropriate to the slow stage you observed.
Make the caller’s deadline longer than the provider’s expected processing window, with room for response delivery.
Avoid stacking a long fixed delay on top of a long navigation wait unless the total request budget allows both.
Change one setting at a time and compare status, render time, and caller elapsed time.

For example, Cloudflare documents gotoOptions.timeout up to 60,000 ms. ScreenshotAPI.net documents a 1–30 second timeout for the whole render. These are not interchangeable recommendations: one is a navigation setting and the other is a provider-specific render limit.

5. Separate slow rendering from access failures

A timeout can be a symptom of a target access problem rather than an unusually slow page. Inspect the final status and timing information before repeatedly extending waits. A page that returns an error, blocks the provider, or is routed differently by region may never produce the expected content.

Check the final page status where the provider exposes it.
Compare provider-reported render time with the caller’s total elapsed time.
Verify that the URL is publicly reachable from the provider’s browser and does not require an unprovided login or network route.
Look for bot checks, CAPTCHA pages, or rate limiting in the resulting image or diagnostics.
ScreenshotOne suggests a proxy retry when symptoms indicate IP throttling or regional routing. This is provider-specific guidance, not a universal remedy.

6. A practical debugging sequence

Reproduce one failing URL. Keep the viewport, capture mode, and wait settings fixed so the result is comparable.
Save diagnostics. Record response status, provider error, page status and render-time headers if available, and your client’s elapsed time.
Try a less strict wait. If network idle is timing out, test a supported load or DOM readiness condition. Verify that the resulting screenshot still contains the required content.
Replace arbitrary delay with a content signal. If a known component is required, use a selector wait when supported. Keep any delay short and bounded.
Narrow the capture. Try viewport or selector capture and check provider height limits.
Adjust the relevant timeout. Raise only the limit for the stage that is demonstrably progressing slowly, within provider and caller limits.
Recheck access and status. If the page status is an error or the page shows a challenge, investigate access rather than adding more wait time.

7. Timeout troubleshooting

Symptom	Likely cause	Fix
Network-idle wait never finishes	Persistent polling, analytics, streaming, or other background requests	Use a less strict supported readiness condition or wait for the specific content selector.
Selector wait expires	Selector is wrong, changed, hidden, or only appears after another action	Inspect the live page markup and state; use a stable selector or an appropriate click/action before waiting if the provider supports it.
Capture succeeds on a short page but fails on full page	Large rendering workload or a full-page height cap	Capture a viewport or element, reduce the required page area, and check the provider’s documented limits.
Provider says success, caller times out	Caller, proxy, or gateway deadline is shorter than processing plus download time	Inspect client and intermediary deadlines; align them with the provider’s processing window and response delivery.
Longer timeout makes no difference	The page is blocked, inaccessible, or waiting on a condition that never occurs	Check final status and screenshot contents; correct access or readiness configuration instead of increasing the limit again.
Page loads, but screenshot misses images	Capture begins before lazy or asynchronous content is ready	Use a supported selector or bounded delay; confirm the provider’s behavior for lazy-loaded images and full-page capture.
Intermittent timeout across regions	Variable target routing, throttling, or regional access	Compare status and timing diagnostics across failures; follow provider-specific guidance for routing or proxy diagnosis.
Timeout value is rejected	Wrong units, unsupported option, or provider maximum exceeded	Check the exact endpoint’s parameter name, units, and documented range.

8. Performance, reliability, and cost

Every extra wait consumes part of the end-to-end request budget. A selector tied to the content you need can avoid waiting for unrelated background activity; a fixed delay is simple but spends its full duration on every request. Full-page capture can also cost more time and memory than a viewport or element capture, and providers may enforce height or render limits.

For reliability, log enough information to distinguish navigation, readiness, render, delivery, and access failures. Retry only when the failure looks transient, and keep retries bounded so a persistently blocked page does not multiply latency and provider usage. Do not treat a retry as a fix for a selector that never appears or a network-idle condition that can never be satisfied.

Provider billing rules differ. Check whether failed renders, retries, cache hits, and timeouts count against your plan before adding automatic retries. ScreenshotNeo states that bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; each response includes X-Page-Verdict and X-Billed headers so you can see the outcome.

9. When comparing providers or configurations

Compare the behavior that affects your failure mode, not just a headline timeout value:

Does the limit govern navigation or the complete render?
Which readiness conditions, selector waits, and delays are supported?
What are the full-page height and capture-scope limits?
Are page status and render-time diagnostics exposed?
How are failed requests, retries, and cache hits billed?

ScreenshotNeo is a website screenshot API and MCP server for developers. It provides clean shots by accepting cookie and consent banners like a visitor, then removing more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Only clean shots are billed, and its response headers identify the page verdict and billing outcome.

Or skip the browser setup

Use one GET request to return a screenshot. The examples below save the response as WebP; see the ScreenshotNeo API documentation for request options and configuration.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots with Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Should I always use network idle for a screenshot?

No. It can wait indefinitely on pages with persistent background requests. Use it only when that condition fits the page and provider; otherwise choose a supported load condition or wait for the content you need.

Will increasing the timeout fix a CAPTCHA?

No. A challenge is an access or bot-check outcome, not ordinary slow rendering. Check the resulting page and provider diagnostics.

Why does a viewport screenshot work when full-page capture fails?

Full-page capture may involve more layout and image rendering, and some providers impose height limits. A viewport avoids that extra capture area.

Can I copy a timeout value from another screenshot API?

Use it only as a clue to investigate. Providers define different timeout scopes, units, supported waits, and maximums.