Create Activity Log
chevron down

Create Activity Log

Creates a log entry containing the Fitbit user's activity or private custom activity.

Scope: activity


POST /1/user/[user-id]/activities.json

URI Arguments
user-id required The encoded ID of the user. Use "-" (dash) for current logged-in user.

Query Parameters
activityId optional/required This is the activity ID of the activity, directory activity or intensity level activity. If you pass directory activity id, Fitbit calculates and substitutes it with the corresponding intensity level activity ID based on the specified distance and/or duration. Either activityId or activityName must be provided. integer
activityName optional/required Custom activity name. Either activityId or activityName must be provided. string
manualCalories optional/required Calories burned, specified manually. Request with activityName parameter, otherwise optional integer
startTime required Activity start time. Hours and minutes in the format HH:mm. string ($time)
durationMillis required Duration in milliseconds. integer
date required Log entry date in the format yyyy-MM-dd. string ($date)
distance optional/required Distance; required for logging directory activity. In the format X.XX and in the selected distanceUnit or in the unit system that corresponds to the Accept-Language header provided. decimal
distanceUnit optional Distance measurement unit. See Units for acceptable values. "Steps" may be used as a distanceUnits value when the activity is either "Walking" (activityId=90013) or "Running" (activityId=90009). string

Request Headers
authorization required Specify the token type and Fitbit user’s access token.
Token type: Bearer
accept optional The media type of the response content the client is expecting.
Supported: application/json
accept-language optional The measurement unit system to use for response values. See Localization.
accept-locale optional The locale to use for response values. See Localization.
content-length required According to RFC 7230, section 3.3.2, this HTTP request requires the Content-Length header field containing the anticipated size of the payload body.

curl -X POST "" \
-H "accept: application/json" \
-H "authorization: Bearer <access_token>" \
-H "content-length: <message_body_size>"


Element Name Description
activityLog : activityId The ID of the activity.
activityLog : activityParentId The ID of the top level ("parent") activity.
activityLog : activityParentName The name of the top level ("parent") activity.
activityLog : calories Calories burned during the exercise.
activityLog : description Description of the activity logged.
activityLog : distance The distance traveled during the recorded activity in the unit system corresponding to the Accept-Language header.
activityLog : duration The length of time in milliseconds.
activityLog : hasStartTime Specifies if the activity was entered with a start time.
Supported: true | false
activityLog : isFavorite Specifies if activity is listed as a user's favorite.
Supported: true | false
activityLog : lastModified The timestamp the activity was entered in the format yyyy-MM-ddThh:mm:ss.fff.
activityLog : logId The activity log's reference id.
activityLog : name The name of the activity log.
activityLog : startDate The date the activity occurred.
activityLog : startTime The start time the activity occurred.
activityLog : steps The number of steps taken during the activity.
  "activityLog": {
    "activityId": 90013,
    "activityParentId": 90013,
    "activityParentName": "Walk",
    "calories": 300,
    "description": "Walking less than 2 mph, strolling very slowly",
    "distance": 2,
    "duration": 6000000,
    "hasActiveZoneMinutes": true,
    "hasStartTime": true,
    "isFavorite": false,
    "lastModified": "2023-06-05T18:39:39.035Z",
    "logId": 56268507015,
    "name": "Walk",
    "startDate": "2023-06-01",
    "startTime": "10:30",
    "steps": 2706

Response Headers
content-type The media type of the response content being sent to the client.
Supported: application/json
fitbit-rate-limit-limit The quota number of calls.
fitbit-rate-limit-remaining The number of calls remaining before hitting the rate limit.
fitbit-rate-limit-reset The number of seconds until the rate limit resets.
Note: The rate limit headers are approximate and asynchronously updated. This means that there may be a minor delay in the decrementing of remaining requests. This could result in your application receiving an unexpected 429 response if you don't track the total number of requests you make yourself.

Response Type
HTTP Status Code HTTP response code. List of codes are found in the Troubleshooting Guide.
Status Message Description of the status code.
Response Body Contains the JSON response to the API call. When errors are returned by the API call, the errorType, fieldName and message text will provide more information to the cause of the failure.

Response Codes
201 A successful request.
400 The request had bad syntax or was inherently impossible to be satisfied.
401 The request requires user authentication.
Note: For a complete list of response codes, please refer to the Troubleshooting Guide.

Additional Information

This endpoint uses the units in the unit system which corresponds to the Accept-Language header provided (or using optional custom distanceUnit) and sends a JSON response in the format requested.

When specifying the startTime parameter value, do not include seconds. Seconds is not a supported value and will return incorrect data when it is included.

Activity Types

Any activity log entry is based on one of the activities from the catalog of activities. Though activities in catalog have a tree structure (i.e. divided into categories like "Sports and Workouts", "Running" and subcategories like "Bicycling", "Walking"), each activity leaf in the catalog can also have more granular structure. Each leaf can have a directory activity type (and have child intensity levels) or simple activity (have no levels). When creating a new activity log entry, use the following types of objects to pass as the activityId value:

  • Directory activity id: activity contains child activities which represents intensity levels (e.g. "Running").
  • Intensity level id: activity within directory activity (e.g. "Running/6.7mph (9 min/mile)").
  • Simple activity id: single activity without intensity levels (e.g. "Shoveling snow").
Note: A list of activities can be retrieved via the Browse Activities endpoint.

Custom Activities

In the process of creating a new activity log entry, it is possible to seamlessly create a new custom activity for the user. This can be achieved by using the second scenario for the set of POST parameters (providing activityName instead of activityId). In this case, either existing custom activity with the same name will be used for creating new log entry or a new record created and then logged. As for custom activities on the website, manualCalories must always provided with the activityName parameter among other required fields.

Note: "Steps" may be used as a distanceUnits value when the activity is either "Walking" (activityId=90013) or "Running" (activityId=90009) and distance is only included when it is relevant.

Webhook notifications

The Fitbit Web API can send notifications when a Fitbit user has new data to download. This is possible by implementing the Subscription API and subscribing to one or more data collections. See Using Subscriptions. Whenever the activity service recognizes a change to the user’s data, a notification is sent to your application’s subscriber.

The activity collection recognizes changes to a user’s recorded activities, step count, calories burned, distance traveled, etc. Keep in mind that even when a person is not in motion, their body is burning calories. It’s possible to receive activity notifications representing calorie burn even when the user is sleeping or stationary. Today, you cannot subscribe to a subset of the user’s activity data. So, it is the responsibility of your application to query the necessary activity endpoint(s) to reconcile the data in your system.