GET /api/v0/live opens one WebSocket. Subscribe to as many topics as you need on the same connection, and unsubscribe when you no longer want one.
Connect and subscribe
1
Open the connection
Send the API key on the upgrade request.
2
Subscribe
Send
subscribe with a topic and its params. A request_id lets you match the reply.3
Handle updates
The server replies
subscribed with a subscription_id. Updates then arrive as update messages with the payload in data. Each update also reports charged_usd, what that message cost, and, when it was billed, balance_usd, your organization’s balance after it.Keep the connection alive
- An idle connection can be closed by the network between you and the API.
- Send a WebSocket ping at least every 30 seconds. The server answers each ping with a pong.
- The server sends no messages of its own while nothing matches, so don’t rely on updates to keep the connection open.
Reconnect
Reconnect whenever the connection closes. Subscriptions belong to the connection, so subscribe again after reconnecting.- There is no backfill: only what happens after a subscription starts is sent. Use the pull endpoints, such as
GET /api/v0/transcripts, to fill any gap. - A client that falls 256 messages behind across all its subscriptions, or that does not accept a message within one second, is disconnected. Read messages promptly.
- A client message over 4 KiB closes the connection.
- Subscribing to
flight_statusorairport_statusagain sends, and charges, a new first update. See Billing. - A subscription can also end without the connection closing: when the charge for an update is refused, the server sends
unsubscribedwith anerror. Resolve the cause it names, such as an insufficient balance, before subscribing again.