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",
        }
    ];
}

Doc Home

Authentication

Response Codes

User Methods

Log Methods

API Objects

List Workouts

Parameters

Available fields

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Available operators

Examples

Find workouts with distance greater than 10 km:

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

Response

Example

Request

Response