> ## Documentation Index
> Fetch the complete documentation index at: https://openwearables.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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



## OpenAPI

````yaml https://api.openwearables.io/openapi.json get /api/v1/users/{user_id}/summaries/data/timeline
openapi: 3.1.0
info:
  title: Open Wearables API
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/users/{user_id}/summaries/data/timeline:
    get:
      tags:
        - 'External: Summaries'
      summary: Get Data Timeline
      description: >-
        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.
      operationId: get_data_timeline_api_v1_users__user_id__summaries_data_timeline_get
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                description: >-
                  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 normalized to midnight UTC.
                examples:
                  - '2023-11-07T05:31:56Z'
                  - '2023-11-07'
                format: date-time
              - type: 'null'
            title: Start Date
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                description: >-
                  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 normalized to midnight UTC.
                examples:
                  - '2023-11-07T05:31:56Z'
                  - '2023-11-07'
                format: date-time
              - type: 'null'
            title: End Date
        - name: bucket
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TimelineBucket'
            description: Bucket width.
            default: day
          description: Bucket width.
        - name: group_by
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TimelineGroupBy'
            description: What each series counts.
            default: provider
          description: What each series counts.
        - name: X-Open-Wearables-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Open-Wearables-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDataTimelineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
components:
  schemas:
    TimelineBucket:
      type: string
      enum:
        - day
        - week
      title: TimelineBucket
      description: Width of one bucket in a per-user data timeline.
    TimelineGroupBy:
      type: string
      enum:
        - provider
        - series_type
      title: TimelineGroupBy
      description: What a timeline series is keyed by.
    UserDataTimelineResponse:
      properties:
        bucket:
          $ref: '#/components/schemas/TimelineBucket'
        group_by:
          $ref: '#/components/schemas/TimelineGroupBy'
        series:
          items:
            $ref: '#/components/schemas/TimelineSeries'
          type: array
          title: Series
      type: object
      required:
        - bucket
        - group_by
      title: UserDataTimelineResponse
      description: >-
        Per-user data density over time. Sparse: buckets with no data are
        omitted.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TimelineSeries:
      properties:
        key:
          type: string
          title: Key
        metric:
          $ref: '#/components/schemas/TimelineMetric'
          default: data_points
        buckets:
          items:
            prefixItems:
              - type: string
                format: date
              - type: integer
            type: array
            maxItems: 2
            minItems: 2
          type: array
          title: Buckets
          description: '``[bucket_start, count]`` pairs, chronological'
      type: object
      required:
        - key
        - buckets
      title: TimelineSeries
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    TimelineMetric:
      type: string
      enum:
        - data_points
      title: TimelineMetric
      description: >-
        What a series counts. Event records (workouts, sleep) join as their own
        metric.
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/login

````