Fetch

Functions for interacting with the fetch API resource. Each operation ships in four forms — sync / sync_detailed and their async counterparts.

Get Fetch

Fetch a URL (GET)

Direct HTTP fetch. Metadata is returned in X-Fetch-* headers. What the body holds depends on X-Fetch-Fast-Path. When it is true, a successful response returns the upstream response bytes verbatim. When it is false the request fell back to a browser render, and the body is the rendered page rather than the bytes the target sent; X-Fetch-Content-Length is then the compressed size of that page. Non-2xx upstream responses use the upstream_error JSON envelope with the upstream HTTP status.

Parameters

• url_query (str)
• country (str | Unset)
• timeout_ms (int | Unset)
• cache_ttl (GetFetchCacheTtlType1 | str | Unset)
• custom (str | Unset)

Call styles

sync_detailed(client=client, url_query=url_query, country=country, timeout_ms=timeout_ms, cache_ttl=cache_ttl, custom=custom) -> Response[Error | str]
sync(client=client, url_query=url_query, country=country, timeout_ms=timeout_ms, cache_ttl=cache_ttl, custom=custom) -> Error | str | None
await asyncio_detailed(client=client, url_query=url_query, country=country, timeout_ms=timeout_ms, cache_ttl=cache_ttl, custom=custom) -> Response[Error | str]
await asyncio(client=client, url_query=url_query, country=country, timeout_ms=timeout_ms, cache_ttl=cache_ttl, custom=custom) -> Error | str | None

Post Fetch

Fetch a URL (POST)

Same as GET /v1/fetch but with a JSON request body. The response is the same, including the X-Fetch-Fast-Path rule for what the body holds: the upstream bytes verbatim when it is true, the rendered page when it is false.

Limits: request bodies are capped at 512 KB. An oversized body returns a 400 with error code request_too_large.

Parameters

• body (FetchRequest)
• url — str
• country — str | Unset — Two-letter country code. Either case is accepted; the value is upper-cased.
• timeout_ms — int | Unset
• cache_ttl — FetchRequestCacheTtlType1 | str | Unset — How long a freshly fetched URL may be served from cache. 0 skips the cache read; cache-eligible fresh results are still written with the default 7-day TTL so later non-zero-TTL callers can HIT. Safety-classified WAF husks remain live-only and are not written. Accepts Nh (hours, up to 168h), Nd (days, up to 7d), or the integer 0. Examples: 0, 48h, 2d. Invalid values receive a 422 validation_error with an actionable message.
• custom — FetchRequestCustom | Unset — User-supplied JSON payload, base64-encoded into the X-Fetch-Custom response header so callers can correlate the response back to caller-side state (job IDs, batch metadata, etc.). Capped at 4096 UTF-8 bytes after JSON serialization. Does NOT affect cache-key inputs — two requests differing only in custom share the same cache slot.

Call styles

sync_detailed(client=client, body=body) -> Response[Error | str]
sync(client=client, body=body) -> Error | str | None
await asyncio_detailed(client=client, body=body) -> Response[Error | str]
await asyncio(client=client, body=body) -> Error | str | None