Live Sync Status (SSE)

Overview

The sync status API lets you observe the entire lifecycle of every sync that runs for a user — across pulls, webhooks, SDK uploads, Apple Health XML imports, and historical Garmin backfills — in real time. Three endpoints are exposed:

GET /api/v1/users/{user_id}/sync/stream — long-lived Server-Sent Events connection that streams every event as it happens.
GET /api/v1/users/{user_id}/sync/recent — the last N events buffered in Redis (default 50, max 200, retained for 24 hours).
GET /api/v1/users/{user_id}/sync/runs — the latest event per run (one row per run_id), so you can quickly inspect which syncs are in progress and how recent ones ended.

All three accept the same ApiKeyDep authentication as the rest of the public API: pass your API key via the X-API-Key header.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.openwearables.io/api/v1/users/USER_ID/sync/stream"

HTTP status codes (all three endpoints)

Code	Meaning
`200`	Success
`401`	Missing or invalid API key
`404`	User not found
`422`	Validation error (invalid parameter value)
`500`	Internal server error

Error response shape

{ "detail": "User not found" }

The SSE endpoint also supports webhooks — if you have outgoing webhook endpoints registered, terminal sync events (sync.completed, sync.failed, sync.cancelled) are also dispatched as Svix webhooks. See the Webhooks guide.

Event Schema

Every event is a JSON object emitted as the data field of an SSE message with event: sync.status:

{
  "event_id": "evt_01HZ...",
  "run_id": "pull_garmin_user42_1730000000",
  "user_id": "user42",
  "provider": "garmin",
  "source": "pull",
  "stage": "fetching",
  "status": "in_progress",
  "message": "Fetching workouts",
  "progress": 0.42,
  "items_processed": 21,
  "items_total": 50,
  "error": null,
  "metadata": {},
  "started_at": "2024-10-27T10:15:00Z",
  "ended_at": null,
  "timestamp": "2024-10-27T10:15:32Z"
}

Fields

Field	Type	Description
`run_id`	`string`	Unique identifier per sync run. Multiple events share a `run_id` as a sync progresses.
`provider`	`string`	Lower-case provider slug (e.g. `garmin`, `oura`, `apple`).
`source`	`SyncSource`	One of `pull`, `webhook`, `sdk`, `backfill`, `xml_import`.
`stage`	`SyncStage`	One of `queued`, `started`, `fetching`, `processing`, `saving`, `completed`, `failed`, `cancelled`.
`status`	`SyncStatus`	One of `in_progress`, `success`, `partial`, `failed`, `cancelled`. Terminal statuses end a run.
`progress`	`number \| null`	Optional 0..1 fraction. Not all syncs report this.
`items_processed`	`number \| null`	Optional count of items processed so far.
`items_total`	`number \| null`	Optional total when known.
`started_at`	`string \| null`	ISO-8601 timestamp when the run started.
`ended_at`	`string \| null`	ISO-8601 timestamp when the run reached a terminal status.
`timestamp`	`string`	ISO-8601 timestamp of this individual event.

Streaming endpoint

curl -N "https://api.openwearables.io/api/v1/users/USER_ID/sync/stream?replay=20" \
  -H "X-API-Key: YOUR_API_KEY"

Path parameters

Parameter	Type	Required	Description
`user_id`	`string (UUID)`	Required	The user whose sync events to stream.

Query parameters

Parameter	Type	Default	Range	Description
`replay`	`integer`	`20`	`1..200`	Number of recent events to replay before the live stream begins. Allows a freshly connected client to catch up on in-progress syncs.

The replay parameter causes the most recent events from the last 24 hours to be replayed before the live stream begins, so a freshly connected client can see in-progress syncs immediately. The stream emits:

A connect comment (: connected) when the connection is established.
One SSE message per event (event: sync.status, data: <json>).
A : heartbeat comment every 15 seconds to keep the connection alive.

Browsers can consume the stream using EventSource (without auth headers) or fetch + ReadableStream (with a Bearer JWT token in the Authorization header). Both authentication methods are accepted by the same endpoint — no separate dashboard variant is needed. Example SSE stream output

: connected

event: sync.status
data: {"event_id":"evt_01HZ...","run_id":"pull_garmin_user42_1730000000","provider":"garmin","stage":"fetching","status":"in_progress","progress":0.42,...}

: heartbeat

event: sync.status
data: {"event_id":"evt_01HZ...","run_id":"pull_garmin_user42_1730000000","provider":"garmin","stage":"completed","status":"success","progress":1.0,"ended_at":"2024-10-27T10:16:45Z",...}

Error responses

HTTP/1.1 401 Unauthorized
{ "detail": "Invalid authentication credentials" }

HTTP/1.1 404 Not Found
{ "detail": "User not found" }

Example: Node.js

import { EventSource } from 'eventsource';

const url =
  'https://api.openwearables.io/api/v1/users/USER_ID/sync/stream?replay=20';
