Skip to main content

​
Activities

Activities represent individual training sessions or races. Each activity belongs to an athlete and can have a nutrition prescription, selected products, and post-activity feedback attached.

​
Activity lifecycle

Create activity -> Calculate prescription -> (Optional) Add products -> (Optional) Submit feedback
  1. Create the activity with type, duration, and optional intensity/thermal stress
  2. Calculate a nutrition prescription for it
  3. Add products the athlete plans to use (optional — for preparation planning)
  4. Submit feedback after the activity (optional — improves future prescriptions)

​
Creating an activity

import requests

response = requests.post(
    "https://api.saturday.fit/v1/athletes/ath_abc123/activities",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "type": "run",
        "name": "Saturday long run",
        "duration_min": 120,
        "intensity_level": 5,
        "scheduled_at": "2025-01-15T07:00:00Z",
        "thermal_stress_level": 4,
    },
)

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

​
Activity fields

FieldTypeRequiredDescription
typestringYesActivity type (see supported types)
duration_minintegerYesExpected duration in minutes
intensity_levelintegerNo1-9 scale
thermal_stress_levelintegerNo1-9 scale
is_race_eventbooleanNoWhether this is a race
namestringNoHuman-readable label
scheduled_atstringNoISO 8601 datetime

​
Multi-sport activities

For triathlons and brick workouts, specify sub-activities: 
{
  "type": "bike",
  "name": "Olympic distance race",
  "duration_min": 165,
  "intensity_level": 8,
  "is_race_event": true
}
Saturday calculates prescriptions tailored to the activity type — you fuel differently on the bike than on a run.

​
Calculating a prescription

POST /v1/athletes/{athlete_id}/activities/{activity_id}/prescription
This uses the activity’s parameters and the athlete’s profile to generate a personalized prescription. Recalculating overwrites the previous prescription — use this when activity parameters change (e.g., updated weather forecast).

​
Getting an activity with prescription

GET /v1/athletes/{athlete_id}/activities/{activity_id}
The activity response includes the prescription, safety metadata, and any attached products.

​
Listing activities

GET /v1/athletes/{athlete_id}/activities?from=2025-01-01&to=2025-01-31&type=running
Supports filtering by date range and type.

​
Submitting feedback

Post-activity feedback improves future prescriptions: 
response = requests.post(
    "https://api.saturday.fit/v1/athletes/ath_abc123/activities/act_xyz789/feedback",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "gi_comfort": "good",
        "energy_level": "adequate",
        "hydration_feel": "slightly_dehydrated",
        "notes": "Felt good until mile 18, then energy dropped",
        "actual_intake": {
            "carbs_grams": 100,
            "fluid_ml": 900,
            "sodium_mg": 800,
        },
    },
)

​
Feedback fields

FieldValuesDescription
gi_comfortexcellent, good, fair, poorGI comfort during activity
energy_levelsurplus, adequate, low, bonkedEnergy levels throughout
hydration_feelover_hydrated, well_hydrated, slightly_dehydrated, dehydratedPerceived hydration
actual_intakeobjectWhat the athlete actually consumed
Feedback is the single most valuable signal for improving future prescriptions. The more activities with feedback, the more personalized Saturday becomes. Encourage athletes to submit feedback — even simple ratings help.

​
Activity type inference

If your platform has activity metadata but not a clean type, Saturday can infer it: 
POST /v1/inference/activity-type

{
  "title": "Morning jog around Green Lake",
  "description": "Easy recovery after yesterday's intervals",
  "tags": ["recovery", "outdoor"]
}
Response: 
{
  "inferred_type": "run",
  "confidence": 0.95,
  "intensity_hint": "easy"
}
For multi-sport titles like “Bike/run brick”, use POST /v1/inference/activity-type/brick.