Python SDK¶

The sweatstack package is the official Python client for the SweatStack API. This page covers installing it, a first script, and where to go next.

Install the SDK¶

Install it with the frame library you analyze with:

uv add "sweatstack[polars]"     # or sweatstack[pandas]

The plain sweatstack package has no frame library. That's enough for services that only need the response models, like FastAPI apps and webhook consumers.

Extra	Adds
`[polars]`	Polars frames
`[pandas]`	pandas frames (includes `[arrow]`)
`[arrow]`	Arrow tables, which DuckDB queries directly
`[streamlit]`	the Streamlit sign-in helper (includes `[pandas]`)
`[fastapi]`	the FastAPI sign-in helper

Extras combine: uv add "sweatstack[polars,arrow]". The SDK supports Python 3.10 and newer.

Write a first script¶

from sweatstack import Client

client = Client()
client.authenticate()  # opens the browser once; the SDK saves the sign-in for later runs

latest = client.activities.latest()
if latest is None:
    raise SystemExit("No activities yet: connect a wearable at https://app.sweatstack.no")

data = client.activities.data(latest.id, metrics=["power", "heart_rate"])
print(data.head())

activities.data() returns a frame of the library you installed. See Data output to choose one per call.

Find the method for an endpoint¶

The SDK mirrors the REST API. Every endpoint group is an attribute named after its URL, and the method name follows from what the endpoint does:

Endpoint	Python
`GET /api/v1/activities/`	`client.activities.list()`
`GET /api/v1/activities/{activity_id}`	`client.activities.retrieve(activity_id)`
`GET /api/v1/activities/{activity_id}/data`	`client.activities.data(activity_id)`
`GET /api/v1/activities/longitudinal-mean-max`	`client.activities.longitudinal.mean_max(...)`
`PUT /api/v1/traces/{trace_id}`	`client.traces.replace(trace_id, ...)`
`POST /api/v1/dailies/{measure}`	`client.dailies.set(measure, ...)`

The attributes are activities, traces, tests, dailies, profile, users, teams, portal and oauth. Each method's reference entry names its endpoint.

Use the SDK with an AI coding agent¶

Install the SDK's agent skill in Claude Code, Cursor, Codex or another agent:

npx skills add SweatStack/sweatstack-python

See AI coding for the other skills and for pointing an agent at these docs.

Next steps¶

Authentication: browser sign-in, API keys, environment variables.
Clients: one client per user, and acting as another user.
Data output: models, pandas, Polars, Arrow and DuckDB.
Errors: what to catch, retries and timeouts.
Upgrading: the changes in each release, and how to update your code.