Activities

An activity is one training ride, run, swim, or race. Each activity belongs to an athlete and can carry a nutrition prescription and post-activity feedback. Whatever your platform calls these (workouts, sessions, events), the Saturday object is an activity, and every field and route below uses that word.

Activity lifecycle

Create the activity with type and duration, plus intensity and thermal stress if you have them.
Calculate a nutrition prescription for it.
Submit feedback afterward, if you collect it.

Creating an activity

import os
import requests

response = requests.post(
    "https://api.saturday.fit/v1/athletes/ath_abc123/activities",
    headers={"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"},
    json={
        "type": "run",
        "duration_min": 120,
        "intensity_level": 5,
        "thermal_stress_level": 4,
        "external_id": "your-activity-88213",
    },
)

activity = response.json()
print(f"Activity ID: {activity['id']}")

const response = await fetch(
  "https://api.saturday.fit/v1/athletes/ath_abc123/activities",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SATURDAY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "run",
      duration_min: 120,
      intensity_level: 5,
      thermal_stress_level: 4,
      external_id: "your-activity-88213",
    }),
  }
);

const activity = await response.json();
console.log(`Activity ID: ${activity.id}`);

Activity fields

Field	Type	Required	Description
`type`	string	Yes	Activity type (see supported types)
`duration_min`	integer	Yes	Expected duration in minutes
`intensity_level`	integer	No	1-9 scale; `lift` and `hike` use 1-3 (low, medium, high), store anything higher as 3, and an omitted level counts as 2
`thermal_stress_level`	integer	No	1-9 scale
`is_race_event`	boolean	No	Whether this is a race
`meal_before_min`	integer	No	Minutes between the athlete’s last meal and the start
`external_id`	string	No	Your platform’s activity ID

Create accepts these fields and no others. There is no field for a display name or a scheduled start time; keep those on your side and join on external_id. external_id is worth sending. Saturday’s hosted onboarding finish screen uses it to deep-link the athlete back into the matching activity in your app.

Multi-sport activities

Each activity carries one type, and Saturday prescribes for that type: an athlete fuels differently on the bike than on the run. For a triathlon or a brick, create one activity per leg. To work out which legs a multi-sport title implies, use POST /v1/infer/brick-types.

Calculating a prescription

POST /v1/athletes/{athlete_id}/activities/{activity_id}/calculate

This combines the activity’s parameters with the athlete’s profile. Recalculating overwrites the previous prescription, so call it again whenever the activity changes: a revised duration, a new weather forecast. The response is tier-aware, with the same semantics as /v1/nutrition/calculate:

Full tier (subscribed, covered, or in-trial athletes): tier: "full" with the prescription object (carb, sodium, and fluid totals and per-hour rates), stored on the activity. When the fueling profile is incomplete, the stored prescription carries carb_range_g_per_hr and the other range fields with profile_complete: false in place of exact numbers. Trial responses also carry tier_source: "trial", trial_ends_at, and trial_calls_remaining_today. Each calculation debits the trial’s daily call allowance, exactly like nutrition calculate.
Teaser tier: tier: "teaser" with per-hour ranges (carb_range_g_per_hr, sodium_range_mg_per_hr, fluid_range_ml_per_hr), a subscription_cta carrying the athlete’s subscribe link, and required attribution. Nothing is stored, so GET .../prescription keeps returning the last full-tier result if there was one.

safety metadata is included on every tier.

Getting a stored prescription

GET /v1/athletes/{athlete_id}/activities/{activity_id}/prescription

Returns the most recently calculated prescription for this activity, wrapped with safety metadata:

{
  "prescription": {
    "carb_g_per_hr": 62.5,
    "sodium_mg_per_hr": 485.0,
    "fluid_ml_per_hr": 620.0,
    "total_carb_g": 125,
    "total_sodium_mg": 970,
    "total_fluid_ml": 1240,
    "calculated_at": 1737010500
  },
  "safety": {
    "max_safe_fluid_ml_per_hr": 1500,
    "max_safe_sodium_mg_per_hr": 3000,
    "confidence_score": 0,
    "requires_human_review": false,
    "warnings": null,
    "not_instructions": true
  }
}

calculated_at is a Unix timestamp in seconds, not an ISO 8601 string. Timestamps across the athlete and activity objects (created_at, updated_at) use the same encoding.

On this stored-prescription endpoint, read prescription.* for values and safety.* for guardrails. POST /v1/nutrition/calculate instead returns flat nutrition fields. The activity calculation uses the tier-aware envelope described above. The not_instructions: true flag marks these as recommendations for a person to consider, not commands to execute.

