Fetch

Low-latency raw HTTP fetch with byte-for-byte upstream responses. Accessed via client.fetch.

create

client.fetch.create(opts: FetchOpts, requestOptions?: RequestOptions): Promise<FetchResult>

POST /v1/fetch — fetch URL content via POST body.

Resolves a FetchResult — the raw content body plus X-Fetch-* metadata. The body is returned verbatim — a JSON-serving upstream comes back as the raw JSON string, not a parsed object.

requestOptions carries the CLIENT-side abort budget (requestTimeoutMs) and an optional caller signal. It matters most here: the gateway's own ceiling for a fetch is 60 s, so without a per-call budget a slow upstream holds the caller for the constructor default (2 minutes) rather than a duration the caller chose.

get

client.fetch.get(opts: FetchGetOpts, requestOptions?: RequestOptions): Promise<FetchResult>

GET /v1/fetch — fetch URL content via query params.

Resolves a FetchResult — the raw content body plus X-Fetch-* metadata.

Accepts only the four params the spec declares for this endpoint. custom is a POST-body option with no GET query param; use create() for custom metadata.

The query string is built by iterating FETCH_GET_QUERY_KEYS, the same list FetchGetOpts is derived from, so every accepted option is necessarily serialized.

requestOptions carries the CLIENT-side abort budget (requestTimeoutMs) and an optional caller signal. As on create, the gateway's own ceiling for a fetch is 60 s, so a per-call budget is what keeps a slow upstream from holding the caller for the constructor default.

Options (FetchOpts)

• url (required) — string
• country — string
• timeout_ms — number
• cache_ttl — string | 0 — How long a freshly fetched URL may be served from cache. Matches the OpenAPI FetchRequest.cache_ttl schema: a duration string ("48h", "2d", up to 168h / 7d) or the integer 0 to disable caching. Defaults to "48h" server-side when omitted.
• custom — Record<string, unknown> — User-supplied JSON payload, base64-encoded into the X-Fetch-Custom response header so callers can correlate the response to caller-side state. Capped at 4096 UTF-8 bytes after JSON serialization. Does NOT affect cache-key inputs.