> ## 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 Sleep Totals

> Returns the count, naps, time asleep, time in bed and mean efficiency of the sessions.

The same filters as the sleep list, so it adds up exactly what that would page through.

Added up in the database, so it covers every matching session however many
there are, without paging through them.



## OpenAPI

````yaml /openapi.json get /api/v1/users/{user_id}/events/sleep/totals
openapi: 3.1.0
info:
  title: Open Wearables API
  version: 1.0.0
servers: []
security: []
paths:
  /api/v1/users/{user_id}/events/sleep/totals:
    get:
      tags:
        - 'External: Events'
      summary: Get Sleep Totals
      description: >-
        Returns the count, naps, time asleep, time in bed and mean efficiency of
        the sessions.


        The same filters as the sleep list, so it adds up exactly what that
        would page through.


        Added up in the database, so it covers every matching session however
        many

        there are, without paging through them.
      operationId: get_sleep_totals_api_v1_users__user_id__events_sleep_totals_get
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
        - name: start_date
          in: query
          required: true
          schema:
            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 cover the whole day, so a date-only range includes
              both boundary days.
            examples:
              - '2023-11-07T05:31:56Z'
              - '2023-11-07'
            format: date-time
            title: Start Date
          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
            cover the whole day, so a date-only range includes both boundary
            days.
        - name: end_date
          in: query
          required: true
          schema:
            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 cover the whole day, so a date-only range includes
              both boundary days.
            examples:
              - '2023-11-07T05:31:56Z'
              - '2023-11-07'
            format: date-time
            title: End Date
          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
            cover the whole day, so a date-only range includes both boundary
            days.
        - name: provider
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/ProviderName'
              - type: 'null'
            title: Provider
        - name: source
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Source
        - name: device_model
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Device Model
        - name: data_source_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Data Source Id
        - name: is_nap
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: >-
              When true, return only naps; when false, only main sleep. Omit to
              return both.
            title: Is Nap
          description: >-
            When true, return only naps; when false, only main sleep. Omit to
            return both.
        - name: source_selection
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - all
                  - per_session
                type: string
              - type: 'null'
            description: >-
              `all` returns every source's sessions. `per_session` drops a
              session when the sessions of one source ranked higher by provider,
              then device type priority, cover at least
              `SESSION_DUPLICATE_OVERLAP` of it (default 0.5); sessions nothing
              better covers stay, and equally ranked sources never hide each
              other. Source filters narrow which sessions compete. Defaults to
              `all`.
            title: Source Selection
          description: >-
            `all` returns every source's sessions. `per_session` drops a session
            when the sessions of one source ranked higher by provider, then
            device type priority, cover at least `SESSION_DUPLICATE_OVERLAP` of
            it (default 0.5); sessions nothing better covers stay, and equally
            ranked sources never hide each other. Source filters narrow which
            sessions compete. Defaults to `all`.
        - name: filter_by_priority
          in: query
          required: false
          schema:
            type: boolean
            description: Same as source_selection=per_session.
            deprecated: true
            default: false
            title: Filter By Priority
          description: Same as source_selection=per_session.
          deprecated: true
        - 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/SleepTotals'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        4XX:
          description: Client error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        5XX:
          description: Server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - OAuth2PasswordBearer: []
components:
  schemas:
    ProviderName:
      type: string
      enum:
        - apple
        - samsung
        - garmin
        - health_connect
        - google_health
        - polar
        - suunto
        - whoop
        - strava
        - oura
        - fitbit
        - ultrahuman
        - sensorbio
        - withings
        - unknown
        - internal
      title: ProviderName
      description: Supported data providers.
    SleepTotals:
      properties:
        count:
          type: integer
          title: Count
          description: Sessions that match the filters, naps included
          example: 30
        naps:
          type: integer
          title: Naps
          description: Of those, how many are naps
          example: 4
        sleep_duration_seconds:
          type: integer
          title: Sleep Duration Seconds
          description: Sum of time asleep
          example: 799200
        time_in_bed_seconds:
          type: integer
          title: Time In Bed Seconds
          description: Sum of time in bed, or of the session's span where none was reported
          example: 871200
        avg_efficiency_percent:
          anyOf:
            - type: number
            - type: 'null'
          title: Avg Efficiency Percent
          description: Mean efficiency over the sessions that report one
          example: 91.4
      type: object
      required:
        - count
        - naps
        - sleep_duration_seconds
        - time_in_bed_seconds
      title: SleepTotals
      description: >-
        Sleep sessions matching a filter, added up in the database rather than
        paged.
    ValidationProblem:
      description: A 422 for a request that failed validation, listing every failure.
      examples:
        - code: VALIDATION_ERROR
          detail: >-
            body.email: value is not a valid email address: An email address
            must have an @-sign. (and 1 more)
          errors:
            - loc:
                - body
                - email
              msg: >-
                value is not a valid email address: An email address must have
                an @-sign.
              type: value_error
            - loc:
                - body
                - first_name
              msg: String should have at most 100 characters
              type: string_too_long
          status: 422
          title: Unprocessable Content
      properties:
        title:
          description: HTTP status phrase
          title: Title
          type: string
        status:
          description: HTTP status code, the same as the response's
          title: Status
          type: integer
        detail:
          description: Human-readable explanation of this occurrence
          title: Detail
          type: string
        code:
          description: Machine-readable error code, stable across releases
          title: Code
          type: string
        errors:
          description: Every validation failure in the request
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
          title: Errors
          type: array
      required:
        - title
        - status
        - detail
        - code
        - errors
      title: ValidationProblem
      type: object
    Problem:
      description: >-
        An error response: RFC 9457 Problem Details, served as
        ``application/problem+json``.


        ``type`` is omitted, which per the RFC means ``about:blank``: ``title``
        is the status

        phrase, and ``code`` tells errors with the same status apart.
      examples:
        - code: NOT_FOUND
          detail: 'User with ID: 123e4567-e89b-12d3-a456-426614174000 not found.'
          status: 404
          title: Not Found
      properties:
        title:
          description: HTTP status phrase
          title: Title
          type: string
        status:
          description: HTTP status code, the same as the response's
          title: Status
          type: integer
        detail:
          description: Human-readable explanation of this occurrence
          title: Detail
          type: string
        code:
          description: Machine-readable error code, stable across releases
          title: Code
          type: string
      required:
        - title
        - status
        - detail
        - code
      title: Problem
      type: object
    ValidationErrorItem:
      properties:
        loc:
          description: Where the invalid value is, e.g. ['body', 'email']
          items:
            anyOf:
              - type: string
              - type: integer
          title: Loc
          type: array
        msg:
          description: What is wrong with it
          title: Msg
          type: string
        type:
          description: Pydantic error type, e.g. 'missing'
          title: Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationErrorItem
      type: object
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/login

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.