Health Checks

AISIX AI Gateway exposes several health and status endpoints, each answering a different operator question. Use liveness to decide whether the process should restart, readiness to decide whether the instance should receive traffic, and model status to investigate provider routing state.

The following table helps you choose the narrowest signal for the check you need:

Question	Endpoint	Listener	Authentication
Is the AISIX process running and not shutting down?	`GET /livez`	Proxy; admin in self-hosted mode	None
Should this instance receive proxy traffic?	`GET /readyz`	Proxy; admin in self-hosted mode	None
Has this instance applied any valid configuration?	`GET /status/ready`	Metrics/status	None
Did the latest configuration load completely, and what is AISIX serving?	`GET /status/config`	Metrics/status	None
Are models failing, and is the configuration snapshot fresh?	`GET /admin/v1/health`	Admin in self-hosted mode	Admin key
Is a direct model healthy, in cooldown, or excluded by background checks?	`GET /admin/v1/models/status` or `GET /status/models`	Admin or metrics/status	Admin key on the admin route; none on the status route

Proxy Liveness

Use proxy liveness for load balancer and orchestration probes. It confirms that the proxy listener can respond and the process is not shutting down.

Check the proxy listener:

curl -i "http://127.0.0.1:3000/livez"

The healthy response should return 200 OK with an ok body.

During graceful shutdown, AISIX marks liveness as failed. The route returns 503 Service Unavailable with a body ending in livez check failed. Graceful shutdown is an expected drain rather than an internal error, so the status code is 503, not 500. Liveness governs whether Kubernetes restarts the container; to stop sending traffic to a draining instance, use Readiness, which Kubernetes maps to Service endpoint membership.

Append ?verbose=1 for a multi-line body suitable for manual curl checks. Do not depend on the verbose body for automated probes.

Proxy liveness is intentionally narrow. It does not expose snapshot details, provider adapter inventory, provider credentials, or model health.

Admin Liveness

The admin listener exposes the same /livez route in self-hosted mode. Use it to confirm that the private management listener is reachable.

Check the admin listener:

curl -i "http://127.0.0.1:3001/livez"

Proxy and admin listeners are separate sockets. A healthy proxy listener does not prove that the admin listener is reachable, and a healthy admin listener does not prove that caller-facing traffic can reach the proxy.

Readiness

Liveness answers whether the container should be restarted. Readiness answers whether the instance should receive traffic. Point Kubernetes liveness probes at /livez and readiness probes at /readyz.

The /readyz route is served on the proxy listener, and also on the admin listener in self-hosted mode. The admin listener does not exist in managed mode, so probe the proxy listener there.

# Proxy listener (all modes):
curl -i "http://127.0.0.1:3000/readyz"
# Admin listener (self-hosted mode only):
curl -i "http://127.0.0.1:3001/readyz"

It returns 200 OK with an ok body when the instance can serve traffic, and 503 Service Unavailable when the instance should be kept out of rotation:

During graceful shutdown, while the instance drains.
Before the gateway applies its first configuration snapshot, while the instance is still starting up.
When the configuration watch is stale, with no apply within roughly the last five minutes, which can indicate a wedged watch.

Append ?verbose=1 for a multi-line body that names which readiness check failed. As with liveness, do not depend on the verbose body for automated probes.

Configuration Load Status

The metrics/status listener provides two configuration-specific checks when Prometheus metrics are enabled. Unlike /readyz, these routes report only configuration loading. They do not include process shutdown or stale-watch checks.

Use /status/ready as a simple gate for the first valid configuration:

curl -i "http://127.0.0.1:9090/status/ready"

The route returns 503 Service Unavailable with no configuration available until AISIX applies its first valid configuration. It returns 200 OK with ok afterward, including when AISIX is serving a last-known-good configuration after a later reload fails.

Use /status/config to investigate what AISIX observed, applied, or rejected from the configured source:

curl -sS "http://127.0.0.1:9090/status/config"

A successful file-source response has the following shape:

{
  "state": "synced",
  "source": {
    "type": "file",
    "source_hash": "sha256-hash",
    "observed_at": "2026-07-20T10:00:00Z"
  },
  "applied": {
    "config_hash": "sha256-hash",
    "apply_seq": 1,
    "applied_at": "2026-07-20T10:00:00Z",
    "resource_counts": {
      "api_keys": 1,
      "models": 2,
      "provider_keys": 2
    }
  },
  "last_reload": {
    "successful": true,
    "at": "2026-07-20T10:00:00Z"
  },
  "last_failure": null,
  "rejected": []
}

The top-level state summarizes the relationship between the latest observed configuration and the configuration AISIX is serving:

State	Meaning
`synced`	The applied configuration matches the latest observation and contains no rejected resources.
`degraded`	AISIX applied part of the latest observation, but rejected one or more resources.
`out_of_sync`	AISIX rejected the latest observation as a whole and is serving the last-known-good configuration, if one exists.
`empty`	AISIX applied a valid configuration that contains no resources.
`never_loaded`	AISIX has not applied a valid configuration since startup.

