---
title: "Return sleep cycles aggregated by a specified period."
method: GET
path: "/data/v0/{fulcra_userid}/sleep_agg"
tags: ["data", "sleep"]
---

# Return sleep cycles aggregated by a specified period.

`GET /data/v0/{fulcra_userid}/sleep_agg`

## Request

- Base URL: `https://api.fulcradynamics.com`
- URL: `https://api.fulcradynamics.com/data/v0/{fulcra_userid}/sleep_agg`
- Auth: HTTP bearer

Process raw sleep data samples aggregated sleep stage durations per period.

## Path parameters

- `fulcra_userid` string, uuid, required

## Query parameters

- `start_time` string, date-time, required: The starting timestamp in ISO8601 format (inclusive)
- `end_time` string, date-time, required: The ending timestamp in ISO8601 format (exclusive)
- `output` 'ndjson' | 'jstable' | 'jscolumns' | 'arrow' | 'arrowraw' | 'parquet' | 'csv' | 'quotecsv', required
- `cycle_gap` string, duration: Minimum time interval separating distinct cycles.
- `stages` integer[], nullable: Sleep stages to include. Defaults to all stages.
- `gap_stages` integer[], nullable: Sleep stages to consider as gaps in sleep cycles.
- `clip_to_range` boolean: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
- `mode` 'start' | 'end' | 'split'
- `period` string: The period start and interval represented with the polars string language (see https://docs.pola.rs/api/python/dev/reference/expressions/api/polars.Expr.dt.truncate.html).
- `agg_functions` AggregateFunction[]: Aggregations to return.
- `tz` string: IANA time zone to return results in

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fulcradynamics/apis/fulcra-life-api.md) · [All operations](https://skmtc.dev/fulcradynamics/apis/fulcra-life-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fulcradynamics/apis/fulcra-life-api/revisions/d85136fc304a?raw)