Skip to main content
Event endpoints provide access to discrete health events that have a defined start and end time. This includes workouts and sleep sessions (including naps).

​
List Workouts

​
user_id
string
required
UUID of the user
​
start_date
string
required
Start date for the range (ISO 8601 format or Unix timestamp)
​
end_date
string
required
End date for the range (ISO 8601 format or Unix timestamp)
​
record_type
string
Filter by workout type (e.g., “running”, “cycling”, “swimming”, “strength_training”)
​
cursor
string
Pagination cursor from previous response
​
limit
integer
default:"50"
Number of records per page (1-100)
cURL
curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/events/workouts?start_date=2024-03-01&end_date=2024-03-07&record_type=running" \
  -H "X-API-Key: your_api_key"

​
Response

​
data
array
Array of workout objects
​
pagination
object
​
metadata
object
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "running",
      "name": "Morning Run",
      "start_time": "2024-03-01T07:00:00Z",
      "end_time": "2024-03-01T07:45:30Z",
      "duration_seconds": 2730,
      "source": {
        "provider": "apple_health",
        "device": "Apple Watch Series 9"
      },
      "calories_kcal": 425.5,
      "distance_meters": 7243.8,
      "avg_heart_rate_bpm": 152,
      "max_heart_rate_bpm": 178,
      "avg_pace_sec_per_km": 377,
      "elevation_gain_meters": 82.5
    },
    {
      "id": "660f9511-f30c-52e5-b827-557766551111",
      "type": "strength_training",
      "name": "Upper Body Workout",
      "start_time": "2024-03-02T18:30:00Z",
      "end_time": "2024-03-02T19:25:00Z",
      "duration_seconds": 3300,
      "source": {
        "provider": "apple_health",
        "device": "Apple Watch Series 9"
      },
      "calories_kcal": 285.0,
      "distance_meters": null,
      "avg_heart_rate_bpm": 118,
      "max_heart_rate_bpm": 165,
      "avg_pace_sec_per_km": null,
      "elevation_gain_meters": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjY2MGY5NTExLWYzMGMtNTJlNS1iODI3LTU1Nzc2NjU1MTExMSIsInRzIjoxNzA5NDA2NjAwfQ",
    "previous_cursor": null,
    "has_more": true,
    "total_count": 12
  },
  "metadata": {
    "resolution": null,
    "sample_count": 2,
    "start_time": "2024-03-01T00:00:00Z",
    "end_time": "2024-03-07T23:59:59Z"
  }
}

​
List Sleep Sessions

​
user_id
string
required
UUID of the user
​
start_date
string
required
Start date for the range (ISO 8601 format or Unix timestamp)
​
end_date
string
required
End date for the range (ISO 8601 format or Unix timestamp)
​
cursor
string
Pagination cursor from previous response
​
limit
integer
default:"50"
Number of records per page (1-100)
cURL
curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/events/sleep?start_date=2024-03-01&end_date=2024-03-07" \
  -H "X-API-Key: your_api_key"

​
Response

Returns individual sleep sessions including both nighttime sleep and naps.
​
data
array
Array of sleep session objects
​
pagination
object
​
metadata
object
{
  "data": [
    {
      "id": "770f9511-f30c-52e5-b827-557766551111",
      "start_time": "2024-03-01T23:15:00Z",
      "end_time": "2024-03-02T07:30:00Z",
      "source": {
        "provider": "apple_health",
        "device": "Apple Watch Series 9"
      },
      "duration_seconds": 29700,
      "efficiency_percent": 89.5,
      "stages": {
        "awake_minutes": 30,
        "light_minutes": 240,
        "deep_minutes": 120,
        "rem_minutes": 90
      },
      "is_nap": false
    },
    {
      "id": "880f9511-f30c-52e5-b827-557766552222",
      "start_time": "2024-03-02T14:00:00Z",
      "end_time": "2024-03-02T14:30:00Z",
      "source": {
        "provider": "apple_health",
        "device": "Apple Watch Series 9"
      },
      "duration_seconds": 1800,
      "efficiency_percent": 95.0,
      "stages": {
        "awake_minutes": 2,
        "light_minutes": 28,
        "deep_minutes": 0,
        "rem_minutes": 0
      },
      "is_nap": true
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6Ijg4MGY5NTExLWYzMGMtNTJlNS1iODI3LTU1Nzc2NjU1MjIyMiIsInRzIjoxNzA5NDA2NjAwfQ",
    "previous_cursor": null,
    "has_more": true,
    "total_count": 8
  },
  "metadata": {
    "resolution": null,
    "sample_count": 2,
    "start_time": "2024-03-01T00:00:00Z",
    "end_time": "2024-03-07T23:59:59Z"
  }
}

​
Workout Types

The following workout types are supported in the record_type filter parameter:
  • running - Outdoor or treadmill running
  • walking - Walking activities
  • cycling - Road, mountain, or stationary cycling
  • swimming - Pool or open water swimming
  • strength_training - Weightlifting, resistance training
  • hiit - High-intensity interval training
  • yoga - Yoga sessions
  • pilates - Pilates sessions
  • rowing - Rowing machine or water rowing
  • elliptical - Elliptical machine workouts
  • hiking - Trail hiking
  • other - Other workout types

​
Usage Examples

​
Filter Workouts by Type

curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/events/workouts?start_date=2024-03-01&end_date=2024-03-31&record_type=cycling" \
  -H "X-API-Key: your_api_key"

​
Get All Sleep Sessions Including Naps

curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/events/sleep?start_date=2024-03-01&end_date=2024-03-31&limit=50" \
  -H "X-API-Key: your_api_key"

​
Paginate Through Workout History

# First request
curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/events/workouts?start_date=2024-01-01&end_date=2024-03-31&limit=20" \
  -H "X-API-Key: your_api_key"

# Next page using cursor from previous response
curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/events/workouts?start_date=2024-01-01&end_date=2024-03-31&limit=20&cursor=eyJpZCI6IjY2MGY5NTExLWYzMGMtNTJlNS1iODI3LTU1Nzc2NjU1MTExMSIsInRzIjoxNzA5NDA2NjAwfQ" \
  -H "X-API-Key: your_api_key"

Build docs developers (and LLMs) love

Get started for freeTalk to us