For an etcd source, source also reports connection state and the observed revision, while applied reports the applied revision. Use rejected for per-resource validation details and last_failure for the most recent load failure. These routes are unauthenticated, so keep the metrics/status listener private.

Per-Model Health

Use admin health in self-hosted deployments when liveness is green but you need more detail about configured models or configuration freshness. The endpoint requires an admin-key bearer token and returns the models known to the admin store.

Request admin health with an admin key:

curl -sS "http://127.0.0.1:3001/admin/v1/health" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

The endpoint returns a response similar to the following:

{
  "status": "degraded",
  "models": [
    {
      "id": "m-uuid-1",
      "name": "gpt-4o-prod",
      "health": 0
    },
    {
      "id": "m-uuid-2",
      "name": "claude-prod",
      "health": 1
    }
  ],
  "config": {
    "snapshot_revision": 1234567,
    "snapshot_age_seconds": 5
  }
}

The top-level status aggregates model health and configuration freshness:

ok when every model is healthy and configuration is fresh.
degraded when a model is degraded, or the snapshot is stale or not yet applied.
unhealthy when a model is down.

Use each model's health value and the config block for the per-dimension detail:

0: healthy, with no recent upstream failure streak
1: degraded, after 4 to 7 consecutive upstream failures
2: down, after 8 or more consecutive upstream failures

The optional config block reports snapshot freshness. A growing snapshot_age_seconds can indicate a stalled watch or delayed configuration propagation. The block is omitted when snapshot freshness is not available. When freshness tracking is available but has no age yet, snapshot_age_seconds can be null.

Model Runtime Status

The aggregate admin health response reports consecutive upstream failures. To see whether a direct model is currently eligible for routing, in cooldown, or excluded by a background health check, request the model runtime status instead.

In self-hosted mode, the authenticated admin route is available on the admin listener:

curl -sS "http://127.0.0.1:3001/admin/v1/models/status" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

When Prometheus metrics are enabled, the same response is available without application authentication on the metrics/status listener:

curl -sS "http://127.0.0.1:9090/status/models"

The /status/models route is for private operational monitoring. It exposes model IDs, display names, kinds, and runtime states, so restrict the metrics/status listener at the network layer.

Both routes return the same model status view. A response can include direct models and the virtual models that dispatch to them:

[
  {
    "id": "m-uuid-1",
    "display_name": "gpt-4o-primary",
    "kind": "direct",
    "status": "cooldown",
    "cooldown_until": {
      "secs_since_epoch": 1784543400,
      "nanos_since_epoch": 0
    },
    "status_reason": "upstream_rate_limited"
  },
  {
    "id": "m-uuid-2",
    "display_name": "chat-prod",
    "kind": "routing",
    "status": "not_applicable"
  }
]

Interpret status according to the model kind and its current runtime state:

healthy: The direct model is eligible for routing.
cooldown: Recent configured failure statuses temporarily removed the direct model from routing. Use cooldown_until and status_reason for context.
unhealthy: A background model check has excluded the direct model from routing.
not_applicable: The entry is a routing, semantic, or ensemble model. Inspect the direct target models that make provider calls.

Optional fields such as last_checked_at, last_check_status, and status_reason appear when AISIX has recorded the corresponding runtime event. This view is operational routing state; it does not replace the failure-count and configuration-freshness view from /admin/v1/health.

Interpret the Result

Use the narrowest signal that answers the question in front of you.

If proxy liveness fails, inspect process state, proxy listener binding, and listener TLS.
If admin liveness fails in self-hosted mode, inspect admin binding, private network placement, and admin listener TLS.
If /status/ready returns 503, inspect the initial configuration load. Use /status/config to distinguish an unavailable source from rejected content.
If /status/config reports degraded or out_of_sync, inspect rejected and last_failure before changing the last-known-good configuration.
If snapshot_age_seconds keeps growing, focus on etcd connectivity and configuration watch freshness.
If configuration freshness is healthy but admin health reports a model as degraded or down, check the upstream provider credential, upstream network path, and provider availability.
If a request has no eligible routing target, inspect model runtime status for targets in cooldown or unhealthy state.

Liveness does not prove that a model alias exists, a provider key is valid, or an upstream provider is reachable. Confirm those conditions with a caller-facing model list or a real request to the endpoint your application uses.

Admin health is also not a substitute for a real request-path check. A model can appear in health while caller access, provider credentials, or upstream behavior still prevents a proxy request from succeeding.

Next Steps

You have now seen which health endpoint answers each operational question. Continue with Metrics and Logs to connect health signals with runtime telemetry.

Proxy Liveness​

Admin Liveness​

Readiness​

Configuration Load Status​

Per-Model Health​

Model Runtime Status​

Interpret the Result​

Next Steps​