Browser Behavior

What Fetch does in the browser

Fetch is not just downloading HTML. It opens the page in a browser, lets client-side JavaScript run, observes the rendered page, and then extracts the content and state that matter for agents.

That difference matters on pages where raw HTML misses the useful content:

• JavaScript-rendered docs that hydrate after load;
• dashboards and app shells backed by JSON state;
• pricing pages, tables, and grids where layout carries meaning;
• icon-heavy pages where the icons are the signal.

Fetch reads and preserves page context. It is not a public browser-automation engine: this page does not promise that Fetch can fill forms, click through multi-step flows, or drive arbitrary page interactions.

Readiness and timing

Fetch decides when the page is ready internally. Public Fetch does not currently expose timeout, wait selector, network-idle, or custom readiness controls.

What that means in practice:

• pages are rendered before extraction, not captured as raw source;
• a page that never settles may be captured partially;
• captures that fail or are refused surface as errors or blocked outcomes;
• when output looks off, replay shows what Fetch actually saw.

The capture ceiling

Synchronous Fetch has one 150-second capture-work budget. The API creates its absolute epoch before URL preparation and Hatchet dispatch, so dispatch and browser queueing, worker replacements, lease waiting, local retries, navigation, rendering, settling, optional scroll, snapshot production, and result publication all consume the same budget. Every worker invocation reads the epoch from the immutable workflow payload; retries and reassignments never receive a fresh window.

• If timeout classification wins and Expand cannot prove the run stayed queue-only, the API returns 504 FetchCaptureTimeout. This includes known-started captures and the conservative fallback when classification is missing, fails, or takes longer than five seconds. It does not prove the target page caused the timeout. timeoutMs reports the configured request ceiling (150000 by default), and the SDKs do not retry this tag automatically to avoid amplifying control-plane incidents. A deliberate manual retry may still be appropriate.
• If timeout classification wins and Expand proves the deadline elapsed while the run remained queue-only, the API returns 529 FetchCapacityTimeout with Retry-After: 5. This is a retryable Expand capacity condition, not a page verdict; both SDKs retry it.
• A run that started before its worker disappeared remains a 504 even if a replacement waits in the queue, because the capture was attempted.
• Use a 180-second synchronous client timeout: after the 150-second capture epoch, timeout classification has a single disconnected five-second budget. If classification wins, the server produces a typed 504/529 by 155 seconds even if the control plane hangs. That leaves 25 seconds for response serialization and network transit. The TypeScript SDK's timeoutMs defaults to 60 seconds and therefore aborts long captures client-side; see TypeScript SDK.
• Batched Fetch starts the same 150-second epoch before each durable item supervisor is dispatched. The supervisor and every browser-child retry or reassignment inherit that immutable epoch. A child first started after expiry stores the retryable 529; a child that previously started stores 504. Time spent in batched submission and initialization before item dispatch is outside the per-item deadline because batched results are polled rather than held on one synchronous request.

150 seconds bounds the capture-work budget, but it is not a strict success cutoff or a target: most captures finish in a few seconds. Reaching the epoch starts timeout classification; a result that arrives during that window can still win and be returned successfully. Otherwise, bounded classification produces a typed 504/529 by 155 seconds at the latest. Every capture timing constant beneath the 150-second budget — readiness waits, settle budgets, and per-phase deadlines — is internal, is not a stable public contract, and can change.

Scrolling

scrollFullPage is the one public browser behavior control. It defaults to false. When true, Fetch attempts to scroll the page before capture to trigger lazy-loaded content, then returns to the top before capturing.

The scroll pass is best-effort. It does not guarantee that every infinite-scroll page is fully exhausted, and a scroll that fails is logged and does not fail the request.

Use scrollFullPage when important content appears only after scrolling. Do not use it as a promise that every infinite-scroll page will be fully exhausted.

Screenshots

Screenshots are requested through include.screenshot, not browserConfig.

Screenshots are opt-in. A requested screenshot defaults to full-page. Set include.screenshot.fullPage: false for a viewport screenshot instead. Fetch returns one screenshot per request, not both a full-page and a viewport image.

The response carries a screenshot URL and a fullPage boolean. The exact schema belongs to Output Model and the API Reference; see Include Options for the full request surface.

Redirects and response metadata

If your application needs to know what happened at the HTTP layer, request response metadata.

Response metadata can report:

• the final URL Fetch landed on;
• the originally requested URL when it differs;
• origin status;
• redirect status;
• headers, only when include.response.includeHeaders is true.

The full response schema lives in Output Model and the API Reference.

Blocked pages

Fetch can handle many pages that raw HTTP cannot, but it does not promise to bypass every block, CAPTCHA, auth wall, or bot-protection system.

Fetch renders through a real browser and can handle many sites where raw HTTP fails. Some sites still block automated access; those may return FetchBlocked.

• A blocked page may return FetchBlocked.
• Synchronous POST /v1/fetch can surface this as HTTP 403.
• Some retry behavior is internal; Fetch may retry retryable block classes on its own.
• Proxy behavior is internal and is not a public request option.
• When a capture result is surprising, inspect replay or the error details before assuming the page is unreachable.

Browser controls that are not public

This is the full set of public browser behavior today. The rest of the table exists so you do not hunt for options that Fetch does not expose.

If any of these become public, this page and the API Reference change together.

Debug with replay

When output looks incomplete or surprising, replay shows what Fetch saw at capture time.

• Replay helps debug missing or lazy-loaded content.
• Replay lets you inspect citations and evidence.
• Replay separates page behavior (what the site rendered) from extraction behavior (what Fetch kept).

The common failure modes to look for: timeout, blocked, auth wall, CAPTCHA, missing lazy content, and unexpected redirects. Playground & Replay covers the inspection workflow in full.

Next steps

• Include Options: control which artifacts Fetch returns.
• Output Model: see the response fields and schemas.
• Playground & Replay: inspect evidence visually.
• How Fetch Works: the capture mental model.