Skip to main content
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.
The readyz() override described below is available in Pipecat Cloud base image 0.1.14 and later.

​
The built-in endpoints

EndpointPurposeDefault behaviorCustomizable
/readyzReadiness — is this instance ready to take a new session?Returns 200 OK✅ Yes, via readyz()
/livezLiveness — is this instance still alive?Always returns 200 OK❌ No
/readyz and /livez are reserved paths. Don’t define your own endpoints at these paths in your agent. See Reserved paths.

​
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: 
# 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 valueStatus codeMeaning
True / {"ready": True}200Ready for new sessions
False / {"ready": False}503Not ready — no new sessions will be routed here
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.