Nutrition Calculation

The nutrition calculation endpoint is Saturday’s core product. It takes an activity description and returns a personalized fuel prescription — carbohydrate, hydration, and electrolyte targets — with safety guardrails applied.

POST /v1/nutrition/calculate

Progressive enrichment

Saturday works with whatever data you have. More data produces more accurate prescriptions — but even minimal inputs return useful results.

Minimal inputs

The bare minimum for a calculation:

response = requests.post(
    "https://api.saturday.fit/v1/nutrition/calculate",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "activity_type": "run",
        "duration_min": 90,
        "athlete_weight_kg": 70,
    },
)

const response = await fetch(
  "https://api.saturday.fit/v1/nutrition/calculate",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_test_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activity_type: "run",
      duration_min: 90,
      athlete_weight_kg: 70,
    }),
  }
);

This returns a prescription with a low confidence_score. The numbers are based on population-level defaults for the given activity type and body weight.

Standard inputs

Add intensity and environmental conditions for a meaningfully better prescription:

{
  "activity_type": "bike",
  "duration_min": 180,
  "intensity_level": 7,
  "athlete_weight_kg": 68,
  "thermal_stress_level": 8
}

Thermal stress dramatically affects hydration and sodium needs. A 3-hour ride at high thermal stress requires very different fueling than the same ride in cool conditions.

Comprehensive inputs

For the highest accuracy, include an athlete reference:

{
  "activity_type": "bike",
  "duration_min": 300,
  "intensity_level": 8,
  "is_race": true,
  "athlete_id": "ath_abc123",
  "thermal_stress_level": 7
}

When you include an athlete_id, Saturday pulls their stored profile — sweat level, saltiness, carb experience, fitness level, and past activity feedback. This is where prescriptions become genuinely personalized.

The enrichment path: Start with minimal inputs to get integrated fast, then progressively add more data as your integration matures. Every additional field improves accuracy.

Understanding the response

{
  "tier": "full",
  "carb_g_per_hr": 72,
  "sodium_mg_per_hr": 800,
  "fluid_ml_per_hr": 750,
  "total_carb_g": 360,
  "total_sodium_mg": 4000,
  "total_fluid_ml": 3750,
  "safety": {
    "max_safe_fluid_ml_per_hr": 1500,
    "max_safe_sodium_mg_per_hr": 3000,
    "confidence_score": 0.85,
    "requires_human_review": false,
    "warnings": [
      "High thermal stress. Consider ice, cold fluids, and shade."
    ],
    "not_instructions": true
  },
  "attribution": {
    "text": "Powered by Saturday",
    "logo_url": "https://saturday.fit/logo.png",
    "link": "https://saturday.fit",
    "required": false
  }
}

Confidence score

The safety.confidence_score (0.0-1.0) indicates how personalized the prescription is:

Range	Meaning	Typical inputs
0.8-1.0	Strong personalization, athlete history	Athlete profile + conditions + feedback
0.5-0.8	Good estimates with some personalization	Weight + intensity + thermal stress
0.0-0.5	Population-level defaults applied	Minimal inputs (type + duration + weight)

Comparing across conditions

To compare fueling across different conditions (e.g. a cool morning vs. a hot afternoon), call POST /v1/nutrition/calculate once per scenario and diff the results yourself, or use POST /v1/nutrition/calculate/batch to submit up to 50 scenarios in a single request.

Two prescription shapes. The calculate endpoints return a flat response (carb_g_per_hr, sodium_mg_per_hr, … with a nested safety block). The stored-prescription read (GET /v1/athletes/{id}/activities/{id}/prescription) returns a wrapped response: { "prescription": { … }, "safety": { … } }. Read the fields accordingly depending on which endpoint you called.

Calculation timing

Running the calculator is a deliberate computation window, not an instant lookup — the same processing experience athletes see in the Saturday app:

Single calculation (POST /v1/nutrition/calculate, POST .../activities/{id}/calculate): expect roughly 1–3 seconds, scaling gently with activity duration. Recalculating an activity that already has a prescription takes about half that.
Batch (POST /v1/nutrition/calculate/batch): each scenario adds roughly half a single calculation’s time. The response headers arrive immediately with X-Batch-Estimated-Ms — the expected total processing time — so you can size progress indicators before the body lands. The completed body includes estimated_ms and elapsed_ms.
Estimate without calculating: send the same batch payload with "estimate_only": true to get estimated_ms back instantly, with no calculations run. Useful when your HTTP client can’t read streamed headers early.
Reads are instant. Fetching a stored prescription (GET .../prescription) never carries a computation window.

Show a progress indicator during calculation. Athletes trust a prescription more when they see it being computed. Use the calculation window to display a “calculating fueling plan…” state rather than a spinner-free freeze.

Teaser vs. full responses

Responses depend on the athlete’s Saturday subscription status:

Subscribed athletes get exact numbers: "carb_g_per_hr": 72
Free/teaser athletes get ranges: "carb_range_g_per_hr": "55-85"

See Freemium Model for implementation details.

Safety

Every calculation response includes a safety block. This is non-negotiable — Saturday is a nutrition API for athletes, and bad recommendations can cause real harm. See Safety for the full guide on safety fields, risk levels, and display requirements.

Safety data is never gated behind subscription status. Even teaser responses include complete safety metadata.

Supported activity types

Type	Key	Notes
Running	`run`	Road, trail, track
Cycling	`bike`	Road, gravel, mountain
Swimming	`swim`	Pool, open water
Rowing	`row`	On-water, ergometer
Skiing	`ski`	Cross-country, classic, skate
Hiking	`hike`	Long-duration, variable intensity
Weightlifting	`lift`	Strength training

Use GET /v1/activity-types for the complete list with descriptions.

Graduated precision (2026-06): every calculation response now carries a precision object — profile_complete, impact-sorted missing_fields, and an onboarding invite URL. Exact numbers require a complete fueling profile; incomplete profiles get honest bands (never wider than teaser ranges). See Athlete Onboarding.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Nutrition Calculation

Nutrition Calculation

Progressive enrichment

Minimal inputs

Standard inputs

Comprehensive inputs

Understanding the response

Confidence score

Comparing across conditions

Calculation timing

Teaser vs. full responses

Safety

Supported activity types

​Nutrition Calculation

​Progressive enrichment

​Minimal inputs

​Standard inputs

​Comprehensive inputs

​Understanding the response

​Confidence score

​Comparing across conditions

​Calculation timing

​Teaser vs. full responses

​Safety

​Supported activity types

Nutrition Calculation

Progressive enrichment

Minimal inputs

Standard inputs

Comprehensive inputs

Understanding the response

Confidence score

Comparing across conditions

Calculation timing

Teaser vs. full responses

Safety

Supported activity types