Streaming and health routes

TestLookup sends live updates over a WebSocket and over server-sent events (SSE). Both are connections that stay open. These routes are not in the API specification, so they have no endpoint pages. This page explains how to connect to them and sign in.

Sign in to the WebSocket

Connect to /ws/live/{project_id} on the backend and send this as your first message:

{"type":"auth","token":"<access token>"}

• You must be a member of the project.
• The server closes the connection with code 4400 if the first message is malformed, and 4401 if authentication times out or the token is rejected.
• Add "protocol": 2 to the first message to receive batched live_batch frames. Clients that do not ask for it keep the original frame types. Each client receives at most five data frames per second.
• If your client falls behind, a reconcile_required message reports how many events were dropped (dropped).

Server-sent events

Open /api/v1/stream/sse/{project_id}?token=<access token> as an event stream. Browsers cannot send an Authorization header to an event stream, so the access token goes in the token query parameter.

• You must be a member of the project. Admins can open any project’s stream. A bad token returns 401, and a project you cannot access returns 403.
• The first event (initial_state) describes the project’s live sessions.
• To carry on after a disconnect, send the Last-Event-ID header with the ID of the last event you received. An ID is two numbers joined by a hyphen, such as 1718000000000-0. The server then sends what you missed. If it cannot, it sends reconcile_required with the current state. An ID in any other format returns 400.

Single-use invocation tickets

To follow an agent invocation while it runs:

1. Request a ticket with POST /api/v1/agents/invocations/{invocation_id}/events/ticket, using your normal credential.
2. Open GET /api/v1/agents/invocations/{invocation_id}/events with the ticket in the ticket query parameter, as an event stream. It sends progress events until the invocation’s run finishes.

A ticket works once and expires quickly, so request a new one every time you connect.

Health and metrics routes

Health checks are ordinary endpoints in the Health domain:

• GET /health/live: the process is running.
• GET /health/ready: critical dependencies are reachable.
• GET /health/version: the build identity.
• GET /health/details: the state of each service it depends on. It can return 200 while one of them is only partly working, so read the body.

A healthy response does not prove that workers deliver results, that AI models are installed, or that the database updates (migrations) match the code. /metrics exists only when metrics are turned on in the server settings. It is not in the API specification.

Reconnecting

• WebSocket: open a new connection and send the auth message again.
• Server-sent events: reconnect with Last-Event-ID, as described above.
• Agent invocation events: request a new ticket first. A used or expired ticket is refused.

Each time you connect, the server checks your project membership again.

Why these routes have no operation pages

The API specification lists 731 HTTP operations, and this reference has a page for each. The WebSocket and SSE routes above are not in the specification, so this page describes them, based on the API guide in the source repository.

One route looks like a WebSocket but is not. POST /ws/events/{run_id} is an ordinary HTTP POST that sends live events for a run, even though its path starts with /ws. By default it needs a project API key.

More detail is in the source repository on GitHub: the API guide and the endpoint index.