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, or build one from that user's tokens with ambient_credentials=False.

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, renewed when it has expired.

See Client for where the tokens come from.

Returns:

  • SecretStr | None –

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

Raises:

client_id property writable

The client ID of the app that renews this client's tokens.

See Client for which app that is.

client_secret property writable

The client secret of the app that renews this client's tokens, if it has one.

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.

See Client for where the tokens come from.

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, *, ambient_credentials=True)

Initialize a SweatStack client.

The access token and the refresh token always come from one source: the arguments, else the SWEATSTACK_API_KEY and SWEATSTACK_REFRESH_TOKEN environment variables, else the tokens saved on this machine by authenticate(). A client given an access token but no refresh token therefore cannot renew it: on expiry it raises SweatStackTokenRefreshError rather than renew with a refresh token from elsewhere. Only a client whose tokens came from the saved file writes a renewed token back to it.

Only the app a refresh token was issued to can renew it. That is the client_id and client_secret given here; else, for tokens from the environment, the app in SWEATSTACK_CLIENT_ID and SWEATSTACK_CLIENT_SECRET; else the SDK's own client, which authenticate() signs in with.

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

    The client ID of the app the tokens were issued to.

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

    That app's client secret, if it exchanged the sign-in code with one.

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

  • ambient_credentials (bool, default: True ) –

    Whether the client may look for credentials in the environment and in the tokens saved on this machine, and save renewed tokens there. False for a client in a server that other people sign in to: it then holds only the tokens you give it, and never reads or writes this machine's. The Streamlit and FastAPI integrations build their clients this way.

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()
user_client = Client(  # in your own server, one per signed-in user
    api_key=access_token, refresh_token=refresh_token, ambient_credentials=False
)

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, with SWEATSTACK_CLIENT_ID and SWEATSTACK_CLIENT_SECRET when your own app issued the tokens.

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:

  • ValueError –

    If persist is set on a client built with ambient_credentials=False.

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