Oura Sleep Periods
oura_list_sleepRead-onlyIdempotent
Retrieve Oura sleep period records with sleep stages and timing. Filter by date range to analyze sleep patterns and duration.
Instructions
List detailed Oura sleep period records, including sleep stages and timing where available. Requires the daily scope (Oura has no separate sleep OAuth scope). Not medical advice.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Only return Oura records after this time. Converted to an Oura start_date. | |
| limit | No | Maximum number of records returned by this call, kept from the OLDEST end of the window. Oura v2 serves collections oldest-first, has no sort parameter and no page-size parameter, so limit=1 returns the OLDEST record in the window, never the newest. This domain has no latest-record shortcut resource (only daily readiness has one), so to reach the newest record here, narrow the window with after/before until the response comes back with truncated=false and has_more=false: records are oldest-first, so the LAST one is then the newest that exists in that window. The cap is applied locally after fetching and also stops cursor pagination once it is reached; when it dropped records, truncated is true and has_more is true. If truncated is true, raise limit or set all_pages — do not follow a cursor, because next_token is omitted whenever resuming would skip dropped records. | |
| before | No | Only return Oura records before this time. Converted to an Oura end_date. | |
| all_pages | No | When true, follow the Oura next_token cursor up to max_pages in this one call. Resume later by passing the returned next_token with the same after/before window. | |
| max_pages | No | Maximum upstream Oura pages to fetch in this call when all_pages is true. A runaway guard, not an Oura page index. | |
| next_token | No | Opaque Oura v2 cursor from a previous collection response. Pass it back unchanged with the same after/before window to resume. Oura has no integer page index and no page-size parameter; do not invent or increment a page number. | |
| privacy_mode | No | Optional per-call privacy override. Defaults to OURA_PRIVACY_MODE or structured. raw returns upstream Oura JSON. summary minimizes sensitive health and profile details. | |
| response_format | No | markdown | |
| explicit_user_intent | No | Required true when privacy_mode=raw (agent escalation of redaction). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | ||
| records | Yes | ||
| endpoint | Yes | ||
| has_more | Yes | True when more records exist beyond this response, either upstream (a resumable next_token) or because the limit cap dropped records (truncated). If truncated is true, raise limit or set all_pages; if next_token is present, pass it back. | |
| truncated | Yes | True when the limit cap dropped records that had already been fetched. Raise limit or set all_pages (or narrow after/before) to see them. next_token is omitted in this case so a resume cannot skip those rows. | |
| next_token | No | Opaque Oura v2 cursor to resume from. Pass this back as input next_token with the same after/before window. Present only when more records exist upstream AND this call did not locally drop fetched records (truncated is false). When truncated is true, next_token is omitted: raise limit or set all_pages instead of following a cursor, which would skip the dropped records. Never increment a page number. | |
| privacy_mode | Yes | ||
| pages_fetched | Yes |