timeoutOpts on an endpoint that supports request deadlines. milliseconds sets the budget and behavior controls what happens when work is unfinished:
Request a partial page
This Markdown request allows 30 seconds and accepts the page content available at the deadline. Usefail when your workflow needs a completed capture.
These examples use the SDKs’ low-level request methods to send the current API contract, including fields not yet exposed by the 2.14.0 typed helpers. Authentication, retries, and error handling still come from the SDK. See SDK compatibility.
timeoutOpts query value. The API deadline is separate from your HTTP client’s transport timeout. Allow time for the server to return its result, and account for SDK retries when setting your application’s total latency budget.
Choose a valid budget
The maximum is 300,000 milliseconds. Endpoint-specific limits still apply: for example, Answers has a 30-second Fast or 50-second Ultra research budget that a caller timeout can shorten but cannot extend. Parse does not accept
timeoutOpts.
If you supply waitForMs, the deadline must allow the wait plus 10,000 milliseconds for page loading and capture. A zero wait is normalized to 500 milliseconds. An incompatible pair returns 400 TIMEOUT_TOO_SHORT_FOR_WAIT; increase the budget or lower the wait. Brand retrieval can also reject a budget below 10 seconds for an uncached domain with 422 COLD_DOMAIN_TIMEOUT_TOO_LOW.
Preserve completion markers
Browser captures returnfinalDOMState:
loaded: the page completed the waits requested by the call.still-loading: partial mode captured the DOM when the deadline arrived; content that renders later may be missing.
partial: true. Keep that marker with stored data and surface it when completeness matters. A response can be valid JSON and still contain only part of the requested dataset. Search can also expose finalDOMState on a result’s captured Markdown.
Partial extraction must satisfy the caller’s schema. Partial Brand profiles omit unknown fields, and partial product results can omit unfinished image processing. Partial Answers require usable evidence and a valid response shape. A successful HTTP status does not imply complete research or a complete catalog.
Billing and caching
Usable partial results are successful, billable responses under the operation’s pricing. Partial HTML, Markdown, and Images use the base request price without unfinished browser-action, OCR, or enrichment charges. Answers charges the selected mode’s price for a valid partial answer. A deadline failure without usable results is not billed. Incomplete results are not cached as complete results. Use cache freshness controls separately when deciding whether an existing complete result is recent enough.Migrate existing requests
The legacytimeoutMS parameter remains accepted and behaves like timeoutOpts: { milliseconds: timeoutMS, behavior: "fail" }. An explicit timeoutOpts takes precedence. New request schemas expose timeoutOpts; SDK 2.14.0 typed helpers can still expose the legacy field, so use the supported low-level methods above when sending the new object.
Product catalog deadlines
Product catalog extraction previously returned partial success when an explicittimeoutMS interrupted collection. An explicit deadline now returns an unbilled 408 with legacy syntax, omitted behavior, or behavior: "fail".
To accept an incomplete catalog, send:
partial: true and request more time when you need a fuller catalog. Requests without an explicit timeout keep their existing best-effort behavior.
See Troubleshooting for failure recovery and API stability for compatibility guidance.