---
title: "Return status of a stream upstream server group"
method: GET
path: "/stream/upstreams/{streamUpstreamName}/"
tags: ["Stream Upstreams", "Method GET"]
---

# Return status of a stream upstream server group

`GET /stream/upstreams/{streamUpstreamName}/`

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

## Query parameters

- `fields` string

## Response `200`

Success

- NginxStreamUpstream
  - `peers` NginxStreamUpstreamPeer[] — Array of stream upstream servers.
    - `id` integer — The ID of the server.
    - `server` string — An <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> of the server.
    - `service` string — The <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> parameter value of the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a> directive.
    - `name` string, hostname — The name of the server specified in the <a href="https://nginx.org/en/docs/stream/ngx_stream_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/stream/ngx_stream_upstream_module.html#backup">backup</a> server.
    - `weight` integer — <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">Weight</a> of the server.
    - `state` 'up' | 'down' | 'unavail' | 'checking' | 'unhealthy' — Current state, which may be one of “<code>up</code>”, “<code>down</code>”, “<code>unavail</code>”, “<code>checking</code>”, or “<code>unhealthy</code>”.
    - `active` integer — The current number of 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/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> limit for the server.
    - `connections` integer — The total number of client connections forwarded to this server.
    - `connect_time` integer — The average time to connect to the upstream server.
    - `first_byte_time` integer — The average time to receive the first byte of data.
    - `response_time` integer — The average time to receive the last byte of data.
    - `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 connections (state “<code>unavail</code>”) due to the number of unsuccessful attempts reaching the <a href="https://nginx.org/en/docs/stream/ngx_stream_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/stream/ngx_stream_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 whether the last health check request was successful and passed <a href="https://nginx.org/en/docs/stream/ngx_stream_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 connection, in the ISO 8601 format with millisecond resolution.
  - `zombies` integer — The current number of servers removed from the group but still processing active client connections.
  - `zone` string — The name of the shared memory <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#zone">zone</a> that keeps the group’s configuration and run-time state.

## 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)