---
title: "Get Data Timeline"
method: GET
path: "/api/v1/users/{user_id}/summaries/data/timeline"
tags: ["External: Summaries"]
---

# Get Data Timeline

`GET /api/v1/users/{user_id}/summaries/data/timeline`

Returns when a user has data, as counts per time bucket.

Buckets are truncated in UTC and only non-empty ones are returned, so the response is
sparse: the caller fills the gaps for the window it asked for. Counts cover both the
live and the archive table, so archived history does not read as missing data.

Optionally scope to a window via `start_date` / `end_date` (by `recorded_at`); omitting
both returns the user's whole history.

## Path parameters

- `user_id` string, uuid, required

## Query parameters

- `start_date` string, date-time, nullable — ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp in seconds. Date-only strings (e.g. `2023-11-07`) are also accepted and cover the whole day, so a date-only range includes both boundary days.
- `end_date` string, date-time, nullable — ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp in seconds. Date-only strings (e.g. `2023-11-07`) are also accepted and cover the whole day, so a date-only range includes both boundary days.
- `bucket` 'day' | 'week' — Width of one bucket in a per-user data timeline.
- `group_by` 'provider' | 'series_type' | 'workout_type' — What a timeline series is keyed by.
- `provider` 'apple' | 'samsung' | 'garmin' | 'health_connect' | 'google_health' | 'polar' | 'suunto' | 'whoop' | 'strava' | 'oura' | 'fitbit' | 'ultrahuman' | 'sensorbio' | 'withings' | 'unknown' | 'internal' — Supported data providers.

## Headers

- `X-Open-Wearables-API-Key` string, nullable

## Response `200`

Successful Response

- UserDataTimelineResponse — Per-user data density over time. Sparse: buckets with no data are omitted.
  - `bucket` 'day' | 'week', required — Width of one bucket in a per-user data timeline.
  - `group_by` 'provider' | 'series_type' | 'workout_type', required — What a timeline series is keyed by.
  - `series` TimelineSeries[]
    - `key` string, required
    - `metric` 'data_points' | 'workouts' — What a series counts. Event records (workouts, sleep) join as their own metric.
    - `buckets` array[], required — ``[bucket_start, count]`` pairs, chronological
      - unknown[]
        - unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-16** `b628830d5f47` — 2 warning, 2 info
  - added the new `workout_type` enum value to the `group_by` response property for the response status `200`
  - added the new `workouts` enum value to the `series/items/metric` response property for the response status `200`
  - added the new optional `query` request parameter `provider`
  - added the new enum value `workout_type` to the `query` request parameter `group_by`
- **2026-09-08** `4e61b8720ebb` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openwearables/apis/open-wearables-api/changes/api/v1/users/:user_id/summaries/data/timeline/get.md)

---

[API](https://skmtc.dev/openwearables/apis/open-wearables-api.md) · [All operations](https://skmtc.dev/openwearables/apis/open-wearables-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openwearables/apis/open-wearables-api/revisions/6962739bc168?raw)