Sign in
External: Summaries

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

get/api/v1/users/{user_id}/summaries/data/timeline

Path parameters

user_idstring uuid required

Query parameters

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

Example:2023-11-07T05:31:56Z
end_datestring 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.

Example:2023-11-07T05:31:56Z
bucket'day' | 'week'

Width of one bucket in a per-user data timeline.

Bucket width.

group_by'provider' | 'series_type' | 'workout_type'

What a timeline series is keyed by.

What each series counts.

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-Keystring nullable

Response

Successful Response

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.

Changes

Changed in 2 of the 17 revisions of this API.23

  • b628830d5f4722See the full diff
    • ●

      added the new workout_type enum value to the response property for the response status

      response-property-enum-value-added

    • ●

      added the new workouts enum value to the // response property for the response status

      response-property-enum-value-added

    • ○

      added the new optional query request parameter provider

      new-optional-request-parameter

    • ○

      added the new enum value workout_type to the query request parameter group_by

      request-parameter-enum-value-added

  • 4e61b8720ebb1See the full diff
    • ○

      endpoint added

      endpoint-added