> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-pcc-instance-reuse-and-readyz-t3090.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Health Checks

> Report agent readiness and liveness to control which instances receive new sessions

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.

## What readiness does not do

Reporting not-ready takes an instance out of rotation. It does not replace it.

Pipecat Cloud does not start a fresh instance to stand in for one that reports not-ready, and the instance does not restart itself. Its process keeps running with whatever state it already had.

So `readyz()` is not a way to recycle an instance. If your agent needs a fresh process, for example to clear memory it could not release, reporting not-ready will not give you one. There is no per-instance recycle setting today. Instances are replaced when you deploy again, which discards instances created before that deployment. See [Instance reuse and memory](./scaling#instance-reuse-and-memory) for what carries over when an instance serves another session.

## 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>