Activities

Activity lifecycle — creating, prescribing, and tracking

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

Python

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

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
thermal_stress_level	integer	No	1-9 scale
is_race_event	boolean	No	Whether this is a race
name	string	No	Human-readable label
scheduled_at	string	No	ISO 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).

The response is the prescription object itself (carb/sodium/fluid values, totals, per-hour rates).

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": "2025-01-15T06:55:00Z"
  },
  "safety": {
    "max_safe_fluid_ml_per_hr": 1801,
    "max_safe_sodium_mg_per_hr": 5000,
    "confidence_score": 0.85,
    "not_instructions": true,
    "warnings": []
  }
}

The {prescription, safety} envelope is consistent across all Saturday endpoints that return prescription data. Always read prescription.* for values and safety.* for guardrail information. The not_instructions: true flag signals that these are recommendations for human consideration, not executable commands.

Getting an activity with prescription

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

The activity response includes the prescription inline, along with 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:

Python

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

Field	Values	Description
gi_comfort	excellent, good, fair, poor	GI comfort during activity
energy_level	surplus, adequate, low, bonked	Energy levels throughout
hydration_feel	over_hydrated, well_hydrated, slightly_dehydrated, dehydrated	Perceived hydration
actual_intake	object	What 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.