> 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, listed in [Data types](/streaming-api/data-types.md)

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 is a **paid add-on** to your Terra plan. See [Pricing](/streaming-api/pricing.md) for the $99/month add-on and how credits are measured.

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). 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

1. Open the SDK page for your platform: [iOS](/streaming-api/ios-swift.md), [Android](/streaming-api/android.md), [React Native](/streaming-api/react-native.md), or [Flutter](/streaming-api/flutter.md). Each page covers the first two connections: connect a wearable to your app, then stream its data to Terra.
2. Set up a [backend consumer](/streaming-api/terra-greater-than-your-backend.md) to receive the live stream.

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

{% hint style="success" %}
**Prefer to read working code?** [**Terra Grip**](https://docs.tryterra.co/developer-tools/example-apps/terra-grip) is a React Native reference app that implements the producer path end to end with the `terra-rt` SDK, covering pairing, tokens, and live streaming. [**Terra Pulse**](https://docs.tryterra.co/developer-tools/example-apps/terra-pulse) implements the consumer path: a React web app that opens a WebSocket to Terra and renders the stream live. Clone either, run it, and copy the parts you need.
{% endhint %}

{% hint style="info" %}
**Building with an AI coding assistant?** The `terra-streaming` [agent skill](https://docs.tryterra.co/developer-tools/agent-skills) gives your assistant the streaming architecture, the websocket protocol, and the platform gotchas up front, so it writes against the real contract instead of guessing.

```bash
npx skills add tryterra/agent-skills --skill terra-streaming
```

{% endhint %}
