`http_get`

HTTP GET request convenience wrapper.

Parameters

urlstringrequired: Request URL. Supports context interpolation via ${ctx.key}.
headersobjectdefault {}: Key-value map of request headers. Header values support ${ctx.key} interpolation.
body_typestringdefault "json": Body encoding: json, form, text, artifact, or multipart.
bodyany: Inline payload, or an artifact descriptor/URI for artifact mode.
body_keystring: Context key containing an artifact descriptor/URI.
partsarray: Multipart text/artifact parts.
response_modestringdefault "inline": inline returns parsed JSON/text; artifact streams the response to the artifact store.
timeoutnumberdefault 30: Total deadline in seconds for one request attempt, including redirects and response transfer.
authobject: Authentication configuration. See [Auth](#auth) below.
output_keystringdefault "http": Prefix for context output keys.
fail_on_statusbooleandefault true: When true, non-2xx responses return an error after any configured status retries. When false, non-2xx responses are returned as normal output.
retry_statusesarraydefault []: HTTP status codes to retry, as numbers or numeric strings.
status_retriesintegerdefault 0: Number of retries for responses whose status appears in retry_statuses; maximum 100.
max_status_retriesintegerdefault 0: Alias for status_retries, with the same maximum 100.
status_retry_backoffnumberdefault 1: Base retry delay in seconds. Delay uses exponential backoff by attempt; minimum 0.01 when retries are enabled.
respect_retry_afterbooleandefault true: When true, a numeric Retry-After response header overrides the backoff delay.
max_retry_afternumberdefault 60: Maximum status retry delay in seconds; minimum 0.01 when retries are enabled.
max_redirectsintegerdefault 10: Maximum redirects to follow; 0 disables redirects and 100 is the hard ceiling.
allow_cross_origin_redirectsbooleandefault false: Allow redirects that change scheme, host, or port. Even when enabled, cross-origin redirects are refused when auth, credentials embedded in URL userinfo, caller-configured headers, or a request body is present, because arbitrary credentials cannot be stripped safely. Generated Referer headers are disabled.
proxy_modestringdefault "auto": auto uses the system proxy unless private-network blocking is enabled; system always uses it; direct bypasses it.
block_private_networkbooleandefault false: Refuse internal initial/redirect targets after validating and pinning every DNS answer. Incompatible with proxy_mode = "system".

For body_type = "form", body must be an object and is sent as application/x-www-form-urlencoded. For body_type = "text", body is sent as plain text. Artifact and multipart input contracts match http_request, including artifact-only sources and the HTTP byte limit.

Auth

The auth object supports three authentication types, determined by auth.type:

`auth.type`	Fields	Behavior
`"bearer"`	`token` (string)	Sets the `Authorization: Bearer <token>` header. Default when `auth.type` is omitted. Token supports `${ctx.key}` interpolation.
`"basic"`	`username` (string), `password` (string)	Sets basic authentication. `username` defaults to `""` if omitted. `password` is optional.
`"api_key"`	`key` (string), `header` (string)	Sets a custom header with the API key. `header` defaults to `"X-API-Key"`. Key supports `${ctx.key}` interpolation.

Context Output

On a successful response (HTTP 2xx), or on a non-2xx response when fail_on_status = false, the following keys are written to the context:

{output_key}_status -- HTTP status code as a number (e.g., 200).
{output_key}_headers -- Response headers as a key-value object.
{output_key}_success -- Boolean true for HTTP 2xx, false otherwise.
{output_key}_attempts -- Number of HTTP attempts, including the first request and any status retries.

Inline mode returns {output_key}_data as parsed JSON or text. Artifact mode returns {output_key}_artifact instead and preserves binary bytes without UTF-8 conversion.

By default, non-success responses (non-2xx) return an error without materializing the final body. Set fail_on_status = false when the flow should inspect provider error responses, such as 401, 402, 429, or 5xx bodies and headers.

With the default output_key of "http", artifact mode replaces http_data with http_artifact.

Status Retries

Status retries are separate from step-level retries. They retry only HTTP responses whose status is listed in retry_statuses; transport errors still surface as node errors and can be handled by step retry configuration.

Retry counts, redirect counts, booleans, and delay values are parsed strictly: a present but invalid value is an error rather than being treated as an omitted default. A provider's Retry-After: 0 is floored to 0.01 seconds.

flow:step("probe", nodes.http_get({
    url = "https://api.example.com/resource",
    output_key = "probe",
    fail_on_status = false,
    retry_statuses = { 429, 500, 502, 503 },
    status_retries = 2,
    status_retry_backoff = 0.5,
    respect_retry_after = true,
    max_retry_after = 10
}))

Example

local flow = Flow.new("fetch_user")

flow:step("get_user", nodes.http_get({
    url = "https://api.example.com/users/${ctx.user_id}",
    headers = { ["Accept"] = "application/json" },
    auth = { type = "bearer", token = "${ctx.api_token}" },
    timeout = 15,
    output_key = "user"
}))

flow:step("done", nodes.log({
    message = "Fetched user: ${ctx.user_data}",
    level = "info"
})):depends_on("get_user")

return flow