Overview

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

The Streaming API is a paid add-on to your Terra plan — see Pricing & Access 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, Xiaomi Mi Band 5 & 6...)

• and more

Data flow diagram for data streaming

---

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. 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, 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 — pair a wearable to your mobile app with an RT SDK.

2. Your app → Terra — stream the wearable's data from your app to Terra.

3. Terra → Your backend — 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, which documents the full WebSocket protocol — opcodes, payload shapes, and close codes.