Health Checks

AISIX AI Gateway exposes health endpoints for different operator questions. Start with liveness when you need to know whether a listener is up. In self-hosted deployments, use authenticated admin health when you need model status and configuration freshness from the local admin listener.

Proxy liveness confirms that the proxy listener responds and the process is not shutting down. Admin liveness checks whether the private management listener is reachable in self-hosted mode. Admin health adds model health and snapshot freshness when you need more detail than liveness can provide.

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 intentionally marks liveness as failed. The route returns 500 Internal Server Error with a body ending in livez check failed, so Kubernetes probes and load balancers can stop routing traffic during drain.

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.

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": "ok",
  "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 shows that the health endpoint responded. Use each model's health value for the actionable signal:

• 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.

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 snapshot_age_seconds keeps growing, focus on etcd connectivity and configuration watch freshness.
• If configuration freshness is healthy but a model reports degraded or down, check the upstream provider credential, upstream network path, and provider availability.

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 readiness question. Continue with Metrics and Logs to connect health signals with runtime telemetry.