intervals-icu

---
name: intervals-icu-api
description: Complete guide for accessing and managing training data with the intervals.icu API. Use when working with Intervals.icu athlete profiles, activities, workouts, events, wellness data, and training plans. Covers authentication, retrieving activities with combined data fields, managing calendar events with planned workouts, and creating/updating training data. Includes curl examples for all major operations.
---

# Intervals.icu API Skill

Comprehensive guide for interacting with the intervals.icu API to manage athlete training data, activities, workouts, and calendar events.

## Authentication

### API Key Method

Get your Athlete ID and API Key from [intervals.icu settings page](https://intervals.icu/settings).

```bash
# Using API Key header
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID
```

### Bearer Token Method (OAuth)

```bash
# Using Bearer token
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID
```

**Base URL:** `https://intervals.icu/api/v1`

**Date Format:** ISO-8601 (e.g., `2024-01-15` or `2024-01-15T10:30:00`)

---

## Core Concepts

### Athlete ID

Your unique identifier in Intervals.icu. Used in all API endpoints as `{id}` path parameter.

### Activities vs Events

- **Activities**: Completed workouts with actual data (GPS, power, HR). Retrieved from `/athlete/{id}/activities`
- **Events**: Planned workouts on your calendar. Retrieved from `/athlete/{id}/events`

### Data Fields

Activities and events can return different fields. Use the `fields` query parameter to include/exclude specific data points for more efficient queries.

---

## Getting Activities (Completed Workouts)

### List Activities for Date Range

Retrieve all activities between two dates, sorted newest to oldest.

```bash
# Basic activity list
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&newest=2024-01-31"

# With limit
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&limit=10"

# Specific fields only (more efficient)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&fields=id,name,start_date_local,type,distance,moving_time,icu_training_load"

# For specific activity type (Ride, Run, Swim, etc.)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&newest=2024-01-31" | jq '.[] | select(.type == "Ride")'
```

### Combine Activities with External Data

Use `fields` parameter to combine activity data with contextual information:

```bash
# Power, HR, and load data
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&fields=name,icu_weighted_avg_watts,average_heartrate,icu_training_load,icu_atl,icu_ctl"

# Include fatigue and fitness metrics
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&fields=id,name,type,icu_training_load,icu_atl,icu_ctl,perceived_exertion"

# Combine power zones and zone times
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&fields=id,name,distance,moving_time,icu_zone_times,icu_weighted_avg_watts"

# HR zones + intensity data
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities?oldest=2024-01-01&fields=id,name,type,average_heartrate,max_heartrate,icu_hr_zone_times,trimp"
```

### Get Single Activity with Full Details

```bash
# Get activity by ID with all data
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/activity/ACTIVITY_ID"

# Get activity with intervals
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/activity/ACTIVITY_ID?intervals=true"
```

### Export Activity Streams (CSV or JSON)

```bash
# Get activity streams as JSON
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/activity/ACTIVITY_ID/streams.json"

# Get activity streams as CSV (includes time, power, heart_rate, cadence, etc.)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/activity/ACTIVITY_ID/streams.csv" \
  --output activity_streams.csv

# Get specific stream types
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/activity/ACTIVITY_ID/streams.json?types=watts,heart_rate,cadence"
```

---

## Calendar & Planned Workouts

### List Calendar Events (Planned Workouts)

Retrieve planned workouts, notes, and training targets from your calendar.

```bash
# Get all events in date range
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events?oldest=2024-02-01&newest=2024-02-29"

# Get with specific fields
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events?oldest=2024-02-01&newest=2024-02-29&fields=id,name,category,start_date_local,description"

# Filter by category (WORKOUT, NOTE, TARGET, FITNESS_DAYS, etc.)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events?oldest=2024-02-01&category=WORKOUT"

# Get workout targets for date range
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events?oldest=2024-02-01&category=TARGET"
```

### Get Single Event Details

```bash
# Get specific planned workout
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events/EVENT_ID"
```

### Download Planned Workout File

Export planned workouts in various formats for your training device.

```bash
# Download as .zwo (Zwift format)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events/EVENT_ID/download.zwo" \
  --output workout.zwo

# Download as .mrc (TrainerRoad format)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events/EVENT_ID/download.mrc" \
  --output workout.mrc

# Download as .erg (Wahoo format)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events/EVENT_ID/download.erg" \
  --output workout.erg

# Download as .fit (Garmin format)
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events/EVENT_ID/download.fit" \
  --output workout.fit

# Download multiple workouts as zip
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/workouts.zip?oldest=2024-02-01&newest=2024-02-29&ext=zwo" \
  --output workouts.zip
```

---

## Creating & Writing Data

### Create Manual Activity

Add a manually-logged activity to your training history.

```bash
# Basic manual activity
curl -X POST \
  -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Run",
    "type": "Run",
    "start_date_local": "2024-01-15T06:00:00",
    "distance": 10000,
    "moving_time": 3600,
    "description": "Easy morning run"
  }' \
  https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities/manual

# With power (cycling activity)
curl -X POST \
  -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Indoor Zwift",
    "type": "Ride",
    "start_date_local": "2024-01-15T18:00:00",
    "moving_time": 3600,
    "icu_joules": 900000,
    "icu_weighted_avg_watts": 250,
    "average_heartrate": 155,
    "trainer": true
  }' \
  https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities/manual

# With external ID (for syncing with external systems)
curl -X POST \
  -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Strava Activity",
    "type": "Run",
    "start_date_local": "2024-01-15T07:00:00",
    "distance": 5000,
    "moving_time": 1800,
    "external_id": "strava_12345"
  }' \
  https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities/manual
```

### Create Multiple Activities (Bulk)

```bash
# Bulk create activities
curl -X POST \
  -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Monday Easy Run",
      "type": "Run",
      "start_date_local": "2024-01-15T06:00:00",
      "distance": 10000,
      "moving_time": 3600
    },
    {
      "name": "Tuesday Interval Ride",
      "type": "Ride",
      "start_date_local": "2024-01-16T18:00:00",
      "moving_time": 5400,
      "icu_weighted_avg_watts": 280
    }
  ]' \
  https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/activities/manual/bulk
```

### Create Planned Workout (Event on Calendar)

Add a scheduled workout to your calendar for future training.

```bash
# Basic planned workout
curl -X POST \
  -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vo2Max Intervals",
    "category": "WORKOUT",
    "start_date_local": "2024-02-15T18:00:00",
    "description": "6x 4min at 110% FTP with 3min recovery"
  }' \
  "https://intervals.icu/api/v1/athlete/YOUR_ATHLETE_ID/events?upsertOnUid=true"

# Planned workout with Intervals.icu format description
curl -X POST \
  -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sweet Spot Buil

... (truncated)