Doc Home

Authentication

Response Codes

User Methods

Log Methods

API Objects

List Workouts

GET https://api.runningahead.com/rest/logs/me/workouts

Retrieves a list of the user's workouts. The workout data is only in summary form. You will need to call Get Workout to get detailed information for a specific workout using the workout's ID.

You can filter the workouts using the query parameters below. Please note that you are limited to 100 workouts per invocation of List Workouts.

Parameters

Parameter Type Description
access_token string (required) OAuth 2.0 token for the current user.
dateMode string

Aggregate the result by a predefined date range. Specify one of the following:

  • day
  • week
  • month
  • year

Each aggregated result is returned as a Workout object. You need to specify the date property in the fields parameter to distinguish the results. The date value in the workout object will be set to the first date of the aggregation period. For example, if you aggregate by month, then the date will be the first of each month. If an aggregation period does not contain any data, then this period will be excluded from the result.

Date aggregation either averages or sums the resulting numeric values, depending on the value type. For example, distances and durations are summed, while pace and weight are averaged.

fields comma separated list of integers

Specify the list of workout properties to be returned. Rather than requesting all properties for each workout, you should request only the properties needed to generate the workouts list. Empty properties will not be included in the result.

You may specify one or more of the following:

Code Value Description
10 integer Activity ID
11 integer Workout type ID
12 date Date
13 time of day Time of day
20 decimal Distance
21 decimal Duration (expressed in seconds)
22 string Course name
23 string Equipment name
25 string Notes
60 integer The over race placement
61 integer Number of participants in the race
62 integer Minimum group age
63 integer Maximum group age
64 integer Placement within the group
65 integer Number of age group participants
66 integer Overall gender placement
67 integer Number of participants of the same gender
80 decimal Weight
81 integer Resting heart rate
82 integer Workout's average heart rate
83 integer Workout's maximum heart rate
84 decimal Number of hours of sleep
85 integer The workout's quality
86 integer The workout's effort
101 integer Temperature
200 time Average pace
201 decimal Average speed
202 decimal Total calories expended
203 decimal VO2Max
filters JSON array of triplets

Search for workouts by specifying filters. The filters parameter value is a JSON string in the following form:

[["field1", "operator1", value1], ["field2", "operator2", value2], ...]

Since the filters are expressed as a JSON string, they must be properly URI encoded.

Available fields

Field Type Description
activityID integer

Activity ID

Example:

["activityID", "eq", 10]
workoutID integer

Workout type ID.

Example:

["workoutID", "eq", 1]
date Date

The workout date.

Example:

["date", "eq", "2014-04-18"]
time Time

The workout start time.

Example:

["time", "eq", "18:30:00"]
distance Distance or decimal expressed in meters

The workout distance.

Distance can be expressed as the distance object:
{ value: 5, unit: "mi" }
or it can be expressed in meters: 8046.72

