Batch Operations

Batch endpoints let you perform multiple operations in a single API call. Use these when you need to process a training week, onboard a team, or import historical activities. The examples read your key from a SATURDAY_API_KEY environment variable, as in Quickstart. Sandbox keys are issued with a separate base URL; using one against api.saturday.fit returns 401 invalid_api_key.

Batch calculate

Calculate prescriptions for multiple scenarios at once. Ideal for building “training week” views or “what if” comparisons.

POST /v1/nutrition/calculate/batch

Each scenario is a full calculate request, so athlete_id goes on the scenario, not at the top level. Successful results come back in request order, with failures omitted. Use the failed indexes in errors to match each result to its original scenario.

import os
import requests

ATHLETE = "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
week = [
    {"activity_type": "run", "duration_min": 45, "intensity_level": 3},
    {"activity_type": "run", "duration_min": 60, "intensity_level": 7},
    {"activity_type": "bike", "duration_min": 180, "intensity_level": 5,
     "thermal_stress_level": 7},
]

response = requests.post(
    "https://api.saturday.fit/v1/nutrition/calculate/batch",
    headers={"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"},
    json={"scenarios": [dict(s, athlete_id=ATHLETE) for s in week]},
)

data = response.json()
errors = {err["index"]: err for err in data.get("errors", [])}
results = iter(data["results"])
for i in range(len(week)):
    if i in errors:
        err = errors[i]
        print(f"scenario {i} failed: {err['code']} {err['message']}")
        continue
    result = next(results)
    carbs = result.get("carb_range_g_per_hr", result.get("carb_g_per_hr", 0))
    print(f"scenario {i}: {carbs}g carbs/hr")

const ATHLETE = "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d";
const week = [
  { activity_type: "run", duration_min: 45, intensity_level: 3 },
  { activity_type: "run", duration_min: 60, intensity_level: 7 },
  { activity_type: "bike", duration_min: 180, intensity_level: 5,
    thermal_stress_level: 7 },
];

const response = await fetch(
  "https://api.saturday.fit/v1/nutrition/calculate/batch",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SATURDAY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      scenarios: week.map((s) => ({ ...s, athlete_id: ATHLETE })),
    }),
  }
);

const data = await response.json();
const errors = new Map();
for (const error of data.errors ?? []) errors.set(error.index, error);
let resultIndex = 0;
for (let i = 0; i < week.length; i++) {
  const error = errors.get(i);
  if (error) {
    console.log(`scenario ${i} failed: ${error.code} ${error.message}`);
    continue;
  }
  const result = data.results[resultIndex++];
  const carbs = result.carb_range_g_per_hr ?? result.carb_g_per_hr ?? 0;
  console.log(`scenario ${i}: ${carbs}g carbs/hr`);
}

Response format

Counts and the request ID sit at the top level. Each entry in results is the same body the single calculate endpoint returns, so it carries tier, safety, and attribution and does not carry an index. errors appears only when at least one scenario failed.

{
  "results": [
    {
      "tier": "full",
      "carb_g_per_hr": 30,
      "sodium_mg_per_hr": 300,
      "fluid_ml_per_hr": 400,
      "safety": {
        "max_safe_fluid_ml_per_hr": 1500,
        "max_safe_sodium_mg_per_hr": 3000,
        "confidence_score": 0.65,
        "requires_human_review": false,
        "warnings": [],
        "not_instructions": true
      }
    },
    {
      "tier": "full",
      "carb_g_per_hr": 55,
      "sodium_mg_per_hr": 400,
      "fluid_ml_per_hr": 500,
      "safety": {
        "max_safe_fluid_ml_per_hr": 1500,
        "max_safe_sodium_mg_per_hr": 3000,
        "confidence_score": 0.65,
        "requires_human_review": false,
        "warnings": [],
        "not_instructions": true
      }
    }
  ],
  "total": 2,
  "succeeded": 2,
  "failed": 0,
  "estimated_ms": 4200,
  "elapsed_ms": 4381,
  "request_id": "req_ca5a6125aad2"
}

