NGINX · Schema
HTTP Upstreams
Status information of all HTTP dynamically configurable groups.
API GatewayCachingCloud NativeLoad BalancerOpen SourceReverse ProxyWeb Server
JSON Schema
{
"$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-map-schema.json",
"title": "HTTP Upstreams",
"description": "Status information of all HTTP\n<a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone\">dynamically configurable</a>\n<a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream\">groups</a>.\n",
"type": "object",
"additionalProperties": {
"title": "HTTP Upstream",
"type": "object",
"properties": {
"peers": {
"title": "HTTP Upstream Servers",
"description": "An array of HTTP\n<a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream\">upstream servers</a>.\n",
"type": "array",
"items": {
"title": "HTTP Upstream Server",
"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
}
}
}
},
"keepalive": {
"type": "integer",
"description": "The current number of idle <a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive\">keepalive</a> connections.",
"example": 0
},
"zombies": {
"type": "integer",
"description": "The current number of servers removed from the group but still processing active client requests.",
"example": 0
},
"zone": {
"type": "string",
"description": "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\u2019s configuration and run-time state.",
"example": "example-zone"
},
"queue": {
"type": "object",
"description": "For the requests <a href=\"https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue\">queue</a>, the following data are provided:\n",
"properties": {
"size": {
"type": "integer",
"description": "The current number of requests in the queue.",
"example": 0
},
"max_size": {
"type": "integer",
"description": "The maximum number of requests that can be in the queue at the same time.",
"example": 0
},
"overflows": {
"type": "integer",
"description": "The total number of requests rejected due to the queue overflow.",
"example": 0
}
},
"example": {}
}
},
"example": {
"upstream_backend": {
"peers": [
{
"id": 0,
"server": "10.0.0.1:8088",
"name": "10.0.0.1:8088",
"backup": false,
"weight": 5,
"state": "up",
"active": 0,
"ssl": {
"handshakes": 620311,
"handshakes_failed": 3432,
"session_reuses": 36442,
"no_common_protocol": 4,
"handshake_timeout": 0,
"peer_rejected_cert": 0,
"verify_failures": {
"expired_cert": 2,
"revoked_cert": 1,
"hostname_mismatch": 2,
"other": 1
}
},
"max_conns": 20,
"requests": 667231,
"header_time": 20,
"response_time": 36,
"responses": {
"1xx": 0,
"2xx": 666310,
"3xx": 0,
"4xx": 915,
"5xx": 6,
"codes": {
"200": 666310,
"404": 915,
"503": 6
},
"total": 667231
},
"sent": 251946292,
"received": 19222475454,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 26214,
"fails": 0,
"unhealthy": 0,
"last_passed": true
},
"downtime": 0,
"downstart": "2022-06-28T11:09:21.602000+00:00",
"selected": "2022-06-28T15:01:25+00:00"
},
{
"id": 1,
"server": "10.0.0.1:8089",
"name": "10.0.0.1:8089",
"backup": true,
"weight": 1,
"state": "unhealthy",
"active": 0,
"max_conns": 20,
"requests": 0,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 26284,
"fails": 26284,
"unhealthy": 1,
"last_passed": false
},
"downtime": 262925617,
"downstart": "2022-06-28T11:09:21.602000+00:00",
"selected": "2022-06-28T15:01:25+00:00"
}
],
"keepalive": 0,
"zombies": 0,
"zone": "upstream_backend"
}
}
},
"example": {
"trac-backend": {
"peers": [
{
"id": 0,
"server": "10.0.0.1:8088",
"name": "10.0.0.1:8088",
"backup": false,
"weight": 5,
"state": "up",
"active": 0,
"ssl": {
"handshakes": 620311,
"handshakes_failed": 3432,
"session_reuses": 36442,
"no_common_protocol": 4,
"handshake_timeout": 0,
"peer_rejected_cert": 0,
"verify_failures": {
"expired_cert": 2,
"revoked_cert": 1,
"hostname_mismatch": 2,
"other": 1
}
},
"requests": 667231,
"header_time": 20,
"response_time": 36,
"responses": {
"1xx": 0,
"2xx": 666310,
"3xx": 0,
"4xx": 915,
"5xx": 6,
"codes": {
"200": 666310,
"404": 915,
"503": 6
},
"total": 667231
},
"sent": 251946292,
"received": 19222475454,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 26214,
"fails": 0,
"unhealthy": 0,
"last_passed": true
},
"downtime": 0,
"downstart": "2022-06-28T11:09:21.602000+00:00",
"selected": "2022-06-28T15:01:25+00:00"
},
{
"id": 1,
"server": "10.0.0.1:8089",
"name": "10.0.0.1:8089",
"backup": true,
"weight": 1,
"state": "unhealthy",
"active": 0,
"requests": 0,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 26284,
"fails": 26284,
"unhealthy": 1,
"last_passed": false
},
"downtime": 262925617,
"downstart": "2022-06-28T11:09:21.602000+00:00",
"selected": "2022-06-28T15:01:25+00:00"
}
],
"keepalive": 0,
"zombies": 0,
"zone": "trac-backend"
},
"hg-backend": {
"peers": [
{
"id": 0,
"server": "10.0.0.1:8088",
"name": "10.0.0.1:8088",
"backup": false,
"weight": 5,
"state": "up",
"active": 0,
"ssl": {
"handshakes": 620311,
"handshakes_failed": 3432,
"session_reuses": 36442,
"no_common_protocol": 4,
"handshake_timeout": 0,
"peer_rejected_cert": 0,
"verify_failures": {
"expired_cert": 2,
"revoked_cert": 1,
"hostname_mismatch": 2,
"other": 1
}
},
"requests": 667231,
"header_time": 20,
"response_time": 36,
"responses": {
"1xx": 0,
"2xx": 666310,
"3xx": 0,
"4xx": 915,
"5xx": 6,
"codes": {
"200": 666310,
"404": 915,
"503": 6
},
"total": 667231
},
"sent": 251946292,
"received": 19222475454,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 26214,
"fails": 0,
"unhealthy": 0,
"last_passed": true
},
"downtime": 0,
"downstart": "2022-06-28T11:09:21.602000+00:00",
"selected": "2022-06-28T15:01:25+00:00"
},
{
"id": 1,
"server": "10.0.0.1:8089",
"name": "10.0.0.1:8089",
"backup": true,
"weight": 1,
"state": "unhealthy",
"active": 0,
"requests": 0,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 26284,
"fails": 26284,
"unhealthy": 1,
"last_passed": false
},
"downtime": 262925617,
"downstart": "2022-06-28T11:09:21.602000+00:00",
"selected": "2022-06-28T15:01:25+00:00"
}
],
"keepalive": 0,
"zombies": 0,
"zone": "hg-backend"
}
}
}