Skip to content

Client

The SweatStack API client.

Every endpoint group is an attribute named after its URL segment: client.activities, client.traces, client.tests, client.dailies, client.profile, client.users, client.teams, client.portal and client.oauth.

Create one client per user. In a script or notebook, Client() finds your credentials (authenticate(), the SWEATSTACK_API_KEY environment variable, or the tokens saved by an earlier sign-in). In an app, use the client the FastAPI or Streamlit helper hands you for each signed-in user.

Examples:

from sweatstack import Client

client = Client()
client.authenticate()  # opens the browser only when no saved sign-in exists
latest = client.activities.latest()
data = client.activities.data(latest.id)

activities cached property

Activities, their time series and analyses: /api/v1/activities/....

api_key property writable

The current API access token.

Loads from instance, environment (SWEATSTACK_API_KEY), or persistent storage. Automatically refreshes expired tokens.

Returns:

  • SecretStr | None –

    SecretStr containing the access token, or None if not authenticated.

Raises:

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.

dailies cached property

Daily measures (body mass, HRV, ...): /api/v1/dailies/....

oauth cached property

OAuth2 and OpenID Connect: /oauth/... and /api/v1/oauth/....

portal cached property

The SweatStack Portal (beta): /api/v1/portal/....

profile cached property

The user the client acts as: /api/v1/profile/....

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.

teams cached property

Teams: /api/v1/teams/....

tests cached property

Tests (fitness assessments): /api/v1/tests/....

traces cached property

Traces (point measurements such as lactate): /api/v1/traces/....

url property writable

The SweatStack instance URL: the constructor's url, else SWEATSTACK_URL, else production. A non-default instance usually needs its own client_id too.

users cached property

The users you can access, and managed users: /api/v1/users/....

__init__(api_key=None, refresh_token=None, url=None, streamlit_compatible=False, client_id=None, client_secret=None, skip_token_expiry_check=False, output=None, timeout=60.0, max_retries=2)

Initialize a SweatStack client.

Parameters:

  • api_key (str | SecretStr | None, default: None ) –

    Optional API access token. If not provided, will check environment or storage.

  • refresh_token (str | SecretStr | None, default: None ) –

    Optional refresh token for automatic token renewal.

  • url (str | None, default: None ) –

    Optional SweatStack instance URL. Defaults to production.

  • streamlit_compatible (bool, default: False ) –

    Set to True when using in Streamlit apps.

  • client_id (str | None, default: None ) –

    Optional OAuth client ID. Defaults to the public client ID.

  • client_secret (str | SecretStr | None, default: None ) –

    Optional OAuth client secret for confidential clients.

  • skip_token_expiry_check (bool, default: False ) –

    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).

  • output (FrameOutput | None, default: None ) –

    Default container for every method that returns a collection: "pandas", "polars", "arrow" or "bytes". A per-call output= always wins; a value a method cannot produce ("arrow" or "bytes" on list endpoints) is ignored for that method. When None, the module default from :func:sweatstack.set_output applies; failing that, time series come back in the installed frame library (Polars if both are installed) and lists as models. Only the data endpoints take output (activities, traces, tests, dailies and the time series); account, team, status and Portal methods always return models.

  • timeout (float, default: 60.0 ) –

    Seconds to wait for a connection and for each read. Streams have no read timeout.

  • max_retries (int, default: 2 ) –

    How often to retry a GET, PUT or DELETE after a connection error, a timeout, or a 408, 429 or 5xx response, with exponential backoff and the server's Retry-After. POST is never retried, since the API has no idempotency keys. At most 30 s of waiting per call. Use 0 where latency matters more than resilience, such as inside a web request.

Examples:

from sweatstack import Client

client = Client(timeout=120.0, max_retries=4)  # a long batch job
with Client(api_key="...") as client:          # closes the connection pool on exit
    client.activities.list()

authenticate(force=False, persist=True)

Signs the client in, opening the browser only when no saved credentials exist.

Looks for credentials in order: this client, the SWEATSTACK_API_KEY and SWEATSTACK_REFRESH_TOKEN environment variables, then the tokens saved by an earlier sign-in on this machine. Opens the browser for a SweatStack sign-in only when none are found, or when force=True.

In headless environments, set the environment variables instead of calling this.

Parameters:

  • force (bool, default: False ) –

    Sign in again even if credentials exist.

  • persist (bool, default: True ) –

    Save new tokens on this machine for later sessions.

Raises:

  • Exception –

    If the browser sign-in fails or times out.

Examples:

from sweatstack import Client

client = Client()
client.authenticate()            # opens the browser only if needed
client.authenticate(force=True)  # sign in again, e.g. as another user

clear_cache()

Deletes everything :func:sweatstack.enable_cache cached for the current user.

Examples:

from sweatstack import Client

client = Client()
client.clear_cache()

close()

Closes the client's connection pool. The client opens a new one if used again.

Call this, or use the client as a context manager, to release connections at a known point, for example in a worker that creates many clients.

Examples:

from sweatstack import Client

client = Client()
client.activities.list()
client.close()

delegated_client(user, *, team_id=None)

Returns a new client that acts as another user. This client is left unchanged.

Endpoint: POST /api/v1/oauth/delegated-token

Parameters:

  • user (str | UserSummary) –

    The user's ID, or a UserSummary from client.users.list() or client.teams.users(team_id).

  • team_id (str | None, default: None ) –

    Delegate through this team's access instead of a direct share.

Returns:

  • Client ( Client ) –

    A client acting as user, with this client's settings.

Raises:

Examples:

from sweatstack import Client

coach = Client()
for athlete in coach.users.list(include_managed=False):
    athlete_client = coach.delegated_client(athlete)
    print(athlete.display_name, athlete_client.activities.latest())

principal_client()

Returns a new client that acts as the signed-in user, also from a delegated client.

Endpoint: GET /api/v1/oauth/principal-token

Returns:

  • Client ( Client ) –

    A client acting as the principal user, with this client's settings.

Raises:

  • SweatStackAuthError –

    If the current token cannot resolve a principal (e.g. a delegated session that has expired).

  • SweatStackAPIError –

    If the API request fails for any other reason.

Examples:

from sweatstack import Client

client = Client()
athlete_client = client.delegated_client("usr_carla")
coach_client = athlete_client.principal_client()

whoami()

Returns the user this client acts as.

Reads the user ID from the access token and finds it among client.users.list(), so it works on a principal and a delegated client alike and needs no profile scope (unlike client.oauth.userinfo()).

Returns:

  • UserSummary ( UserSummary ) –

    The user this client acts as.

Raises:

  • ValueError –

    If the client is not signed in, or the user cannot be found.

  • SweatStackAPIError –

    If the API request fails.

Examples:

from sweatstack import Client

client = Client()
print(client.whoami().display_name)