NGINX · Schema

HTTP Upstream Server

NginxHTTPUpstreamPeer schema from NGINX Plus REST API

API GatewayCachingCloud NativeLoad BalancerOpen SourceReverse ProxyWeb Server

Properties

Name Type Description
id integer The ID of the server.
server string An address of the server.
service string The service parameter value of the serv
name string The name of the server specified in the server directive.
backup boolean A boolean value indicating whether the server is a backup server.
weight integer Weight of the server.
state string Current state, which may be one of “up”, “draining”, “down”, “unavail”, “checking”, and “unhealthy”.
active integer The current number of active connections.
ssl object
max_conns integer The max_conns limit for the server.
requests integer The total number of client requests forwarded to this server.
responses object
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 “unavail”) due to the number of unsuccessful attempts reaching the health_checks object
downtime integer Total time the server was in the “unavail”, “checking”, and “unhealthy” states.
downstart string The time when the server became “unavail”, “checking”, or “unhealthy”, in the ISO 8601 format with millisecond resolution.
selected string 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 response header from the server.
response_time integer The average time to get the full response from the server.
View JSON Schema on GitHub

JSON Schema

plus-http-api-nginx-http-upstream-peer-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/nginx/refs/heads/main/json-schema/plus-http-api-nginx-http-upstream-peer-schema.json",
  "title": "HTTP Upstream Server",
  "description": "NginxHTTPUpstreamPeer schema from NGINX Plus REST API",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "The ID of the server.",
      "readOnly": true,
      "example": 0
    },
    "server": {
      "type": "string",
      "description": "An  <a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server\">address</a> of the server.",
      "example": "example-server"
    },
    "service": {
      "type": "string",
      "description": "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.",
      "example": "example-service"
    },
    "name": {
      "type": "string",
      "description": "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.",
      "readOnly": true,
      "example": "my_shared_zone"
    },
    "backup": {
      "type": "boolean",
      "description": "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.",
      "example": false
    },
    "weight": {
      "type": "integer",
      "description": "<a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight\">Weight</a> of the server.",
      "example": 0
    },
    "state": {
      "type": "string",
      "enum": [
        "up",
        "draining",
        "down",
        "unavail",
        "checking",
        "unhealthy"
      ],
      "description": "Current state, which may be one of \u201c<code>up</code>\u201d, \u201c<code>draining</code>\u201d, \u201c<code>down</code>\u201d, \u201c<code>unavail</code>\u201d, \u201c<code>checking</code>\u201d, and \u201c<code>unhealthy</code>\u201d.",
      "example": "example-state"
    },
    "active": {
      "type": "integer",
      "description": "The current number of active connections.",
      "readOnly": true,
      "example": 5
    },
    "ssl": {
      "type": "object",
      "readOnly": true,
      "properties": {
        "handshakes": {
          "type": "integer",
          "description": "The total number of successful SSL handshakes.",
          "readOnly": true,
          "example": 79572
        },
        "handshakes_failed": {
          "type": "integer",
          "description": "The total number of failed SSL handshakes.",
          "readOnly": true,
          "example": 21025
        },
        "session_reuses": {
          "type": "integer",
          "description": "The total number of session reuses during SSL handshake.",
          "readOnly": true,
          "example": 15762
        },
        "no_common_protocol": {
          "type": "integer",
          "description": "The number of SSL handshakes failed because of no common protocol.",
          "example": 4
        },
        "handshake_timeout": {
          "type": "integer",
          "description": "The number of SSL handshakes failed because of a timeout.",
          "example": 0
        },
        "peer_rejected_cert": {
          "type": "integer",
          "description": "The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message.",
          "example": 0
        },
        "verify_failures": {
          "type": "object",
          "description": "SSL certificate verification errors",
          "properties": {
            "expired_cert": {
              "type": "integer",
              "description": "An expired or not yet valid certificate was presented by an upstream server.",
              "example": 2
            },
            "revoked_cert": {
              "type": "integer",
              "description": "A revoked certificate was presented by an upstream server.",
              "example": 1
            },
            "hostname_mismatch": {
              "type": "integer",
              "description": "Server's certificate doesn't match the hostname.",
              "example": 2
            },
            "other": {
              "type": "integer",
              "description": "Other SSL certificate verification errors.",
              "example": 1
            }
          },
          "example": {}
        }
      },
      "example": {}
    },
    "max_conns": {
      "type": "integer",
      "description": "The <a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns\">max_conns</a> limit for the server.",
      "example": 0
    },
    "requests": {
      "type": "integer",
      "description": "The total number of client requests forwarded to this server.",
      "readOnly": true,
      "example": 31070465
    },
    "responses": {
      "type": "object",
      "readOnly": true,
      "properties": {
        "1xx": {
          "type": "integer",
          "description": "The number of responses with \u201c<code>1xx</code>\u201d status codes.",
          "readOnly": true,
          "example": 0
        },
        "2xx": {
          "type": "integer",
          "description": "The number of responses with \u201c<code>2xx</code>\u201d status codes.",
          "readOnly": true,
          "example": 0
        },
        "3xx": {
          "type": "integer",
          "description": "The number of responses with \u201c<code>3xx</code>\u201d status codes.",
          "readOnly": true,
          "example": 0
        },
        "4xx": {
          "type": "integer",
          "description": "The number of responses with \u201c<code>4xx</code>\u201d status codes.",
          "readOnly": true,
          "example": 0
        },
        "5xx": {
          "type": "integer",
          "description": "The number of responses with \u201c<code>5xx</code>\u201d status codes.",
          "readOnly": true,
          "example": 0
        },
        "codes": {
          "type": "object",
          "description": "The number of responses per each status code.",
          "readOnly": true,
          "properties": {
            "codeNumber": {
              "type": "integer",
              "description": "The number of responses with this particular status code.",
              "readOnly": true,
              "example": 0
            }
          },
          "example": {}
        },
        "total": {
          "type": "integer",
          "description": "The total number of responses obtained from this server.",
          "readOnly": true,
          "example": 98765
        }
      },
      "example": 1234567
    },
    "sent": {
      "type": "integer",
      "description": "The total number of bytes sent to this server.",
      "readOnly": true,
      "example": 20183175459
    },
    "received": {
      "type": "integer",
      "description": "The total number of bytes received from this server.",
      "readOnly": true,
      "example": 180157219
    },
    "fails": {
      "type": "integer",
      "description": "The total number of unsuccessful attempts to communicate with the server.",
      "readOnly": true,
      "example": 0
    },
    "unavail": {
      "type": "integer",
      "description": "How many times the server became unavailable for client requests (state \u201c<code>unavail</code>\u201d) 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.",
      "readOnly": true,
      "example": 0
    },
    "health_checks": {
      "type": "object",
      "readOnly": true,
      "properties": {
        "checks": {
          "type": "integer",
          "description": "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.",
          "example": 0
        },
        "fails": {
          "type": "integer",
          "description": "The number of failed health checks.",
          "example": 0
        },
        "unhealthy": {
          "type": "integer",
          "description": "How many times the server became unhealthy (state \u201c<code>unhealthy</code>\u201d).",
          "example": 0
        },
        "last_passed": {
          "type": "boolean",
          "description": "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>.",
          "example": false
        }
      },
      "example": 0
    },
    "downtime": {
      "type": "integer",
      "readOnly": true,
      "description": "Total time the server was in the \u201c<code>unavail</code>\u201d, \u201c<code>checking</code>\u201d, and \u201c<code>unhealthy</code>\u201d states.",
      "example": 0
    },
    "downstart": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "The time when the server became \u201c<code>unavail</code>\u201d, \u201c<code>checking</code>\u201d, or \u201c<code>unhealthy</code>\u201d, in the ISO 8601 format with millisecond resolution.",
      "example": "2026-04-21T10:30:00.000Z"
    },
    "selected": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "The time when the server was last selected to process a request, in the ISO 8601 format with millisecond resolution.",
      "example": "2026-04-21T10:30:00.000Z"
    },
    "header_time": {
      "type": "integer",
      "readOnly": true,
      "description": "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.",
      "example": 0
    },
    "response_time": {
      "type": "integer",
      "readOnly": true,
      "description": "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.",
      "example": 0
    }
  }
}