---
title: "Get Sleep Totals"
method: GET
path: "/api/v1/users/{user_id}/events/sleep/totals"
tags: ["External: Events"]
---

# Get Sleep Totals

`GET /api/v1/users/{user_id}/events/sleep/totals`

## Request

- Base URL: `https://api.openwearables.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openwearables.io/api/v1/users/{user_id}/events/sleep/totals`
- Auth: OAuth 2 (password, token URL `/api/v1/auth/login`)

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.

## Path parameters

- `user_id` string, uuid, required

## Query parameters

- `start_date` string, date-time, required: 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, required: 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.
- `provider` 'apple' | 'samsung' | 'garmin' | 'health_connect' | 'google_health' | 'polar' | 'suunto' | 'whoop' | 'strava' | 'oura' | 'fitbit' | 'ultrahuman' | 'sensorbio' | 'withings' | 'unknown' | 'internal': Supported data providers.
- `source` string, nullable
- `device_model` string, nullable
- `data_source_id` string, uuid, nullable
- `is_nap` boolean, nullable: When true, return only naps; when false, only main sleep. Omit to return both.
- `filter_by_priority` boolean: When true, keep only the highest-priority source's sessions per sleep date (provider/device priority, same ranking as summaries). Defaults to false for backwards compatibility.

## Headers

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

## Response `200`

Successful Response

- SleepTotals: Sleep sessions matching a filter, added up in the database rather than paged.
  - `count` integer, required: Sessions that match the filters, naps included
  - `naps` integer, required: Of those, how many are naps
  - `sleep_duration_seconds` integer, required: Sum of time asleep
  - `time_in_bed_seconds` integer, required: Sum of time in bed, or of the session's span where none was reported
  - `avg_efficiency_percent` number, nullable: Mean efficiency over the sessions that report one

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-05** `c4e4e974ed37`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openwearables/apis/open-wearables-api/changes/api/v1/users/:user_id/events/sleep/totals/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/c9016a165d04?raw)