Sleep Endpoint

polar_flow.endpoints.sleep.SleepEndpoint

Sleep data endpoint handler.

This class provides methods for accessing sleep tracking data from the Polar AccessLink API. Sleep data is non-transactional and can be retrieved multiple times.

get(user_id, date) async

Get sleep data for a specific date.

Parameters:

Name	Type	Description	Default
user_id	str	Polar user ID	required
date	str | date	Date in YYYY-MM-DD format or date object (the day user woke up)	required

Returns:

Type	Description
SleepData	Sleep data for the specified date

Raises:

Type	Description
NotFoundError	If no sleep data exists for the date
AuthenticationError	If access token is invalid
ValidationError	If date format is invalid

Example

async with PolarFlow(access_token="token") as client:
    sleep = await client.sleep.get(user_id="123", date="2026-01-09")
    print(f"Sleep score: {sleep.sleep_score}/100")
    print(f"Total sleep: {sleep.total_sleep_hours} hours")

list(user_id=None, *, days=None, since=None, end_date=None) async

Get sleep data for multiple days.

Parameters:

Name	Type	Description	Default
user_id	str | None	(Deprecated) Polar user ID - not needed, API uses token	None
days	int | None	Number of days to fetch (1-30). Defaults to 7.	None
since	str | None	Fetch data since this date (YYYY-MM-DD). Alternative to days.	None
end_date	str | date | None	End date (inclusive). Defaults to today.	None

Returns:

Type	Description
list[SleepData]	List of sleep data, ordered by date (most recent first)

Raises:

Type	Description
ValueError	If both days and since specified, or if since is invalid
AuthenticationError	If access token is invalid

Example

async with PolarFlow(access_token="token") as client:
    # Get last 7 days of sleep
    sleep_list = await client.sleep.list(days=7)

    # Get sleep since specific date
    sleep_list = await client.sleep.list(since="2026-01-01")

    for sleep in sleep_list:
        print(f"{sleep.date}: {sleep.sleep_score}/100")