> For the complete documentation index, see [llms.txt](https://docs.pulsoid.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pulsoid.net/heart-rate-and-sensor-data/read-data-via-websocket-v2.md).

# Read Data via WebSocket v2

Version 2 of the real-time API streams typed messages. You choose which message types to receive, and besides heart rate the connection can deliver the battery level of the user's heart rate monitor or watch and data ingestion pause notifications.

{% hint style="info" %}
The WebSocket connection can be interrupted at any point in time, make sure to have retry logic with backoff.
{% endhint %}

***

#### Request

| Key            | Value                                               |
| -------------- | --------------------------------------------------- |
| URL            | `wss://dev.pulsoid.net/api/v2/data/real_time`       |
| Required scope | Depends on the requested types, see the table below |

#### Authentication

Provide your OAuth2 Bearer token using one of the following methods:

| Method          | Example                                                               |
| --------------- | --------------------------------------------------------------------- |
| Query parameter | `wss://dev.pulsoid.net/api/v2/data/real_time?access_token=YOUR_TOKEN` |
| Header          | `Authorization: Bearer YOUR_TOKEN`                                    |

#### Query Parameters

| Parameter      | Type     | Default      | Description                                                 |
| -------------- | -------- | ------------ | ----------------------------------------------------------- |
| `access_token` | `string` |              | OAuth2 access token (alternative to `Authorization` header) |
| `types`        | `string` | `heart_rate` | Comma-separated list of message types to subscribe to       |

#### Available Message Types

| Type              | Required scope            | Description                                                         |
| ----------------- | ------------------------- | ------------------------------------------------------------------- |
| `heart_rate`      | `data:heart_rate:read`    | Real-time heart rate updates                                        |
| `battery_level`   | `data:battery_level:read` | Battery level of the measuring device (heart rate monitor or watch) |
| `ingestion_pause` | `data:heart_rate:read`    | Pulsoid paused accepting the user's data until a given time         |

To subscribe to multiple types, separate them with commas:

```
?types=heart_rate,battery_level,ingestion_pause
```

The token must have the scope of every requested type, otherwise the connection is rejected with HTTP `400` and error code `6003`. Unknown types are ignored.

{% hint style="warning" %}
The `types` parameter is supported only by v2. Passing it to `wss://dev.pulsoid.net/api/v1/data/real_time` rejects the connection with HTTP `400` and error code `6009`.
{% endhint %}

#### Connection Status Codes

| Status | Description                                                    |
| ------ | -------------------------------------------------------------- |
| `101`  | Connection established                                         |
| `400`  | The token does not have the scope required by a requested type |
| `401`  | Missing or invalid token                                       |

The server closes the connection when the token is revoked or expires.

**Websocket URL Request Example**

```url
wss://dev.pulsoid.net/api/v2/data/real_time?access_token=8c4da3ce-7ed7-4a19-a1f1-058498661e45&types=heart_rate,battery_level,ingestion_pause
```

***

#### Response Messages

All messages are JSON objects with the following base structure:

| Field       | Type     | Description                                    |
| ----------- | -------- | ---------------------------------------------- |
| `type`      | `string` | The message type (see table above)             |
| `timestamp` | `string` | ISO 8601 timestamp of when the value was taken |

Each message includes a payload field matching its `type`: `heartRate`, `batteryLevel` or `ingestionPause`. In most cases a message carries a single value, but it may carry several values at a time, so read the fields you need and ignore the rest.

**`heart_rate`**

```json
{
  "type": "heart_rate",
  "timestamp": "2026-10-17T12:00:00.123Z",
  "heartRate": {
    "bpm": 85
  }
}
```

| Field           | Type      | Description                    |
| --------------- | --------- | ------------------------------ |
| `heartRate.bpm` | `integer` | Heart rate in beats per minute |

**`battery_level`**

The battery level of the device that measures the heart rate, that is the user's heart rate monitor or watch. It is not the battery of the phone or computer running the Pulsoid app.

```json
{
  "type": "battery_level",
  "timestamp": "2026-10-17T12:00:00.123Z",
  "batteryLevel": {
    "percent": 67
  }
}
```

| Field                  | Type      | Description                                          |
| ---------------------- | --------- | ---------------------------------------------------- |
| `batteryLevel.percent` | `integer` | Battery level of the measuring device, from 0 to 100 |

{% hint style="warning" %}
Battery level is reported by the latest versions of the Pulsoid desktop, Android, iOS, and watchOS apps. It is not available yet in the Wear OS app, where support is pending review. Users of the Wear OS app or older app versions do not produce `battery_level` messages.
{% endhint %}

**`ingestion_pause`**

Sent when Pulsoid pauses accepting the user's data. Until `ends_at`, no `heart_rate` or `battery_level` messages are delivered. There is no separate message when the pause ends, data simply starts flowing again.

If a pause is active when you connect, the message is sent right after the connection is established. If a new pause starts before the current one ends, you receive another `ingestion_pause` message and its `ends_at` applies.

```json
{
  "type": "ingestion_pause",
  "timestamp": "2026-10-17T12:00:00.123Z",
  "ingestionPause": {
    "id": "3f6b1c2e-8d4a-4f7e-9b1a-2c5d6e7f8a9b",
    "started_at": "2026-10-17T12:00:00.123Z",
    "ends_at": "2026-10-17T12:05:00Z"
  }
}
```

| Field                       | Type     | Description                                  |
| --------------------------- | -------- | -------------------------------------------- |
| `ingestionPause.id`         | `string` | Unique identifier of the pause               |
| `ingestionPause.started_at` | `string` | ISO 8601 timestamp of when the pause started |
| `ingestionPause.ends_at`    | `string` | ISO 8601 timestamp of when the pause ends    |

***

#### JavaScript Example

```javascript
const types = ["heart_rate", "battery_level", "ingestion_pause"].join(",");
const ws = new WebSocket(
  `wss://dev.pulsoid.net/api/v2/data/real_time?access_token=YOUR_TOKEN&types=${types}`
);

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.heartRate) {
    console.log(`${message.heartRate.bpm} BPM`);
  }
  if (message.batteryLevel) {
    console.log(`Device battery: ${message.batteryLevel.percent}%`);
  }
  if (message.ingestionPause) {
    console.log(`Paused until ${message.ingestionPause.ends_at}`);
  }
};
```
