> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Health checks

> Report agent readiness and liveness, and recycle instances on your own schedule

Pipecat Cloud continuously checks the health of each agent instance through two HTTP endpoints that the base image exposes for you: a **readiness** check and a **liveness** check. You don't need to add these endpoints yourself — they're built in — but you can customize the readiness check to control when an instance should receive new sessions.

<Note>
  The `readyz()` override described below is available in Pipecat Cloud base
  image `0.1.14` and later.
</Note>

## The built-in endpoints

| Endpoint  | Purpose                                                   | Default behavior        | Customizable          |
| --------- | --------------------------------------------------------- | ----------------------- | --------------------- |
| `/readyz` | Readiness — is this instance ready to take a new session? | Returns `200 OK`        | ✅ Yes, via `readyz()` |
| `/livez`  | Liveness — is this instance still alive?                  | Always returns `200 OK` | ❌ No                  |

<Warning>
  `/readyz` and `/livez` are reserved paths. Don't define your own endpoints at
  these paths in your agent. See [Reserved
  paths](../guides/session-api#important-notes).
</Warning>

## How readiness affects routing

Readiness is the signal Pipecat Cloud uses to decide whether an instance should be sent new work:

* When an instance reports **ready**, it can be assigned new sessions from the pool.
* When an instance reports **not ready**, Pipecat Cloud **stops routing new sessions to it**. Any session already running on that instance is **unaffected** and continues to completion.

This makes the readiness check a clean way to take an instance out of rotation without disrupting active calls — for example, while it finishes a graceful shutdown.

## Customizing the readiness check

Override the default readiness behavior by defining a `readyz()` function in your `bot.py`. It can be synchronous or asynchronous, and may return either a `bool` or a `dict` containing a `ready` key:

```python theme={null}
# Simple boolean
def readyz() -> bool:
    return is_healthy()

# With additional detail (returned in the response body)
def readyz() -> dict:
    if not database_connected():
        return {"ready": False, "reason": "database unavailable"}
    return {"ready": True}
```

Return values map to HTTP status codes:

| Return value                 | Status code | Meaning                                         |
| ---------------------------- | ----------- | ----------------------------------------------- |
| `True` / `{"ready": True}`   | `200`       | Ready for new sessions                          |
| `False` / `{"ready": False}` | `503`       | Not ready — no new sessions will be routed here |

<Tip>
  Use `readyz()` to gate on dependencies your agent needs in order to handle a
  session — for example a database, a model download, or an upstream API. If a
  dependency is unavailable, report not-ready so the instance isn't handed new
  sessions until it recovers.
</Tip>