For the complete documentation index, see llms.txt. This page is also available as Markdown.

Overview

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

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

  1. Open the SDK page for your platform: iOS, Android, React Native, or Flutter. 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 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, which documents the full WebSocket protocol: opcodes, payload shapes, and close codes.

Building with an AI coding assistant? The terra-streaming agent skill 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.

Last updated

Was this helpful?