Client class¶
Bases: OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin
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.
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. |
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_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_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_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_data(*, sport=None, sports=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 |
|---|---|---|---|
sport
|
Sport | str | None
|
Optional single sport to filter by. Can be a Sport enum or string. Cannot be used together with 'sports'. |
None
|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter by. Can be a list of Sport enums or strings. Cannot be used together with 'sport'. |
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(*, sport, metric, date=None, window_days=None)
¶
Gets the mean-max curve for a specific sport and metric.
This method retrieves the mean-max curve data for a given sport and metric, optionally filtered by date and window size.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sport
|
Sport | str
|
The sport to get mean-max data for. Can be a Sport enum or string ID. |
required |
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate mean-max for. Must be either "power" or "speed". |
required |
date
|
date | str | None
|
Optional reference date for the mean-max calculation. If provided, the mean-max curve will be calculated up to this date. Can be a date object or string in ISO format. |
None
|
window_days
|
int | None
|
Optional number of days to include in the calculation window before the reference date. If None, all available data is used. |
None
|
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_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_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. |
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. |