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

# Connect

> Open the Enhanced Radar live WebSocket and subscribe to topics. Message format, replies, errors, and connection limits.

GET `wss://api.enhancedradar.com/api/v0/live`

Opens one WebSocket for live updates. Subscribe to as many topics as you need on the same connection, and unsubscribe when you no longer want one. Send the API key on the WebSocket upgrade request. The key is checked once, when the connection opens.

```bash theme={null}
websocat -H "Authorization: Bearer $ER_API_KEY" "wss://api.enhancedradar.com/api/v0/live"
```

For a walkthrough, see [Live updates](https://enhancedradar.com/docs/api/docs/api/guides/live-updates.md).

## Messages

Every message in either direction is one JSON text message.

**1. Subscribe**

Send `subscribe` with a `subscription_topic` and the topic's `params`:

```json theme={null}
{"action": "subscribe", "request_id": "3f9a7c21-5d4e-4b8a-9c6f-0e2d1a7b4c85", "subscription_topic": "pireps", "params": {"q": "turbulence", "latitude": 37.62, "longitude": -122.38, "radius_nm": 60}}
```

The server answers with `subscribed` and the `subscription_id` it assigned:

```json theme={null}
{"message_type": "subscribed", "request_id": "3f9a7c21-5d4e-4b8a-9c6f-0e2d1a7b4c85", "subscription_id": "6a0f5d6e-2b8c-4f0e-9a4d-1c7e3b5f8d21", "subscription_topic": "pireps"}
```

**2. Receive updates**

Each update for that subscription arrives as `update`, with the topic's payload in `data` and what the message cost in `charged_usd` and `balance_usd`:

```json theme={null}
{"message_type": "update", "subscription_id": "6a0f5d6e-2b8c-4f0e-9a4d-1c7e3b5f8d21", "subscription_topic": "pireps", "charged_usd": "0.150", "balance_usd": "9.850", "data": {"event_id": 5180144, "...": "..."}}
```

**3. Unsubscribe**

Send `unsubscribe` with the `subscription_id`. The server answers with `unsubscribed`; no more updates for that subscription are sent after it.

```json theme={null}
{"action": "unsubscribe", "request_id": "b71e4d09-2a6c-4f3e-8d5b-9c0a1e7f6d42", "subscription_id": "6a0f5d6e-2b8c-4f0e-9a4d-1c7e3b5f8d21"}
{"message_type": "unsubscribed", "request_id": "b71e4d09-2a6c-4f3e-8d5b-9c0a1e7f6d42", "subscription_id": "6a0f5d6e-2b8c-4f0e-9a4d-1c7e3b5f8d21", "subscription_topic": "pireps"}
```

Each update is charged to your organization as it is sent; see [Billing](https://enhancedradar.com/docs/api/docs/api/concepts/billing.md). When the charge for an update is refused because your balance does not cover it, it would go over a limit of your account tier, or the key is not owned by an organization, the update is not sent and the server ends the subscription with an `unsubscribed` message that has `error` and no `request_id`:

```json theme={null}
{"message_type": "unsubscribed", "subscription_id": "6a0f5d6e-2b8c-4f0e-9a4d-1c7e3b5f8d21", "subscription_topic": "pireps", "error": "insufficient balance: this needs $0.040 and $0.020 is available"}
```

A message the server cannot act on is answered with `error`. The connection stays open, and other subscriptions are not affected.

```json theme={null}
{"message_type": "error", "request_id": "3f9a7c21-5d4e-4b8a-9c6f-0e2d1a7b4c85", "subscription_topic": "pireps", "error": "radius_nm must be a number from 1 to 150"}
```

## Client messages

**action** `string` *required*

`subscribe` or `unsubscribe`.

**request\_id** `string`

A UUID you generate is recommended, but any string is accepted; it is copied into the reply so you can match the two.

**subscription\_topic** `string`

With `subscribe`: `transcripts`, `events`, `flight_status`, `airport_status`, or `pireps`.

**params** `object`

With `subscribe`: the topic's parameters. Numbers are JSON numbers and lists are JSON arrays. Unknown parameters are rejected.

**subscription\_id** `string`

With `unsubscribe`: a `subscription_id` from a `subscribed` reply on this connection.

## Server messages

**message\_type** `string`

`subscribed`, `update`, `unsubscribed`, or `error`.

**request\_id** `string`

The `request_id` of the client message this replies to. Absent on `update`, on an `unsubscribed` the server sends when it ends a subscription, and when the client sent none.

**subscription\_id** `string`

The subscription the message is about. On `error`, the `subscription_id` the client sent, if any.

**subscription\_topic** `string`

The subscription's topic.

**data** `object`

On `update` only: the topic's payload, described under each topic.

**charged\_usd** `string`

On `update`: what this message cost, in US dollars with three decimal places, e.g. `"0.150"`.

**balance\_usd** `string`

On a billed `update`: the organization's balance after this charge, in the same format. Omitted for a first `flight_status` update whose `status` is `null`, which is not billed.

**error** `string`

On `error`: what was wrong, e.g. a missing or invalid parameter, a refused charge, or a failure on our side; retry those later. On an `unsubscribed` the server sends when it ends a subscription: why it ended it.

## Topics

| Topic | Page |
| - | - |
| `transcripts` | [Transcripts topic](https://enhancedradar.com/docs/api/docs/api/api-reference/live/transcripts.md) |
| `events` | [Events topic](https://enhancedradar.com/docs/api/docs/api/api-reference/live/events.md) |
| `flight_status` | [Flight status topic](https://enhancedradar.com/docs/api/docs/api/api-reference/live/flight-status.md) |
| `airport_status` | [Airport status topic](https://enhancedradar.com/docs/api/docs/api/api-reference/live/airport-status.md) |
| `pireps` | [PIREPs topic](https://enhancedradar.com/docs/api/docs/api/api-reference/live/pireps.md) |

## Billing

Opening a connection and subscribing are free. Each update sent is charged at the price of its topic:

| Topic | Charged for | Price |
| - | - | - |
| `transcripts` | Each transcript sent. | \$0.03 per transcript |
| `events` | Each message: the first report of an event and each later update of it. | \$5.00 per message |
| `flight_status` | Each status sent, including the first. A first status whose `status` is `null` is free. | \$0.12 per status |
| `airport_status` | Each status sent, including the first. | \$1.50 per status |
| `pireps` | Each PIREP sent. | \$0.15 per PIREP |

The first update of `flight_status` and `airport_status` is charged when you subscribe; if that charge is refused, the server answers with `error` instead of `subscribed`. If the charge for a later update is refused, that subscription ends: the server sends `unsubscribed` with an `error` that says why. Each `update` reports what it cost in `charged_usd` and, when billed, the balance after it in `balance_usd`. The upgrade response does not report the cost of later updates. See [Pricing](https://enhancedradar.com/docs/api/docs/api/pricing.md) and [Billing](https://enhancedradar.com/docs/api/docs/api/concepts/billing.md).

## Behavior

The server handles client messages one at a time, in the order they arrive, and replies to each before reading the next. A `subscribe` that has to prepare a search or load a status can take a few seconds. Once `subscribed` is sent, updates for that subscription can arrive at any time, interleaved with updates for other subscriptions and with replies.

* Subscriptions belong to the connection. When the connection closes, every subscription on it ends; after reconnecting, subscribe again.
* Updates are not acknowledged, and there is no backfill: only what happens after a subscription starts is sent.
* A client that falls 256 messages behind across all its subscriptions, or that does not accept a message within one second, is disconnected and should reconnect.
* The server sends no messages of its own while nothing matches.
* 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.
* A client message over 4 KiB closes the connection.

The upgrade request itself returns `401` or `403` as described in [Errors](https://enhancedradar.com/docs/api/docs/api/concepts/errors.md); everything after that is reported with `error` messages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.