# Custom alerts

`GET` `https://api.unusualwhales.com/api/socket/custom_alerts`

**NOTE:**
This is the documentation for websocket channel `custom_alerts`.
Websocket access for personal use is only available through the [Advanced plan](https://unusualwhales.com/pricing?product=api).

Unlike the other websocket channels, `custom_alerts` is a **per-user** stream. You only receive notifications that match the alert configurations on the Unusual Whales account that owns the API token used to connect. Configure alerts on [https://unusualwhales.com/notifications](https://unusualwhales.com/notifications); every notification fired against your account is also delivered on this channel.

You can find fully-functional examples that stream data from many channels here:

- Python: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output)
- Javascript: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs)



Connect to the websocket URI:

`wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN>`

then `join` the channel: `custom_alerts`.

Payload format:

```
[
  "custom_alerts",
  {
    "name": "Aggressive ask-side flow on AAPL",
    "noti_type": "flow_alerts",
    "user_noti_config_id": "f80a7f23-2cf6-4bc2-b7cd-2cb13e7a9a80",
    "user_id": "0d5b0a13-b9d8-4f3b-8a4f-7c6c9a9a1b40",
    "symbol": "AAPL",
    "symbol_type": "stock",
    "tape_time": "2026-04-27T14:32:11Z",
    "meta": {}
  }
]
```

`meta` is a free-form object whose shape depends on `noti_type`.

### Field reference

| Field | Type | Description |
|---|---|---|
| `name` | string | The alert configuration's display name. |
| `noti_type` | string | The kind of alert that fired (e.g. `"flow_alerts"`, `"price_alert"`, `"news"`). Determines the shape of `meta`. |
| `user_noti_config_id` | uuid string | Identifier of the alert configuration that produced this notification. Use this to group alerts by the rule that fired them. |
| `user_id` | uuid string | Account that received the alert (always the account associated with the API token). |
| `symbol` | string \| null | Symbol the alert is about, if applicable. |
| `symbol_type` | `"stock"` \| `"option_chain"` \| null | Tells you how to interpret `symbol`. |
| `tape_time` | ISO 8601 string | Time the alert fired, UTC. |
| `meta` | object | Free-form payload whose shape depends on `noti_type`. |



## Authentication

```
Authorization: Bearer YOUR_API_KEY
```



## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/socket/custom_alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("GET", "/api/socket/custom_alerts", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": []
}
```