---
title: "Return status of an HTTP upstream server group"
method: GET
path: "/http/upstreams/{httpUpstreamName}/"
tags: ["HTTP Upstreams", "Method GET"]
---

# Return status of an HTTP upstream server group

`GET /http/upstreams/{httpUpstreamName}/`

Returns status of a particular HTTP upstream server group and its servers.

## Query parameters

- `fields` string

## Response `200`

Success

- NginxHTTPUpstream
  - `peers` NginxHTTPUpstreamPeer[] — An array of HTTP <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">upstream servers</a>.
    - `id` integer — The ID of the server.
    - `server` string — An <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</a> of the server.
    - `service` string — The <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</a> parameter value of the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> directive.
    - `name` string — The name of the server specified in the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> directive.
    - `backup` boolean — A boolean value indicating whether the server is a <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</a> server.
    - `weight` integer — <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">Weight</a> of the server.
    - `state` 'up' | 'draining' | 'down' | 'unavail' | 'checking' | 'unhealthy' — Current state, which may be one of “<code>up</code>”, “<code>draining</code>”, “<code>down</code>”, “<code>unavail</code>”, “<code>checking</code>”, and “<code>unhealthy</code>”.
    - `active` integer — The current number of active connections.
    - `ssl` object
      - `handshakes` integer — The total number of successful SSL handshakes.
      - `handshakes_failed` integer — The total number of failed SSL handshakes.
      - `session_reuses` integer — The total number of session reuses during SSL handshake.
      - `no_common_protocol` integer — The number of SSL handshakes failed because of no common protocol.
      - `handshake_timeout` integer — The number of SSL handshakes failed because of a timeout.
      - `peer_rejected_cert` integer — The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message.
      - `verify_failures` object — SSL certificate verification errors
        - `expired_cert` integer — An expired or not yet valid certificate was presented by an upstream server.
        - `revoked_cert` integer — A revoked certificate was presented by an upstream server.
        - `hostname_mismatch` integer — Server's certificate doesn't match the hostname.
        - `other` integer — Other SSL certificate verification errors.
    - `max_conns` integer — The <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</a> limit for the server.
    - `requests` integer — The total number of client requests forwarded to this server.
    - `responses` object
      - `1xx` integer — The number of responses with “<code>1xx</code>” status codes.
      - `2xx` integer — The number of responses with “<code>2xx</code>” status codes.
      - `3xx` integer — The number of responses with “<code>3xx</code>” status codes.
      - `4xx` integer — The number of responses with “<code>4xx</code>” status codes.
      - `5xx` integer — The number of responses with “<code>5xx</code>” status codes.
      - `codes` object — The number of responses per each status code.
        - `codeNumber` integer — The number of responses with this particular status code.
      - `total` integer — The total number of responses obtained from this server.
    - `sent` integer — The total number of bytes sent to this server.
    - `received` integer — The total number of bytes received from this server.
    - `fails` integer — The total number of unsuccessful attempts to communicate with the server.
    - `unavail` integer — How many times the server became unavailable for client requests (state “<code>unavail</code>”) due to the number of unsuccessful attempts reaching the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</a> threshold.
    - `health_checks` object
      - `checks` integer — The total number of <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check">health check</a> requests made.
      - `fails` integer — The number of failed health checks.
      - `unhealthy` integer — How many times the server became unhealthy (state “<code>unhealthy</code>”).
      - `last_passed` boolean — Boolean indicating if the last health check request was successful and passed <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match">tests</a>.
    - `downtime` integer — Total time the server was in the “<code>unavail</code>”, “<code>checking</code>”, and “<code>unhealthy</code>” states.
    - `downstart` string, date-time — The time when the server became “<code>unavail</code>”, “<code>checking</code>”, or “<code>unhealthy</code>”, in the ISO 8601 format with millisecond resolution.
    - `selected` string, date-time — The time when the server was last selected to process a request, in the ISO 8601 format with millisecond resolution.
    - `header_time` integer — The average time to get the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_header_time">response header</a> from the server.
    - `response_time` integer — The average time to get the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time">full response</a> from the server.
    - `response_time_hist` object — Histogram of upstream response times collected per upstream server.
      - `count` integer — Total number of recorded responses.
      - `sum` integer — Sum of all recorded upstream response times, in milliseconds.
      - `buckets` object — Histogram bucket counters for upstream response times, in milliseconds. Each bucket name ("5","10","25","50", etc.) is a time limit in milliseconds. Each bucket value is the number of responses within that time bucket. The "inf" bucket counts responses greater than 10000 ms.
        - `5` integer — The total number of responses with response time less than or equal to 5 ms.
        - `10` integer — The total number of responses with response time greater than 5 ms and less than or equal to 10 ms.
        - `25` integer — The total number of responses with response time greater than 10 ms and less than or equal to 25 ms.
        - `50` integer — The total number of responses with response time greater than 25 ms and less than or equal to 50 ms.
        - `75` integer — The total number of responses with response time greater than 50 ms and less than or equal to 75 ms.
        - `100` integer — The total number of responses with response time greater than 75 ms and less than or equal to 100 ms.
        - `250` integer — The total number of responses with response time greater than 100 ms and less than or equal to 250 ms.
        - `500` integer — The total number of responses with response time greater than 250 ms and less than or equal to 500 ms.
        - `750` integer — The total number of responses with response time greater than 500 ms and less than or equal to 750 ms.
        - `1000` integer — The total number of responses with response time greater than 750 ms and less than or equal to 1000 ms.
        - `2500` integer — The total number of responses with response time greater than 1000 ms and less than or equal to 2500 ms.
        - `5000` integer — The total number of responses with response time greater than 2500 ms and less than or equal to 5000 ms.
        - `7500` integer — The total number of responses with response time greater than 5000 ms and less than or equal to 7500 ms.
        - `10000` integer — The total number of responses with response time greater than 7500 ms and less than or equal to 10000 ms.
        - `inf` integer — The total number of observations with response time greater than 10000 ms.
  - `keepalive` integer — The current number of idle <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive">keepalive</a> connections.
  - `zombies` integer — The current number of servers removed from the group but still processing active client requests.
  - `zone` string — The name of the shared memory <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">zone</a> that keeps the group’s configuration and run-time state.
  - `queue` object — For the requests <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue">queue</a>, the following data are provided:
    - `size` integer — The current number of requests in the queue.
    - `max_size` integer — The maximum number of requests that can be in the queue at the same time.
    - `overflows` integer — The total number of requests rejected due to the queue overflow.

## Other responses

- `400` — Upstream is static (*UpstreamStatic*)
- `404` — Unknown version (*UnknownVersion*), upstream not found (*UpstreamNotFound*)

---

[API](https://skmtc.dev/nginx/apis/nginx-plus-rest-api.md) · [All operations](https://skmtc.dev/nginx/apis/nginx-plus-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nginx/nginx-plus-rest-api/revisions/533ae7834228/schema)