--- title: "remote.http | Grafana Agent documentation" description: "Learn about remote.http" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # remote.http `remote.http` exposes the response body of a URL to other components. The URL is polled for changes so that the most recent content is always available. The most common use of `remote.http` is to load discovery targets from an HTTP server. Multiple `remote.http` components can be specified by giving them different labels. ## Usage Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy remote.http "LABEL" { url = "URL_TO_POLL" } ``` ## Arguments The following arguments are supported: Expand table | Name | Type | Description | Default | Required | |------------------|---------------|----------------------------------------------------------|---------|----------| | `url` | `string` | URL to poll. | | yes | | `method` | `string` | Define HTTP method for the request | `"GET"` | no | | `headers` | `map(string)` | Custom headers for the request. | `{}` | no | | `body` | `string` | The request body. | `""` | no | | `poll_frequency` | `duration` | Frequency to poll the URL. | `"1m"` | no | | `poll_timeout` | `duration` | Timeout when polling the URL. | `"10s"` | no | | `is_secret` | `bool` | Whether the response body should be treated as a secret. | false | no | When `remote.http` performs a poll operation, an HTTP `GET` request is made against the URL specified by the `url` argument. A poll is triggered by the following: - When the component first loads. - Every time the component’s arguments get re-evaluated. - At the frequency specified by the `poll_frequency` argument. The poll is successful if the URL returns a `200 OK` response code. All other response codes are treated as errors and mark the component as unhealthy. After a successful poll, the response body from the URL is exported. ## Blocks The following blocks are supported inside the definition of `remote.http`: Expand table | Hierarchy | Block | Description | Required | |-------------------------------------|---------------------------------------|-----------------------------------------------------------|----------| | client | [client](#client-block) | HTTP client settings when connecting to the endpoint. | no | | client > basic\_auth | [basic\_auth](#basic_auth-block) | Configure basic\_auth for authenticating to the endpoint. | no | | client > authorization | [authorization](#authorization-block) | Configure generic authorization to the endpoint. | no | | client > oauth2 | [oauth2](#oauth2-block) | Configure OAuth2 for authenticating to the endpoint. | no | | client > oauth2 > tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | | client > tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | The `>` symbol indicates deeper levels of nesting. For example, `client > basic_auth` refers to an `basic_auth` block defined inside a `client` block. ### client block The `client` block configures settings used to connect to the HTTP server. Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------| | `bearer_token_file` | `string` | File containing a bearer token to authenticate with. | | no | | `bearer_token` | `secret` | Bearer token to authenticate with. | | no | | `enable_http2` | `bool` | Whether HTTP2 is supported for requests. | `true` | no | | `follow_redirects` | `bool` | Whether redirects returned by the server should be followed. | `true` | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | `bearer_token`, `bearer_token_file`, `basic_auth`, `authorization`, and `oauth2` are mutually exclusive, and only one can be provided inside of a `http_client_config` block. `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. ### basic\_auth block The `basic_auth` block configures basic authentication to use when polling the configured URL. Expand table | Name | Type | Description | Default | Required | |-----------------|----------|------------------------------------------|---------|----------| | `password_file` | `string` | File containing the basic auth password. | | no | | `password` | `secret` | Basic auth password. | | no | | `username` | `string` | Basic auth username. | | no | `password` and `password_file` are mutually exclusive, and only one can be provided inside a `basic_auth` block. ### authorization block The `authorization` block configures custom authorization to use when polling the configured URL. Expand table | Name | Type | Description | Default | Required | |--------------------|----------|--------------------------------------------|---------|----------| | `credentials_file` | `string` | File containing the secret value. | | no | | `credentials` | `secret` | Secret value. | | no | | `type` | `string` | Authorization type, for example, “Bearer”. | | no | `credential` and `credentials_file` are mutually exclusive, and only one can be provided inside an `authorization` block. ### oauth2 block The `oauth2` block configures OAuth2 authorization to use when polling the configured URL. Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------| | `client_id` | `string` | OAuth2 client ID. | | no | | `client_secret_file` | `string` | File containing the OAuth2 client secret. | | no | | `client_secret` | `secret` | OAuth2 client secret. | | no | | `endpoint_params` | `map(string)` | Optional parameters to append to the token URL. | | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | | `scopes` | `list(string)` | List of scopes to authenticate with. | | no | | `token_url` | `string` | URL to fetch the token from. | | no | `client_secret` and `client_secret_file` are mutually exclusive, and only one can be provided inside an `oauth2` block. The `oauth2` block may also contain a separate `tls_config` sub-block. `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. ### tls\_config block The `tls_config` block configures TLS settings for connecting to HTTPS servers. Expand table | Name | Type | Description | Default | Required | |------------------------|----------|----------------------------------------------------------|---------|----------| | `ca_pem` | `string` | CA PEM-encoded text to validate the server with. | | no | | `ca_file` | `string` | CA certificate to validate the server with. | | no | | `cert_pem` | `string` | Certificate PEM-encoded text for client authentication. | | no | | `cert_file` | `string` | Certificate file for client authentication. | | no | | `insecure_skip_verify` | `bool` | Disables validation of the server certificate. | | no | | `key_file` | `string` | Key file for client authentication. | | no | | `key_pem` | `secret` | Key PEM-encoded text for client authentication. | | no | | `min_version` | `string` | Minimum acceptable TLS version. | | no | | `server_name` | `string` | ServerName extension to indicate the name of the server. | | no | The following pairs of arguments are mutually exclusive and can’t both be set simultaneously: - `ca_pem` and `ca_file` - `cert_pem` and `cert_file` - `key_pem` and `key_file` When configuring client authentication, both the client certificate (using `cert_pem` or `cert_file`) and the client key (using `key_pem` or `key_file`) must be provided. When `min_version` is not provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If `min_version` is provided, it must be set to one of the following strings: - `"TLS10"` (TLS 1.0) - `"TLS11"` (TLS 1.1) - `"TLS12"` (TLS 1.2) - `"TLS13"` (TLS 1.3) ## Exported fields The following field is exported and can be referenced by other components: Expand table | Name | Type | Description | Default | Required | |-----------|----------------------|---------------------------|---------|----------| | `content` | `string` or `secret` | The contents of the file. | | no | If the `is_secret` argument was `true`, `content` is a secret type. ## Component health Instances of `remote.http` report as healthy if the most recent HTTP `GET` request of the specified URL succeeds. ## Debug information `remote.http` does not expose any component-specific debug information. ## Debug metrics `remote.http` does not expose any component-specific debug metrics. ## Example This example reads a JSON array of objects from an endpoint and uses them as a set of scrape targets: Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy remote.http "targets" { url = env("MY_TARGETS_URL") } prometheus.scrape "default" { targets = json_decode(remote.http.targets.content) forward_to = [prometheus.remote_write.default.receiver] } prometheus.remote_write "default" { client { url = env("PROMETHEUS_URL") } } ```