Get an Upstream

GET /apisix/admin/upstreams/{id}

Get an Upstream

Retrieve a single upstream by its ID.

Parameters

• id (path, string, required): Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Responses

• 200: Successful response.
• key (string, required):
• value (object, required): Upstream configuration defining backend service nodes and load balancing behavior.

An upstream must specify either nodes (static list) or service_name + discovery_type (service discovery).

• value.id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
• anyOf variant 1: String ID
• anyOf variant 2: Integer ID
• value.name (string, optional): Human-readable name for the upstream.
• value.desc (string, optional): Description of the upstream.
• value.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
• value.create_time (integer, optional): Unix timestamp when the upstream was created. Read-only, set automatically.
• value.update_time (integer, optional): Unix timestamp when the upstream was last updated. Read-only, set automatically.
• value.nodes (object, optional): The upstream endpoints.
• allOf variant 1
• anyOf variant 1: Weight Mapping
• anyOf variant 2: Node Objects
• value.nodes[].host (string, required): Hostname or IP address of the upstream node.
• value.nodes[].port (integer, optional): Port of the upstream node.
• value.nodes[].weight (integer, required): Weight for load balancing. Higher values mean more traffic. 0 means no traffic.
• value.nodes[].priority (integer, optional): Priority of the node. Nodes with higher priority are used first. Lower-priority nodes serve as fallbacks.
• value.nodes[].metadata (object, optional): Arbitrary metadata associated with this node.
• value.retries (integer, optional): Number of retry attempts when a request to the upstream fails.
• value.retry_timeout (number, optional): Maximum time in seconds for retry attempts. 0 disables the retry timeout.
• value.timeout (object, optional): Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.
• value.timeout.connect (number, required): Timeout in seconds for establishing a connection to the upstream.
• value.timeout.send (number, required): Timeout in seconds for sending data to the upstream.
• value.timeout.read (number, required): Timeout in seconds for reading the response from the upstream.
• value.type (string, optional): Load balancing algorithm.
• value.hash_on (string, optional): What to hash on when type is chash.
• value.key (string, optional): The hash key used when type is chash. Required when hash_on is header, cookie, vars, or vars_combinations. Not needed when hash_on is consumer.
• value.scheme (string, optional): Protocol for communicating with upstream nodes.
• value.checks (object, optional): Health check configuration for monitoring upstream node availability. Active checks require at least the active field.
• value.checks.active (object, optional): Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.
• value.checks.active.type (string, optional): Protocol type for health check probes.
• value.checks.active.timeout (number, optional): Timeout in seconds for each health check probe.
• value.checks.active.concurrency (integer, optional): Number of targets to check concurrently during active health checks.
• value.checks.active.host (string, optional): Hostname to use in the health check probe Host header. Defaults to the upstream node's host.
• value.checks.active.port (integer, optional): Port to use for health check probes. Defaults to the upstream node's port.
• value.checks.active.http_path (string, optional): HTTP request path for health check probes.
• value.checks.active.https_verify_certificate (boolean, optional): Whether to verify the upstream's TLS certificate during HTTPS health checks.
• value.checks.active.req_headers (array, optional): Additional HTTP headers to include in health check probe requests.
• value.checks.active.healthy (object, optional): Thresholds for considering a target healthy during active checks.
• value.checks.active.healthy.interval (integer, optional): Interval in seconds between active health check probes for healthy targets.
• value.checks.active.healthy.http_statuses (array, optional): HTTP status codes that indicate a healthy target.
• value.checks.active.healthy.successes (integer, optional): Number of consecutive successful probes to consider a target healthy.
• value.checks.active.unhealthy (object, optional): Thresholds for considering a target unhealthy during active checks.
• value.checks.active.unhealthy.interval (integer, optional): Interval in seconds between active health check probes for unhealthy targets.
• value.checks.active.unhealthy.http_statuses (array, optional): HTTP status codes that indicate an unhealthy target.
• value.checks.active.unhealthy.http_failures (integer, optional): Number of HTTP failures to consider a target unhealthy.
• value.checks.active.unhealthy.tcp_failures (integer, optional): Number of TCP connection failures to consider a target unhealthy.
• value.checks.active.unhealthy.timeouts (integer, optional): Number of probe timeouts to consider a target unhealthy.
• value.checks.passive (object, optional): Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.
• value.checks.passive.type (string, optional): Protocol type for passive health monitoring.
• value.checks.passive.healthy (object, optional): Thresholds for considering a target healthy based on real traffic responses.
• value.checks.passive.healthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate a healthy target.
• value.checks.passive.healthy.successes (integer, optional): Number of consecutive successful requests to restore a target to healthy status.
• value.checks.passive.unhealthy (object, optional): Thresholds for considering a target unhealthy based on real traffic responses.
• value.checks.passive.unhealthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate an unhealthy target.
• value.checks.passive.unhealthy.tcp_failures (integer, optional): Number of TCP failures from real traffic to consider a target unhealthy.
• value.checks.passive.unhealthy.timeouts (integer, optional): Number of timeouts from real traffic to consider a target unhealthy.
• value.checks.passive.unhealthy.http_failures (integer, optional): Number of HTTP failures from real traffic to consider a target unhealthy.
• anyOf variant 1: Active Check
• anyOf variant 2: Passive Check
• value.tls (object, optional): TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.
• value.tls.client_cert_id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
• anyOf variant 1: String ID
• anyOf variant 2: Integer ID
• value.tls.client_cert (string, optional): PEM-encoded client certificate for mTLS with the upstream.
• value.tls.client_key (string, optional): PEM-encoded client private key for mTLS with the upstream.
• value.tls.verify (boolean, optional): Whether to verify the upstream server's TLS certificate. Currently only supported for Kafka upstreams.
• value.keepalive_pool (object, optional): Connection pool configuration for keepalive connections to upstream nodes.
• value.keepalive_pool.size (integer, optional): Maximum number of keepalive connections cached in the connection pool.
• value.keepalive_pool.idle_timeout (number, optional): Time in seconds after which an idle keepalive connection is closed. 0 disables the timeout.
• value.keepalive_pool.requests (integer, optional): Maximum number of requests that can be sent over a single keepalive connection before it is closed.
• value.pass_host (string, optional): How to set the Host header when proxying to the upstream.
• value.upstream_host (string, optional): Custom Host header value. Only effective when pass_host is rewrite.
• value.discovery_type (string, optional): Service discovery type (e.g., dns, consul, nacos, eureka). Required when using service discovery instead of static nodes.
• value.discovery_args (object, optional): Additional arguments for service discovery.
• value.discovery_args.namespace_id (string, optional): Namespace ID for Nacos service discovery.
• value.discovery_args.group_name (string, optional): Group name for service discovery.
• value.service_name (string, optional): Service name for service discovery. Required when discovery_type is set.
• oneOf variant 1: Use Upstream Nodes
• oneOf variant 2: Use Service Registry
• createdIndex (integer, optional):
• modifiedIndex (integer, optional):
• 401: Unauthorized — The API key is missing, invalid, or lacks permission.
• error_msg (string, required): Authentication error message.
• description (string, optional): Detailed reason for the authentication failure.
• 404: Not Found — The specified resource does not exist.
• error_msg (string, required): Error message indicating the resource was not found.

cURL

curl -X GET 'http://127.0.0.1:9180/apisix/admin/upstreams/{id}'