const es = new EventSource(url, {
  fetch: (input, init) =>
    fetch(input, { ...init, headers: { ...init.headers, 'X-API-Key': KEY } }),
});

es.addEventListener('sync.status', (msg) => {
  const event = JSON.parse(msg.data);
  console.log(`[${event.provider}] ${event.stage} - ${event.status}`);
});

Recent events

curl "https://api.openwearables.io/api/v1/users/USER_ID/sync/recent?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

Path parameters

Parameter	Type	Required	Description
`user_id`	`string (UUID)`	Required	The user whose events to return.

Query parameters

Parameter	Type	Default	Range	Description
`limit`	`integer`	`50`	`1..200`	Maximum number of events to return, ordered newest first.

Events are retained in Redis for 24 hours. Useful when reconnecting or rendering a “history” tab to seed the UI before opening the SSE stream. Success response — array of SyncStatusEvent objects, newest first.

[
  {
    "event_id": "evt_01HZ...",
    "run_id": "pull_garmin_user42_1730000000",
    "user_id": "user42",
    "provider": "garmin",
    "source": "pull",
    "stage": "completed",
    "status": "success",
    "message": null,
    "progress": 1.0,
    "items_processed": 42,
    "items_total": 42,
    "error": null,
    "metadata": {},
    "started_at": "2024-10-27T10:15:00Z",
    "ended_at": "2024-10-27T10:16:45Z",
    "timestamp": "2024-10-27T10:16:45Z"
  }
]

Sync run summaries

curl "https://api.openwearables.io/api/v1/users/USER_ID/sync/runs?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Path parameters

Parameter	Type	Required	Description
`user_id`	`string (UUID)`	Required	The user whose run summaries to return.

Query parameters

Parameter	Type	Default	Range	Description
`limit`	`integer`	`20`	`1..50`	Maximum number of run summaries to return.

Returns the latest event for each unique run_id from the past 24 hours (one row per run), ordered newest first. Each run_id is stable for the entire lifetime of a single sync invocation — multiple progress events share the same run_id and only the most recent one is surfaced here. For Garmin backfill, the run_id is unique per execution and incorporates an execution-scoped trace identifier. Success response — array of run summary objects:

[
  {
    "run_id": "pull_garmin_user42_1730000000",
    "user_id": "user42",
    "provider": "garmin",
    "source": "pull",
    "stage": "completed",
    "status": "success",
    "message": null,
    "progress": 1.0,
    "items_processed": 42,
    "items_total": 42,
    "error": null,
    "started_at": "2024-10-27T10:15:00Z",
    "ended_at": "2024-10-27T10:16:45Z",
    "last_update": "2024-10-27T10:16:45Z"
  },
  {
    "run_id": "garmin_backfill_user42_trace-abc123",
    "user_id": "user42",
    "provider": "garmin",
    "source": "backfill",
    "stage": "fetching",
    "status": "in_progress",
    "message": "Fetching activities window 3 of 12",
    "progress": 0.25,
    "items_processed": null,
    "items_total": null,
    "error": null,
    "started_at": "2024-10-27T09:00:00Z",
    "ended_at": null,
    "last_update": "2024-10-27T09:45:00Z"
  }
]

Rate limiting

The sync status endpoints share the global API rate limit. The SSE stream endpoint (/sync/stream) holds a single long-lived connection per client — there is no per-user connection cap, but you should maintain at most one open stream per user and reuse it rather than opening a new one on each page load. For polling-based fallbacks using /sync/recent or /sync/runs, a reasonable poll interval is 5–15 seconds. Polling faster than once per second provides no meaningful benefit since event latency is already sub-second via the SSE stream. Retry guidance If the SSE stream disconnects (network error, server restart, or a 5xx response), implement exponential back-off before reconnecting:

On first disconnect, reconnect after 1 second.
Double the interval on each subsequent failure (2 s, 4 s, 8 s…) up to a maximum of 30 seconds.
Pass replay=<N> on reconnect so you don’t miss events that arrived while offline.

Retention

All sync status data is held in Redis with a 24-hour TTL. For long-term audit, subscribe to the corresponding sync.started / sync.completed / sync.failed outgoing webhooks, which are persisted by Svix.

Overview

Integration Guides

Authentication

Users

Connections

Providers

Data Sync

Summaries

Timeseries

Events

Health Scores

Data Sources

Meta

Apple Health Import

Mobile SDK

Webhooks

Sync Status

Overview

Event Schema

Fields

Streaming endpoint

Example: Node.js

Recent events

Sync run summaries

Rate limiting

Retention

​Overview

​Event Schema

​Fields

​Streaming endpoint

​Example: Node.js

​Recent events

​Sync run summaries

​Rate limiting

​Retention

Overview

Event Schema

Fields

Streaming endpoint

Example: Node.js

Recent events

Sync run summaries

Rate limiting

Retention