Due to floating point rounding errors, it is not commended to search for workouts by distance using the equality operator (i.e. don't use the filter ["distance", "eq", { value: 5, unit: "mi" }]).

Instead, specify a range to account for rounding errors:
["distance", "ge", { value: 4.99, unit: "mi" }], ["distance", "le", { value: 5.01, unit: "mi" }]

You can do the same thing by specifying distance in meters:
["distance", "ge", 8040] ["distance", "le", 8052]

duration decimal in seconds

The duration of the workout expressed in seconds.

Example:

["duration", "eq", 2400]
courseID string

The course's ID.

Example:

["courseID", "eq", "dd8bdfe3622b42daa30e24124525c9b8"]
fieldPlacement integer

If the workout is a race, specify the overall placement.

Example:

["fieldPlacement", "eq", 121]
fieldSize integer

If the workout is a race, specify the overall field size.

Example:

["fieldSize", "eq", 260]
groupPlacement integer

If the workout is a race, specify the placement without the group.

Example:

["groupPlacement", "eq", 23]
groupSize integer

If the workout is a race, specify the number of participants in the group.

Example:

["groupSize", "eq", 43]
weight Weight or integer expressed in grams

The user's weight during the workout.

Weight can be expressed as the weight object:
{ value: 140, unit: "lb" }
or it can be expressed in grams: 63503

Due to floating point rounding errors, it is not commended to search for workouts by weight using the equality operator (i.e. don't use the filter ["weight", "eq", { value: 140, unit: "lb" }]).

Instead, specify a range to account for rounding errors:
["weight", "ge", { value: 139.9, unit: "lb" }], ["weight", "le", { value: 140.1, unit: "lb" }]

You can do the same thing by specifying weight in grams:
["weight", "ge", 63500] ["weight", "le", 63506]

restHR integer

The user's resting heart rate associated with the workout.

Example:

["restHR", "eq", 56]
avgHR integer

The user's average heart rate during the workout.

Example:

["avgHR", "eq", 135]
maxHR integer

The user's maximum heart rate during the workout.

Example:

["maxHR", "eq", 181]
hoursSlept decimal

The number of hours slept.

Example:

["hoursSlept", "eq", 7.3]
quality integer

The quality of the workout Acceptable values are between 1 and 10.

Example:

["quality", "eq", 8]
effort integer

The perceived effort of the workout. Acceptable values are between 1 and 10.

Example:

["effort", "eq", 3]
temperature Temperature or decimal expressed in Celsius degrees

The temperature during the workout.

Temperature can be expressed as the temperature object:
{ value: 55, unit: "F" }
or it can be expressed in Celsius: 12.8

Due to floating point rounding errors, it is not commended to search for workouts by temperature using the equality operator (i.e. don't use the filter ["temperature", "eq", { value: 55, unit: "F" }]).

Instead, specify a range to account for rounding errors:
["temperature", "ge", { value: 54.5, unit: "F" }], ["temperature", "le", { value: 55.5, unit: "F" }]

You can do the same thing by specifying temperature in Celsius degrees:
["temperature", "ge", 12.5], ["temperature", "le", 12.9]

Available operators

Note that fields with string values such as the course ID only accepts the equals (eq) operator since comparing the course ID using other operators doesn't makes sense.

Operator Value
Less than lt
Less than or equals le
Equals eq
Greater than or equals ge
Greater than gt

Examples

Find workouts with distance greater than 10 km:

filters=[["distance","gt",10000]]

Find running races with distance between 5 miles and 10 km:

filters=[["activityID","eq",10],["workoutID","eq",6],["distance","ge",{value:5,unit:"mi"}],["distance","ge",{value:10,unit:"km"}]]
limit integer The total number of workouts to be returned. Must be between 1 and 100, inclusive. If not specified, limit will be defaulted to 50.
offset integer 0-based index of the first workout to be returned.

Response

Parameter Type Description
entries Workout[] An array of workout objects. Each workout object will contain the properties specified by the fields parameter above.
numEntries integer Specifies the total number of workouts matching the filter parameters.

Example

Request

In this example, we are requesting only workouts of the type run (activityID=10) that are between June 1, 2011 and September 30, 2011. We only want the result to include the date (12), distance (21), and duration (22) properties for each workout. We also want the result to contain only 60 entries, starting at entry 120. 

https://api.runningahead.com/rest/logs/me/workouts?
access_token=VjU5s4dyhAPO2XiUzaNVeE&
activityID=10&
fields=12,20,21&
filters=%5b%5b%22date%22%2c%22ge%22%2c%222011-06-01%22%5d%2c%5b%22date%22%2c%22le%22%2c%222011-09-30%22%5d%5d
limit=60&
offset=120

Response

The id property will always be included in the result. You will need the id to obtain detail information for the workout. The distance unit is also automatically included since we requested the distance property. Notice the second workout does not contain a duration property even though we requested it. This is because the user did not record the duration. 

{
    numEntries: 122,
    entries:
    [
        {
            "date": "2011-06-05",
            "details":
            {
                "distance":
                {
                    "unit": "mi",
                    "value": 4.2
                },
                "duration": 2373
            },
            "id": "0c60b2d9eb2f4ac7bb47fd8210fb5f4e"
        },
        {
            "date": "2011-06-01",
            "details":
            {
                "distance":
                {
                    "unit": "mi",
                    "value": 1.5
                }
            },
            "id": "1a0b5226e430458bbc34014f1dcab2c1",
        }
    ];
}
© 2025 RunningAHEAD.com. All rights reserved.