Client class¶
Bases: _OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixin
SweatStack API client for accessing activities, traces, and user data.
The Client handles authentication, API requests, and data retrieval from SweatStack. You can initialize it with credentials or use authenticate()/login() for OAuth2.
Example
client = Client() client.authenticate() activities = client.get_activities(limit=10)
api_key
property
writable
¶
The current API access token.
Loads from instance, environment (SWEATSTACK_API_KEY), or persistent storage. Automatically refreshes expired tokens.
Returns:
| Type | Description |
|---|---|
SecretStr | None
|
SecretStr containing the access token, or None if not authenticated. |
Raises:
| Type | Description |
|---|---|
SweatStackTokenRefreshError
|
If the token is expired and refresh fails. |
client_secret
property
writable
¶
The OAuth client secret for confidential clients.
Returns a SecretStr to prevent accidental logging of the secret. Use .get_secret_value() to get the actual secret string.
jwt
property
writable
¶
Alias for api_key (backward compatibility).
refresh_token
property
writable
¶
The refresh token used for automatic token renewal.
Loads from instance, environment (SWEATSTACK_REFRESH_TOKEN), or persistent storage.
Returns a SecretStr to prevent accidental logging of the token. Use .get_secret_value() to get the actual token string.
url
property
writable
¶
This determines which SweatStack URL to use, allowing the use of a non-default instance.
This is useful for example during local development.
Please note that changing the url probably requires changing the OAUTH2_CLIENT_ID as well.
__init__(api_key=None, refresh_token=None, url=None, streamlit_compatible=False, client_id=None, client_secret=None, skip_token_expiry_check=False)
¶
Initialize a SweatStack client.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_key
|
str | SecretStr | None
|
Optional API access token. If not provided, will check environment or storage. |
None
|
refresh_token
|
str | SecretStr | None
|
Optional refresh token for automatic token renewal. |
None
|
url
|
str | None
|
Optional SweatStack instance URL. Defaults to production. |
None
|
streamlit_compatible
|
bool
|
Set to True when using in Streamlit apps. |
False
|
client_id
|
str | None
|
Optional OAuth client ID. Defaults to the public client ID. |
None
|
client_secret
|
str | SecretStr | None
|
Optional OAuth client secret for confidential clients. |
None
|
skip_token_expiry_check
|
bool
|
If True, skip JWT expiry validation and use the token as-is. Use this when token lifecycle is managed externally (e.g. by a proxy). |
False
|
authorize_team(team_id, scopes=None)
¶
Authorizes a team to access the current user's data.
When called as a delegated user, authorizes the team for that user.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
team_id
|
str
|
The team's ID. |
required |
scopes
|
list[Scope | str] | None
|
Scopes to grant. Defaults to |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
dict |
Confirmation with team_id, user_id, and granted scopes. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
create_test(*, sport, start, title=None, end=None, results=None, tags=None)
¶
Creates a new test.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sport
|
Sport | str
|
The sport for this test. Can be a Sport enum or string ID. |
required |
start
|
datetime
|
The start time of the test. |
required |
title
|
str | None
|
Optional title for the test. |
None
|
end
|
datetime | None
|
Optional end time. Defaults to start + 3 hours server-side. |
None
|
results
|
TestResults | None
|
Optional structured test results (thresholds, capacities, etc.). |
None
|
tags
|
list[str] | None
|
Optional list of tags to associate with this test. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
TestSummary |
TestSummary
|
The created test. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
create_trace(*, timestamp, lactate=None, rpe=None, notes=None, power=None, speed=None, heart_rate=None, tags=None, sport=None)
¶
Creates a new trace with the specified parameters.
This method creates a new trace entry with the given timestamp and optional measurement values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timestamp
|
datetime
|
The date and time when the trace was recorded. |
required |
lactate
|
float | None
|
Optional blood lactate concentration in mmol/L. |
None
|
rpe
|
int | None
|
Optional rating of perceived exertion (typically on a scale of 1-10). |
None
|
notes
|
str | None
|
Optional text notes associated with this trace. |
None
|
power
|
int | None
|
Optional power measurement in watts. |
None
|
speed
|
float | None
|
Optional speed measurement in meters per second. |
None
|
heart_rate
|
int | None
|
Optional heart rate measurement in beats per minute. |
None
|
tags
|
list[str] | None
|
Optional list of tags to associate with this trace. |
None
|
sport
|
Sport | str | None
|
Optional sport to associate with this trace. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
TraceDetails |
TraceDetails
|
The created trace object with all details. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
create_user(first_name, last_name=None)
¶
Creates a managed user.
Managed users have no login credentials — their data is controlled by the creating user via delegated tokens.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
first_name
|
str
|
The user's first name. |
required |
last_name
|
str | None
|
Optional last name. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
UserResponse |
UserResponse
|
The created user. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
delete_activity_app_metadata(activity_id)
¶
Deletes app metadata from an activity (requires app token).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The activity to remove metadata from. |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token. |
delete_daily(measure, *, date)
¶
Deletes a daily value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measure
|
DailyMeasure | str
|
The daily measure to delete. |
required |
date
|
date
|
The date of the entry to delete. |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
404 if entry does not exist. |
delete_test(test_id)
¶
Deletes a test.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
test_id
|
str
|
The unique identifier of the test to delete. |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
delete_test_app_metadata(test_id)
¶
Deletes app metadata from a test (requires app token).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
test_id
|
str
|
The test to remove metadata from. |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token. |
delete_trace(trace_id)
¶
Deletes a trace.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
trace_id
|
str
|
The unique identifier of the trace to delete. |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
delete_trace_app_metadata(trace_id)
¶
Deletes app metadata from a trace (requires app token).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
trace_id
|
str
|
The trace to remove metadata from. |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token. |
delete_user_app_metadata()
¶
Deletes app metadata from the authenticated user (requires app token).
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token. |
get_activities(*, start=None, end=None, sports=None, tags=None, limit=100, offset=0, as_dataframe=False)
¶
Gets a list of activities based on specified filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
date | None
|
Optional start date to filter activities. |
None
|
end
|
date | None
|
Optional end date to filter activities. |
None
|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter activities by. Can be Sport objects or string IDs. |
None
|
tags
|
list[str] | None
|
Optional list of tags to filter activities by. |
None
|
limit
|
int
|
Maximum number of activities to return. Defaults to 100. |
100
|
offset
|
int
|
Number of activities to skip. Defaults to 0. |
0
|
as_dataframe
|
bool
|
Whether to return results as a pandas DataFrame. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
list[ActivitySummary] | DataFrame
|
Either a list of ActivitySummary objects or a pandas DataFrame containing |
list[ActivitySummary] | DataFrame
|
the activities data, depending on the value of as_dataframe. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activity(activity_id)
¶
Gets details for a specific activity by ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The unique identifier of the activity to retrieve. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
ActivityDetails |
ActivityDetails
|
The activity details object containing all information about the activity. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activity_awd(activity_id, metric=None)
¶
Gets the accumulated work duration (AWD) for a specific activity.
This method retrieves accumulated work duration metrics for a specific activity. AWD represents the total duration spent at each intensity level by sorting activity data by intensity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The unique identifier of the activity. |
required |
metric
|
Literal[power, speed] | Literal['power', 'speed'] | None
|
Optional metric type. Defaults to power for cycling, speed for other sports. Can be either "power" or "speed". |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the AWD data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activity_data(activity_id, adaptive_sampling_on=None, metrics=None)
¶
Gets the raw data for a specific activity.
This method retrieves the time-series data for a given activity, with optional adaptive sampling to reduce data points for visualization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The unique identifier of the activity. |
required |
adaptive_sampling_on
|
Literal['power', 'speed'] | None
|
Optional parameter to apply adaptive sampling on either "power" or "speed" data. If None, no adaptive sampling is applied. |
None
|
metrics
|
list[Metric | str] | None
|
Optional list of metrics to include in the results. Can be a list of Metric enums or strings. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the activity's time-series data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activity_mean_max(activity_id, metric, adaptive_sampling=False)
¶
Gets the mean-max data for a specific activity.
This method retrieves the mean-max curve data for a given activity, which represents the maximum average value of a metric (power or speed) for different time durations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The unique identifier of the activity. |
required |
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate mean-max values for, either "power" or "speed". |
required |
adaptive_sampling
|
bool
|
Whether to apply adaptive sampling to reduce data points for visualization. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the mean-max curve data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_authorized_teams()
¶
Lists all teams the current user has authorized to access their data.
Returns:
| Type | Description |
|---|---|
list[AuthorizedTeamResponse]
|
list[AuthorizedTeamResponse]: Teams with their granted scopes. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_backfill_status()
¶
Gets the current backfill status from the activities backfill-status endpoint.
This method connects to the backfill status event stream and returns the first backfill_loaded_until timestamp received.
Returns:
| Name | Type | Description |
|---|---|---|
BackfillStatus |
BackfillStatus
|
A BackfillStatus object containing the current backfill status. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
ValueError
|
If no status message is received. |
get_dailies(measure, *, start, end, interpolate=True, as_dataframe=False)
¶
Gets daily values for a measure over a date range.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measure
|
DailyMeasure | str
|
The daily measure to retrieve (e.g. DailyMeasure.body_mass). |
required |
start
|
date
|
Start date (inclusive). |
required |
end
|
date
|
End date (inclusive). |
required |
interpolate
|
bool
|
Whether to apply server-side estimation/interpolation. Defaults to True. When False, missing dates return value=None with source="missing". |
True
|
as_dataframe
|
bool
|
Whether to return results as a pandas DataFrame. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
list[DailyResponse] | DataFrame
|
Either a list of DailyResponse objects or a pandas DataFrame with |
list[DailyResponse] | DataFrame
|
date as index. Always returns one entry per date in the range. |
get_latest_activity(*, start=None, end=None, sport=None, tag=None)
¶
Gets the most recent activity based on specified filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
date | None
|
Optional start date to filter activities. |
None
|
end
|
date | None
|
Optional end date to filter activities. |
None
|
sport
|
Sport | None
|
Optional sport to filter activities by. Can be a Sport object or string ID. |
None
|
tag
|
str | None
|
Optional tag to filter activities by. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
ActivityDetails |
ActivityDetails
|
The most recent activity matching the filters. |
Raises:
| Type | Description |
|---|---|
StopIteration
|
If no activities match the filters. |
HTTPStatusError
|
If the API request fails. |
get_latest_activity_data(sport=None, adaptive_sampling_on=None, metrics=None)
¶
Gets the data for the latest activity of a specific sport.
This method retrieves the time series data for the most recent activity of the specified sport. If no sport is specified, it returns data for the latest activity regardless of sport.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sport
|
Sport | str | None
|
Optional sport to filter by. Can be a Sport enum or string. |
None
|
adaptive_sampling_on
|
Literal['power', 'speed'] | None
|
Optional metric to apply adaptive sampling for visualization. Can be either "power" or "speed". Defaults to None. |
None
|
metrics
|
list[Metric | str] | None
|
Optional list of metrics to include in the results. Can be a list of Metric enums or strings. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the activity data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_latest_activity_mean_max(metric, sport=None, adaptive_sampling=False)
¶
Gets the mean-max curve for the latest activity of a specific sport.
This method retrieves the mean-max curve data for the most recent activity of the specified sport. If no sport is specified, it returns data for the latest activity regardless of sport.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate the mean-max curve for. Can be either "power" or "speed". |
required |
sport
|
Sport | str | None
|
Optional sport to filter by. Can be a Sport enum or string. |
None
|
adaptive_sampling
|
bool
|
Whether to apply adaptive sampling to the mean-max curve data. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the mean-max curve data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_longitudinal_awd(*, sports=None, sport=None, metric, start=None, end=None, date=None, window_days=None)
¶
Gets the longitudinal accumulated work duration (AWD) for one or more sports.
This method retrieves AWD values across four intensity levels: max (highest daily AWD), hard, medium, and easy (sustainable durations for respective workout intensities).
Note: This endpoint is in development and subject to change.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sports
|
list[Sport | str] | None
|
List of sports to get AWD data for. Can be Sport enums or strings. |
None
|
sport
|
Sport | str | None
|
Deprecated. Use |
None
|
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate AWD for. Must be either "power" or "speed". |
required |
start
|
date | str | None
|
Start of the date range. |
None
|
end
|
date | str | None
|
End of the date range (defaults to today). |
None
|
date
|
date | str | None
|
Deprecated since 0.70.0. Use |
None
|
window_days
|
int | None
|
Deprecated since 0.70.0. Use |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the longitudinal AWD data with intensity levels. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If both |
HTTPStatusError
|
If the API request fails. |
get_longitudinal_data(*, sports=None, sport=None, start, end=None, metrics=None, adaptive_sampling_on=None)
¶
Gets longitudinal data for activities within a specified date range.
This method retrieves aggregated data for activities that match the specified criteria, including sport type and date range. The data is returned as a pandas DataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter by. Can be a list of Sport enums or strings. |
None
|
sport
|
Sport | str | None
|
Deprecated. Use |
None
|
start
|
date | str
|
The start date for the data range. Can be a date object or string in ISO format. |
required |
end
|
date | str | None
|
Optional end date for the data range. Can be a date object or string in ISO format. |
None
|
metrics
|
list[Metric | str] | None
|
Optional list of metrics to include in the results. Can be a list of Metric enums or strings. |
None
|
adaptive_sampling_on
|
Literal[power, speed] | Literal['power', 'speed'] | None
|
Optional metric to apply adaptive sampling for visualization. Can be either "power" or "speed". Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the longitudinal activity data. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If both 'sport' and 'sports' parameters are provided. |
HTTPStatusError
|
If the API request fails. |
get_longitudinal_mean_max(*, sports=None, sport=None, metric, start=None, end=None, date=None, window_days=None)
¶
Gets the mean-max curve for one or more sports and a metric.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sports
|
list[Sport | str] | None
|
List of sports to get mean-max data for. Can be Sport enums or strings. |
None
|
sport
|
Sport | str | None
|
Deprecated. Use |
None
|
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate mean-max for. Must be either "power" or "speed". |
required |
start
|
date | str | None
|
Start of the date range. |
None
|
end
|
date | str | None
|
End of the date range (defaults to today). |
None
|
date
|
date | str | None
|
Deprecated since 0.70.0. Use |
None
|
window_days
|
int | None
|
Deprecated since 0.70.0. Use |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the mean-max curve data. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If both |
HTTPStatusError
|
If the API request fails. |
get_sports(only_root=False)
¶
Gets a list of available sports.
This method retrieves all sports available to the user, with an option to only return root sports (top-level sports without parents).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
only_root
|
bool
|
If True, only returns root sports without parents. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
list[Sport]
|
list[Sport]: A list of Sport objects representing the available sports. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_tags()
¶
Gets a list of all tags used by the user.
This method retrieves all tags that the user has created or used across their activities and traces.
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: A list of tag strings. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_team_user(*, team_id, user, search_mode='auto')
¶
Get a team-authorized user by ID or name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
team_id
|
str
|
The team's ID. |
required |
user
|
str
|
User ID or (part of) display name. |
required |
search_mode
|
Literal['auto', 'id', 'name']
|
"auto" (detect), "id", or "name". |
'auto'
|
Returns:
| Name | Type | Description |
|---|---|---|
UserSummary |
UserSummary
|
The matching user. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no match or multiple matches found. |
HTTPStatusError
|
If the API request fails. |
get_team_users(team_id)
¶
Lists all users who have authorized a team to access their data.
Only accessible to members of the team.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
team_id
|
str
|
The team's ID. |
required |
Returns:
| Type | Description |
|---|---|
list[UserSummary]
|
list[UserSummary]: Users who have authorized the team, with their granted scopes. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_teams()
¶
Lists all teams the current user owns or is a member of.
Returns:
| Type | Description |
|---|---|
list[TeamResponse]
|
list[TeamResponse]: Teams with the user's role (owner or member). |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_test(test_id)
¶
Gets details for a specific test by ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
test_id
|
str
|
The unique identifier of the test to retrieve. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
TestDetails |
TestDetails
|
The test details including resolved traces and overlapping activities. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_tests(*, start=None, end=None, sports=None, tags=None, created_by=None, limit=50, offset=0, as_dataframe=False)
¶
Gets a list of tests based on specified filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
date | None
|
Optional start date to filter tests. |
None
|
end
|
date | None
|
Optional end date to filter tests. |
None
|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter tests by. Can be Sport objects or string IDs. |
None
|
tags
|
list[str] | None
|
Optional list of tags to filter tests by. |
None
|
created_by
|
str | None
|
Optional app ID to filter tests by creator. |
None
|
limit
|
int
|
Maximum number of tests to return. Defaults to 50. |
50
|
offset
|
int
|
Number of tests to skip. Defaults to 0. |
0
|
as_dataframe
|
bool
|
Whether to return results as a pandas DataFrame. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
list[TestSummary] | DataFrame
|
Either a list of TestSummary objects or a pandas DataFrame containing |
list[TestSummary] | DataFrame
|
the tests data, depending on the value of as_dataframe. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_traces(*, start=None, end=None, sports=None, tags=None, limit=100, offset=0, as_dataframe=False)
¶
Gets a list of traces based on specified filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
date | None
|
Optional start date to filter traces. |
None
|
end
|
date | None
|
Optional end date to filter traces. |
None
|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter traces by. Can be Sport objects or string IDs. |
None
|
tags
|
list[str] | None
|
Optional list of tags to filter traces by. |
None
|
limit
|
int
|
Maximum number of traces to return. Defaults to 100. |
100
|
offset
|
int
|
Number of traces to skip. Defaults to 0. |
0
|
as_dataframe
|
bool
|
Whether to return results as a pandas DataFrame. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
list[TraceDetails] | DataFrame
|
Either a list of TraceDetails objects or a pandas DataFrame containing |
list[TraceDetails] | DataFrame
|
the traces data, depending on the value of as_dataframe. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_userinfo()
¶
Gets detailed information about the current user.
This method retrieves comprehensive information about the user currently authenticated with the client.
Returns:
| Name | Type | Description |
|---|---|---|
UserInfoResponse |
UserInfoResponse
|
A UserInfoResponse object containing detailed user information including profile data, permissions, and authentication details. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_users()
¶
Gets a list of all users accessible to the current user.
This method retrieves all users that the current user has access to view. For regular users, this typically returns only their own user information. For admin users, this may return information about multiple users. This method will always authenticate as the principal user.
Returns:
| Type | Description |
|---|---|
list[UserSummary]
|
list[UserSummary]: A list of UserSummary objects containing basic user information. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
set_activity_app_metadata(activity_id, *, data)
¶
Sets app metadata on an activity (requires app token).
Replaces the entire metadata dict for this app on the given activity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The activity to attach metadata to. |
required |
data
|
dict
|
Arbitrary JSON-serializable dict (max 1KB, max nesting depth 32). |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token, 413 if over size limit. |
set_daily(measure, *, date, value)
¶
Sets a daily value (creates or updates).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measure
|
DailyMeasure | str
|
The daily measure (e.g. DailyMeasure.body_mass). |
required |
date
|
date
|
The date for the measurement. |
required |
value
|
float
|
The measurement value. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
DailyResponse |
DailyResponse
|
The created/updated daily entry. |
set_test_app_metadata(test_id, *, data)
¶
Sets app metadata on a test (requires app token).
Replaces the entire metadata dict for this app on the given test.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
test_id
|
str
|
The test to attach metadata to. |
required |
data
|
dict
|
Arbitrary JSON-serializable dict (max 1KB, max nesting depth 32). |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token, 413 if over size limit. |
set_trace_app_metadata(trace_id, *, data)
¶
Sets app metadata on a trace (requires app token).
Replaces the entire metadata dict for this app on the given trace.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
trace_id
|
str
|
The trace to attach metadata to. |
required |
data
|
dict
|
Arbitrary JSON-serializable dict (max 1KB, max nesting depth 32). |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token, 413 if over size limit. |
set_user_app_metadata(*, data)
¶
Sets app metadata on the authenticated user (requires app token).
Replaces the entire metadata dict for this app on the current user.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict
|
Arbitrary JSON-serializable dict (max 4KB, max nesting depth 32). |
required |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
403 if not using an app token, 413 if over size limit. |
update_test(test_id, *, sport, start, title=None, end=None, results=None, tags=None)
¶
Updates a test by replacing all fields.
This is a full replace operation. Fields not provided will be set to null
server-side. To modify a single field, first fetch the test with
get_test(), then pass all fields back.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
test_id
|
str
|
The unique identifier of the test to update. |
required |
sport
|
Sport | str
|
The sport for this test. Can be a Sport enum or string ID. |
required |
start
|
datetime
|
The start time of the test. |
required |
title
|
str | None
|
Optional title for the test. |
None
|
end
|
datetime | None
|
Optional end time. Defaults to start + 3 hours server-side. |
None
|
results
|
TestResults | None
|
Optional structured test results (thresholds, capacities, etc.). |
None
|
tags
|
list[str] | None
|
Optional list of tags to associate with this test. |
None
|
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
update_trace(trace_id, *, timestamp, lactate=None, rpe=None, notes=None, power=None, speed=None, heart_rate=None, tags=None, sport=None)
¶
Updates a trace by replacing all fields.
This is a full replace operation. Fields not provided will be set to null
server-side. To modify a single field, first fetch the trace with
get_traces(), then pass all fields back.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
trace_id
|
str
|
The unique identifier of the trace to update. |
required |
timestamp
|
datetime
|
The date and time when the trace was recorded. |
required |
lactate
|
float | None
|
Optional blood lactate concentration in mmol/L. |
None
|
rpe
|
int | None
|
Optional rating of perceived exertion (typically on a scale of 1-10). |
None
|
notes
|
str | None
|
Optional text notes associated with this trace. |
None
|
power
|
int | None
|
Optional power measurement in watts. |
None
|
speed
|
float | None
|
Optional speed measurement in meters per second. |
None
|
heart_rate
|
int | None
|
Optional heart rate measurement in beats per minute. |
None
|
tags
|
list[str] | None
|
Optional list of tags to associate with this trace. |
None
|
sport
|
Sport | str | None
|
Optional sport to associate with this trace. |
None
|
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
upload(files, *, sport=None)
¶
Uploads activity files (CSV or FIT).
CSV files require the sport parameter and must contain a timestamp
column with ISO 8601 datetimes. FIT files include sport metadata so
sport is optional for them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
files
|
str | Path | list[str | Path]
|
A file path, or a list of file paths, to upload. |
required |
sport
|
Sport | str | None
|
Sport for the activity. Required for CSV files. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
dict |
Confirmation message. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
FileNotFoundError
|
If a file does not exist. |
watch_backfill_status(*, auto_reconnect=False)
¶
Watches backfill status from the activities backfill-status endpoint.
This method connects to the backfill status event stream and yields backfill_loaded_until timestamps as they are received. The connection automatically closes after 60 seconds, but can be configured to auto-reconnect.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
auto_reconnect
|
bool
|
Whether to automatically reconnect when the connection closes and continue receiving updates. Defaults to False. |
False
|
Yields:
| Name | Type | Description |
|---|---|---|
BackfillStatus |
BackfillStatus
|
A BackfillStatus object for each received message. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
whoami()
¶
Gets the authenticated user's summary information.
This method retrieves basic information about the currently authenticated user by extracting the user ID from the JWT token and fetching the user details.
Returns:
| Name | Type | Description |
|---|---|---|
UserSummary |
UserSummary
|
A UserSummary object containing the authenticated user's information. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no authentication token is available. |
HTTPStatusError
|
If the API request fails or user is not found. |