Failed scenarios appear in errors as { "index", "code", "message" }, and the successful ones are still returned: batch operations do not fail atomically. Because failures are dropped from results rather than nulled, results is shorter than scenarios when anything fails, and a result’s position no longer matches its scenario index. When you need that mapping and failures are possible, read the failed indexes from errors first and reconstruct alignment from them.

Limits

Constraint	Value
Max scenarios per batch	50
Rate limiting	Counts as 1 API call per scenario

Exceeding 50 returns 400 with the code batch_too_large, and an empty scenarios array returns 400 with empty_batch.

Sizing the wait

A batch takes as long as the sum of its scenarios. Two things let you show real progress instead of a spinner: the response carries an X-Batch-Estimated-Ms header, flushed before processing begins, and sending "estimate_only": true returns the same estimate immediately without running any calculations, consuming quota, or returning results.

Bulk athlete create

Onboard multiple athletes in one call. Useful for team imports or platform migrations.

POST /v1/athletes/batch

This endpoint takes a partner API key only. An athlete-delegated OAuth token is rejected up front with 403 and code athlete_scope rather than partway through, so a scope mistake never leaves some athletes created and others not.

import requests
import os

response = requests.post(
    "https://api.saturday.fit/v1/athletes/batch",
    headers={"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"},
    json={
        "athletes": [
            {
                "external_id": "user-001",
                "name": "Alice Runner",
                "weight_kg": 58,
                "settings": {"fitness_level": 7},
            },
            {
                "external_id": "user-002",
                "name": "Bob Cyclist",
                "weight_kg": 75,
                "settings": {"fitness_level": 5},
            },
            {
                "external_id": "user-003",
                "name": "Carol Triathlete",
                "weight_kg": 65,
                "settings": {"fitness_level": 9},
            },
        ],
    },
)

results = response.json()
for athlete in results["created"]:
    print(f"Created: {athlete['name']} -> {athlete['id']}")

const response = await fetch("https://api.saturday.fit/v1/athletes/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SATURDAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    athletes: [
      {
        external_id: "user-001",
        name: "Alice Runner",
        weight_kg: 58,
        settings: { fitness_level: 7 },
      },
      {
        external_id: "user-002",
        name: "Bob Cyclist",
        weight_kg: 75,
        settings: { fitness_level: 5 },
      },
    ],
  }),
});

const results = await response.json();
for (const athlete of results.created) {
  console.log(`Created: ${athlete.name} -> ${athlete.id}`);
}

Limits

Constraint	Value
Max athletes per batch	100
Minimum per athlete	At least one of `name`, `email`, or `external_id`

Each athlete is also validated on weight_kg (a negative value is rejected), year_of_birth (1900 to the current year), and sex (male, female, or intersex). A violation fails that item only, with code invalid_value; an item naming none of name, email, or external_id fails with missing_identifier. A year_of_birth that makes the athlete younger than 14 (the current year minus the birth year) fails that item with under_minimum_age, and the item’s message names the minimum age. The batch is also checked against your account’s total athlete quota before processing. If you are at the cap the whole request returns 403 with the code resource_limit_exceeded, rather than partially filling.

external_id is not deduplicated. Saturday does not reject or merge an athlete whose external_id you used before; every create mints a new athlete with a new UUID. Retrying a batch that partially succeeded will therefore create duplicates of the athletes that succeeded the first time. Track the returned IDs against your external_id values and retry only the items that failed.

Activity import

Import multiple activities for an athlete at once. Useful for backfilling historical data from other platforms.

POST /v1/athletes/{athlete_id}/activities/import

An imported activity accepts these fields and no others. Unknown keys are ignored silently, so check this list rather than assuming a field was stored:

Field	Required	Description
`type`	Yes	One of `bike`, `run`, `swim`, `row`, `ski`, `lift`, `hike`
`duration_min`	Yes	Positive integer
`intensity_level`	No	1 to 9; the calculation clamps values outside the scale. `lift` and `hike` use 1 to 3, store anything higher as 3, and an omitted level counts as 2
`thermal_stress_level`	No	1 to 9; the calculation clamps values outside the scale
`is_race_event`	No	Boolean
`external_id`	No	Your activity ID, carried through and used by finish-screen deep links
`calculate`	No	Calculate a prescription for this activity, see below

