# Web request

> Fetch a URL on each trigger under the network allowlist; secrets come from a vault slot, never the Toy.

Source: https://docs.tune.toys/nodes/web.request/

Web request fetches a URL and sends the response into the Patch: parsed JSON, text or bytes, with the HTTP status, an error message and a done trigger.

## What it does

With `trigger` cabled, each trigger sends one request; without it, a new `url` on the input sends one. One request is in flight at a time; triggers that arrive meanwhile collapse into one more request. The URL comes from the `url` input or the node's `url` field, `https:` only (`http:` only for localhost). Header rows and a `headers` JSON object are added; credential headers such as `Authorization` or `Cookie` are refused.

Where the request goes is decided by policy, never by the Toy:

- **Direct** from the browser (no cookies, CORS mode) only when the host is in your network allowlist (Settings → Network) or belongs to an enabled `direct` addon.
- **Proxy** through Tune.Toys (`POST /v1/proxy/request`) for every other host, which needs sign-in. The proxy refuses private, loopback and metadata addresses after DNS, re-checks redirects and caps responses at 5 MiB and 20 seconds.
- **Keys** never reach the browser. The `auth` field names a vault slot such as `secret:openai`; the proxy injects the value on the server, and only to that addon's hosts. A Toy that uses a slot requires it, and the Play surface shows a chip until you add your key ([secrets](https://docs.tune.toys/concepts/secrets/)).

Web request runs in the browser's data runtime; the Player and exports report the data domain unavailable. During [replay](https://docs.tune.toys/concepts/takes/) it does not fetch: the recorded responses are played back.

## When to use it

Use it for any HTTP API that has no addon node yet. For the services in Settings → Addons prefer their typed nodes, such as [Open-Meteo forecast](https://docs.tune.toys/nodes/addon.open-meteo.forecast/), which build the URL for you. Follow it with [Convert](https://docs.tune.toys/nodes/data.convert/) to pick fields.

## Ports

<!-- ports:start -->

| Port       | Direction | Signal         | Lanes |
| ---------- | --------- | -------------- | ----- |
| `trigger`  | Input     | Data (trigger) | 1     |
| `url`      | Input     | Data (string)  | 1     |
| `body`     | Input     | Data (any)     | 1     |
| `headers`  | Input     | Data (json)    | 1     |
| `response` | Output    | Data (any)     | 1     |
| `status`   | Output    | Data (integer) | 1     |
| `error`    | Output    | Data (string)  | 1     |
| `done`     | Output    | Data (trigger) | 1     |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter | Label   | Range   | Default | Unit | Scale  | Notes                                                                                                                 |
| --------- | ------- | ------- | ------- | ---- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| `method`  | Method  | 0 to 4  | 0       |      | linear | HTTP method. Choices: 0 GET, 1 POST, 2 PUT, 3 PATCH, 4 DELETE.                                                        |
| `parse`   | Parse   | 0 to 3  | 0       |      | linear | How the response body is read; Auto follows the content type. Choices: 0 JSON, 1 Text, 2 Bytes, 3 Auto.               |
| `auth_in` | Auth in | 0 to 1  | 0       |      | linear | Where the vault secret named by auth is placed by the proxy. Choices: 0 Header, 1 Query.                              |
| `timeout` | Timeout | 1 to 20 | 10      | s    | linear | Seconds before the request fails with an error.                                                                       |
| `route`   | Route   | 0 to 2  | 2       |      | linear | Direct needs an allowlisted host that answers CORS; Auto falls back to the proxy. Choices: 0 Direct, 1 Proxy, 2 Auto. |
| `retries` | Retries | 0 to 3  | 0       |      | linear | Extra attempts after a network failure or a 5xx response.                                                             |

<!-- parameters:end -->

<!-- data:start -->

- `url`: url.
- `headers`: headers.
- `auth`: requirement.

<!-- data:end -->

### Method (`method`)

GET, POST, PUT, PATCH or DELETE. A cabled `body` is sent with every method except GET; objects are sent as JSON.

### Parse (`parse`)

JSON, Text, Bytes or Auto (by the response's content type). It sets the datatype of `response`. Bytes stay in memory and are never written into a take.

### Auth in (`auth_in`)

Where the proxy places the vault secret named by `auth`: as an `Authorization: Bearer` header, or as a `key` query parameter.

### Timeout (`timeout`)

Seconds, 1 to 20, before the request fails with an error.

### Route (`route`)

Direct, Proxy or Auto. Auto tries the browser first for an allowlisted host and falls back to the proxy after a CORS or network failure. A request with `auth` always uses the proxy.

### Retries (`retries`)

Extra attempts, 0 to 3, after a network failure, a 429 or a 5xx status, with growing pauses between them.

## Tips

- Cable `error` into a [Console log](https://docs.tune.toys/nodes/log.console/): refusals explain exactly what to allow or sign in for.
- An HTTP error status arrives on `status` and `error`; `response` only carries successful bodies.
- Respect the service's terms and rate limits. Use [Cron](https://docs.tune.toys/nodes/time.cron/) with a long interval rather than a fast loop.

## See also

[Web scrape](https://docs.tune.toys/nodes/web.scrape/), [WebSocket](https://docs.tune.toys/nodes/web.socket/), [Convert](https://docs.tune.toys/nodes/data.convert/), [Secrets and the vault](https://docs.tune.toys/concepts/secrets/), [Data cables](https://docs.tune.toys/concepts/data-cables/).