The activity-scoped endpoints populate the two ceilings and not_instructions, but not the rest of the block: confidence_score comes back as 0 and warnings as null from both this read and POST .../calculate. Handle the null, and do not render that zero as a confidence of zero. When you need a confidence score or prescription warnings, call POST /v1/nutrition/calculate with the same parameters. See Safety.

Getting an activity with prescription

GET /v1/athletes/{athlete_id}/activities/{activity_id}

The activity response carries the stored prescription inline.

Listing activities

GET /v1/athletes/{athlete_id}/activities?limit=50&cursor=1737043200%7Cact_7Kq2

Activities come back newest first, paginated by cursor. limit defaults to 50 and is clamped to 1-200; pass pagination.next_cursor back as cursor for the next page, URL-encoded and unchanged. There are no date-range or type filters; filter on your side, or track activities by external_id.

Submitting feedback

Record how the fueling went:

import os
import requests

response = requests.post(
    "https://api.saturday.fit/v1/athletes/ath_abc123/activities/act_xyz789/feedback",
    headers={"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"},
    json={
        "rating": 4,
        "notes": "Felt good until mile 18, then energy dropped",
    },
)

const response = await fetch(
  "https://api.saturday.fit/v1/athletes/ath_abc123/activities/act_xyz789/feedback",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SATURDAY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      rating: 4,
      notes: "Felt good until mile 18, then energy dropped",
    }),
  }
);

Feedback fields

Field	Type	Required	Description
`rating`	integer	Yes	Overall prescription quality, 1 (poor) to 5 (excellent)
`notes`	string	No	Free-text feedback on how the fueling went

Feedback is stored on the activity and returned with it on read, so your UI can show an athlete what they said last time and a coach can review a block of training. Feedback does not change the calculation: prescriptions come from the athlete’s profile and the activity’s parameters, so a rated activity does not change the next one. Update the profile fields to change future prescriptions.

Activity type inference

If your platform has activity metadata but not a clean type, Saturday can infer one:

POST /v1/infer/activity-type

{
  "title": "Morning jog around Green Lake",
  "description": "Easy recovery after yesterday's intervals",
  "tags": ["recovery", "outdoor"]
}

Response:

{
  "activity_type": "run",
  "type": "run",
  "confidence": 0.95,
  "request_id": "req_4f2a9c1e7b30"
}

activity_type is one of the seven activity keys or "unknown", and type carries the same value. When the model is unavailable or the evidence is too thin, you get "unknown" with low or zero confidence rather than an error, so branch on the type. A 502 means the inference service itself could not be reached; it is not counted as usage, so retry with backoff. Sending more than a title sharpens the result. The endpoint also reads pre_activity_comment, workout_type (your provider’s own coarse type), tss_calculation_method, structure_summary, velocity in m/s, has_power, and cadence, and those structured signals resolve many cases before the model is consulted. The API reference names two of these differently, and both spellings work: activity_name is title, and source_type is workout_type. You can also send device, the recording device’s name. A strength session also carries intensity: 1 light, 2 medium, 3 heavy. Lift uses levels 1-3 of intensity_level, so pass the value unchanged as intensity_level when you create the lift activity; rescaling it onto 1-9 raises the carbohydrate ceiling. An entry that marks a day with no training, such as “Rest day”, comes back with "rest_day": true and type "unknown"; it is not a workout to create. For multi-sport titles like “Bike/run brick”, use POST /v1/infer/brick-types. It takes the same fields plus an optional segments list of the legs you already know, in order, and returns every leg in order:

{
  "segments": [
    {"activity_type": "bike", "order": 1},
    {"activity_type": "run", "order": 2}
  ],
  "sub_types": ["bike", "run"],
  "confidence": 0.9,
  "request_id": "req_8d51e0b2c7a4"
}

sub_types is the same list without the order numbers. Create one activity per leg.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Activities

Activities

Activity lifecycle

Creating an activity

Activity fields

Multi-sport activities

Calculating a prescription

Getting a stored prescription

Getting an activity with prescription

Listing activities

Submitting feedback

Feedback fields

Activity type inference

​Activities

​Activity lifecycle

​Creating an activity

​Activity fields

​Multi-sport activities

​Calculating a prescription

​Getting a stored prescription

​Getting an activity with prescription

​Listing activities

​Submitting feedback

​Feedback fields

​Activity type inference

Activities

Activity lifecycle

Creating an activity

Activity fields

Multi-sport activities

Calculating a prescription

Getting a stored prescription

Getting an activity with prescription

Listing activities

Submitting feedback

Feedback fields

Activity type inference