# 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**

```python
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**

```python
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
```