Terra API Streaming Best Practices

Guidelines for building on the Terra API Streaming (Real-Time) API, which delivers live, roughly per-second metrics from wearables. This skill carries the architecture and the protocol gotchas inline; platform setup and the full consumer protocol live in references/.

From the terminal

Account configuration lives in the Terra dashboard, which an agent cannot click. The terra CLI does the same from a terminal. The streaming websocket surface itself has no CLI commands, and the CLI does not mint the short-lived token a streaming client authenticates with: that is minted by your backend, per session, through the flow this skill describes. What the CLI covers is the layer under that: the long-lived credential your backend holds in order to mint them, and whether the user being streamed for exists at all.

A stream that will not open is usually a credential without the right scope, a user id with no connection behind it, or a provider that was never enabled in this environment. All three are read-only checks, so run them before debugging the socket:

terra environments list --json dev_id,name
terra data-tokens list --env <dev-id> --json token_id,name,scopes,expires_at,last_used_at,revoked_at
terra users list --env <dev-id> --user-id <uuid> --json user_id,provider,active
terra unified-api sources list --env <dev-id>

data-tokens list answers the credential question without printing a secret: it shows which tokens exist, what each is scoped for, and whether one has expired or been revoked. Do not mint a token to find out whether a token works, and do not reach for terra environments api-key retrieve --reveal here: it prints the environment's API key and webhook signing secret, neither of which tells you anything about a socket, and in CI both land in the job log.