Imported activities are stamped with the time Saturday created them, so a backfill does not preserve the original activity dates. Keep a date mapping keyed by external_id if you need it.

import requests
import os

response = requests.post(
    "https://api.saturday.fit/v1/athletes/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/activities/import",
    headers={"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"},
    json={
        "activities": [
            {
                "type": "run",
                "duration_min": 48,
                "intensity_level": 7,
                "thermal_stress_level": 2,
                "is_race_event": True,
                "external_id": "strava-10k-2025-01-01",
            },
            {
                "type": "bike",
                "duration_min": 150,
                "intensity_level": 5,
                "external_id": "strava-group-ride-2025-01-04",
            },
        ],
    },
)

const response = await fetch(
  "https://api.saturday.fit/v1/athletes/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/activities/import",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SATURDAY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activities: [
        {
          type: "run",
          duration_min: 48,
          intensity_level: 7,
          thermal_stress_level: 2,
          is_race_event: true,
          external_id: "strava-10k-2025-01-01",
        },
        {
          type: "bike",
          duration_min: 150,
          intensity_level: 5,
          external_id: "strava-group-ride-2025-01-04",
        },
      ],
    }),
  }
);

Up to 200 activities per import. Exceeding that returns 400 with batch_too_large. The import is also checked against the athlete’s activity quota before processing, returning 403 with resource_limit_exceeded if it would exceed the cap. Per-item validation fails an item with missing_field when type is absent and invalid_value for an unknown type or a non-positive duration_min.

Calculating prescriptions during import

Set calculate: true at the top level to calculate a prescription for every imported activity, or on individual activities to calculate selectively:

{
  "calculate": true,
  "activities": [
    { "type": "run", "duration_min": 48 },
    { "type": "bike", "duration_min": 150, "calculate": true }
  ]
}

Each calculation runs the same tier-aware path as the single calculate endpoint: full-tier and in-trial athletes get exact prescriptions, stored on the activity and mirrored on imported[].prescription, while teaser-tier athletes get per-hour ranges with a subscription_cta. Trial athletes debit their daily call allowance per calculated activity, so a large import can exhaust the day’s allowance mid-batch, after which the remaining items return teaser ranges. Per-item outcomes ride a prescriptions array in the response, each with index, activity_id, and the tier-aware result. A failed calculation never fails the import: the activity is still created, and the failure appears on that item’s code and message. Imports count against rate limits per item, like batch calculate.

Error handling in batch operations

Batch operations use partial success semantics. If 3 of 5 items succeed and 2 fail, the 3 successes are committed and the 2 failures are returned in errors. The HTTP status is 200 whenever the request itself was accepted, even when every item failed; a 400 or 403 means nothing was processed. Every batch response uses the same envelope. The success array is named for the operation (results, created, or imported), and alongside it sit total, succeeded, failed, request_id, and, when anything failed, errors. Each error is a flat object with index, code, and message:

{
  "created": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "partner_id": "your-partner-id",
      "name": "Alice Runner",
      "external_id": "user-001",
      "weight_kg": 58,
      "created_at": 1765467600
    }
  ],
  "errors": [
    {
      "index": 1,
      "code": "invalid_value",
      "message": "weight_kg must be positive"
    }
  ],
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "request_id": "req_ca5a6125aad2"
}

Read both arrays. index on an error refers to the item’s position in your request, which is the only reliable way to tell which input failed. Unlike the resource IDs above, request_id is not a UUID: it is req_ followed by 12 hex characters. Log it. It is what support needs to trace a specific call.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Batch Operations

Batch Operations

Batch calculate

Response format

Limits

Sizing the wait

Bulk athlete create

Limits

Activity import

Calculating prescriptions during import

Error handling in batch operations

​Batch Operations

​Batch calculate

​Response format

​Limits

​Sizing the wait

​Bulk athlete create

​Limits

​Activity import

​Calculating prescriptions during import

​Error handling in batch operations

Batch Operations

Batch calculate

Response format

Limits

Sizing the wait

Bulk athlete create

Limits

Activity import

Calculating prescriptions during import

Error handling in batch operations