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.

Batch calculate

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

POST /v1/nutrition/calculate/batch

import requests

response = requests.post(
    "https://api.saturday.fit/v1/nutrition/calculate/batch",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "athlete_id": "ath_abc123",
        "scenarios": [
            {
                "label": "Monday easy run",
                "activity_type": "run",
                "duration_min": 45,
                "intensity_level": 3,
            },
            {
                "label": "Wednesday intervals",
                "activity_type": "run",
                "duration_min": 60,
                "intensity_level": 7,
            },
            {
                "label": "Saturday long ride",
                "activity_type": "bike",
                "duration_min": 180,
                "intensity_level": 5,
                "thermal_stress_level": 7,
            },
        ],
    },
)

results = response.json()
for result in results["results"]:
    print(f"{result['label']}: {result['carb_g_per_hr']}g carbs/hr")

const response = await fetch(
  "https://api.saturday.fit/v1/nutrition/calculate/batch",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_test_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      athlete_id: "ath_abc123",
      scenarios: [
        {
          label: "Monday easy run",
          activity_type: "run",
          duration_min: 45,
          intensity_level: 3,
        },
        {
          label: "Wednesday intervals",
          activity_type: "run",
          duration_min: 60,
          intensity_level: 7,
        },
        {
          label: "Saturday long ride",
          activity_type: "bike",
          duration_min: 180,
          intensity_level: 5,
          thermal_stress_level: 7,
        },
      ],
    }),
  }
);

const data = await response.json();
data.results.forEach((r: any) =>
  console.log(`${r.label}: ${r.carb_g_per_hr}g carbs/hr`)
);

Response format

{
  "results": [
    {
      "index": 0,
      "label": "Monday easy run",
      "carb_g_per_hr": 30,
      "sodium_mg_per_hr": 300,
      "fluid_ml_per_hr": 400,
      "safety": { "confidence_score": 0.65, "warnings": [], "not_instructions": true }
    },
    {
      "index": 1,
      "label": "Wednesday intervals",
      "carb_g_per_hr": 55,
      "sodium_mg_per_hr": 400,
      "fluid_ml_per_hr": 500,
      "safety": { "confidence_score": 0.65, "warnings": [], "not_instructions": true }
    }
  ],
  "errors": [],
  "metadata": {
    "total_scenarios": 3,
    "successful": 3,
    "failed": 0,
    "request_id": "req_abc123def456"
  }
}

If individual scenarios fail, they appear in errors with the index and error detail. Successful scenarios are still returned — batch operations don’t fail atomically.

Limits

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

Bulk athlete create

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

POST /v1/athletes/batch

response = requests.post(
    "https://api.saturday.fit/v1/athletes/batch",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "athletes": [
            {
                "external_id": "user-001",
                "name": "Alice Runner",
                "weight_kg": 58,
                "fitness_level": "advanced",
                "primary_sport": "run",
            },
            {
                "external_id": "user-002",
                "name": "Bob Cyclist",
                "weight_kg": 75,
                "fitness_level": "intermediate",
                "primary_sport": "bike",
            },
            {
                "external_id": "user-003",
                "name": "Carol Triathlete",
                "weight_kg": 65,
                "fitness_level": "elite",
                "primary_sport": "bike",
            },
        ],
    },
)

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 sk_test_abc123def456",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    athletes: [
      {
        external_id: "user-001",
        name: "Alice Runner",
        weight_kg: 58,
        fitness_level: "advanced",
        primary_sport: "run",
      },
      {
        external_id: "user-002",
        name: "Bob Cyclist",
        weight_kg: 75,
        fitness_level: "intermediate",
        primary_sport: "bike",
      },
    ],
  }),
});

const results = await response.json();
results.created.forEach((a: any) => console.log(`Created: ${a.name} -> ${a.id}`));

Limits

Constraint	Value
Max athletes per batch	100
Duplicate `external_id`	Error for that item, others continue

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

response = requests.post(
    f"https://api.saturday.fit/v1/athletes/ath_abc123/activities/import",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "activities": [
            {
                "type": "run",
                "name": "New Year's Day 10K",
                "duration_min": 48,
                "intensity_level": 7,
                "scheduled_at": "2025-01-01T09:00:00Z",
                "thermal_stress_level": 2,
            },
            {
                "type": "bike",
                "name": "Weekend group ride",
                "duration_min": 150,
                "intensity_level": 5,
                "scheduled_at": "2025-01-04T08:00:00Z",
            },
        ],
    },
)

const response = await fetch(
  `https://api.saturday.fit/v1/athletes/ath_abc123/activities/import`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_test_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activities: [
        {
          type: "run",
          name: "New Year's Day 10K",
          duration_min: 48,
          intensity_level: 7,
          scheduled_at: "2025-01-01T09:00:00Z",
          thermal_stress_level: 2,
        },
        {
          type: "bike",
          name: "Weekend group ride",
          duration_min: 150,
          intensity_level: 5,
          scheduled_at: "2025-01-04T08:00:00Z",
        },
      ],
    }),
  }
);

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); teaser-tier athletes get per-hour ranges with a subscription_cta. Trial athletes debit their daily call allowance per calculated activity — a large import can use up the day’s allowance mid-batch, after which remaining items return teaser ranges. Per-item outcomes ride a prescriptions array in the response (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/message. Imports also count against rate limits per item, like batch calculate.

Error handling in batch operations

Batch operations use partial success semantics. If 3 out of 5 items succeed and 2 fail:

The 3 successful items are committed
The 2 failed items are returned in the errors array with index, error type, and message
The HTTP status is 200 (not 400) because some items succeeded

{
  "created": [
    { "index": 0, "id": "ath_abc123", "name": "Alice Runner" },
    { "index": 2, "id": "ath_def456", "name": "Carol Triathlete" }
  ],
  "errors": [
    {
      "index": 1,
      "error": {
        "type": "conflict",
        "code": "duplicate_external_id",
        "message": "An athlete with external_id 'user-002' already exists"
      }
    }
  ]
}

Check both created (or results) and errors arrays to handle the response correctly.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Batch Operations

Batch Operations

Batch calculate

Response format

Limits

Bulk athlete create

Limits

Activity import

Calculating prescriptions during import

Error handling in batch operations

​Batch Operations

​Batch calculate

​Response format

​Limits

​Bulk athlete create

​Limits

​Activity import

​Calculating prescriptions during import

​Error handling in batch operations

Batch Operations

Batch calculate

Response format

Limits

Bulk athlete create

Limits

Activity import

Calculating prescriptions during import

Error handling in batch operations