> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/streaming-api/getting-started.md).

# Overview

{% hint style="info" %}
The Terra Streaming API delivers real-time metrics on a roughly per-second basis:

* Heart rate
* Steps
* Distance covered
* and more

For longer-span data such as **workouts, sleep, daily totals & more**, use the [Unified API](/unified-api/getting-started.md) instead.
{% endhint %}

The **Streaming API** gives access to wearables that broadcast over BLE (Bluetooth Low Energy), ANT+, or certain custom Bluetooth protocols, as well as phone sensors:

* Heart rate straps (Polar H10, Garmin HRM Pro, Wahoo TICKR FIT...)
* Certain smartwatches (Apple Watch, [Garmin Fenix 6 & up](https://support.garmin.com/en-US/?faq=Zj1947s6pqAHzBCAhLhrC9), Xiaomi Mi Band 5 & 6...)
* and more

<div data-full-width="true"><figure><img src="https://files.readme.io/51e8eaf-image.png" alt="" width="563"><figcaption><p>Data flow diagram for data streaming</p></figcaption></figure></div>

***

## How it works

Real-time streaming has **four parts**:

1. **Wearable device** — the heart-rate strap, watch, or sensor, broadcasting over BLE or ANT+.
2. **Producer** — your mobile app, running a Terra Real-Time (RT) SDK, which receives the wearable's data and forwards it to Terra.
3. **Terra WebSocket broker** — Terra's server, which routes the live stream. This is Terra's infrastructure; you don't run it.
4. **Consumer** — your backend, which connects to Terra and receives the stream.

You set up the **three connections** between them:

1. **Wearable → app:** the user pairs their wearable to your app over Bluetooth/ANT+ using a Terra RT SDK.
2. **App → Terra:** your app opens a *producer* connection to Terra's WebSocket and forwards the wearable's data.
3. **Terra → backend:** your backend opens a *consumer* connection to Terra's WebSocket and receives the data in real time.

***

## Before you begin

* **Get your credentials.** Grab your **Dev ID** and **API key** from the [Terra dashboard](https://dashboard.tryterra.co). Your backend uses these to generate the short-lived tokens each WebSocket connection needs — a *producer* token for your app and a *developer* token for your consumer.
* **Know your user IDs.** When your app connects a user with the RT SDK, you identify them by your own `reference_id`. Terra creates a Terra `user_id` for that user (no separate auth widget needed) — and that `user_id` is what your token endpoints take and what you'll see as the `uid` field on every streamed payload.

***

## Test without a wearable

You don't need physical hardware to build and verify your integration. From the **Streaming** page of the [Terra dashboard](https://dashboard.tryterra.co/dashboard/streaming), create a **test user** and Terra streams synthetic data (heart rate, steps, and more) through the live API — so you can stand up and validate your backend consumer end to end before connecting a real device.

***

## Next steps

Work through the three connections in order:

1. [**Wearable → Your app**](/streaming-api/connect-wearable-to-sdk.md) — pair a wearable to your mobile app with an RT SDK.
2. [**Your app → Terra**](/streaming-api/your-app-greater-than-terra.md) — stream the wearable's data from your app to Terra.
3. [**Terra → Your backend**](/streaming-api/terra-greater-than-your-backend.md) — consume the live stream on your backend.

Only building the backend consumer (e.g. you already have a producer, or you're testing with a synthetic test user)? Start with [**Terra → Your backend**](/streaming-api/terra-greater-than-your-backend.md), which documents the full WebSocket protocol — opcodes, payload shapes, and close codes.