Create new time tracker

Creates a new time tracker and starts real-time tracking. When a new tracker is created, it automatically stops all other running trackers for the user (only one tracker can run at a time).

The tracker immediately starts with an active interval beginning at the current time. You can specify:

timeTrackingType: Whether to track on Task or Project level
projectId: Optional project to associate with
taskId: Optional task to associate with (requires timeTrackingType: Task)
activityId: Optional activity category
comment: Optional description of the work
correction: Optional time adjustment in minutes (can be positive or negative)

Returns the created tracker with calculated fields including isRunning: true.

POST/account/time-tracker

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Query parameters

fieldsToReturnstring

Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.

responseShapestring

Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:compactfull

Header parameters

LT-Response-Shapestring

Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:full

Request body

requiredapplication/json

activityIdstring

Optional. UUID of the activity category (e.g., Development, Testing, Management). Used to categorize the type of work being tracked for reporting purposes.

commentstring

Optional. Free-text comment describing the work being tracked. Helps provide context when reviewing time entries later.

correctionnumber

Optional. Manual time adjustment in minutes. Positive values add time (e.g., if you started tracking late), negative values subtract time. Default is 0.

projectIdstring

Optional. UUID of the project to associate with this tracker. If provided, the tracked time will be linked to this project.

taskIdstring

Optional. UUID of the task to associate with this tracker. Only used when timeTrackingType is Task. If timeTrackingType is Task, you should typically provide a taskId.

timeTrackingTypestringrequired

Required. Type of time tracking: Task (for tracking time on a specific task) or Project (for tracking time at project level). Determines whether taskId should be provided.

Allowed:TaskProject

Responses

200

activityIdobject | nullrequired

UUID of the activity category (e.g., Development, Testing, Management). Used for categorizing work in reports. Can be null.

autoEndedbooleanrequired

Whether any interval was automatically ended at the end of the day. This happens when a running interval started on a previous day and was not manually stopped.

commentobject | nullrequired

Optional comment or description of the work being tracked. Helps provide context when reviewing time entries later.

correctionnumberrequired

Manual time adjustment in minutes. Positive values add time, negative values subtract time. Useful for correcting tracking errors or adding time that was not tracked. Default is 0.

createdAtstringrequired

Timestamp when the tracker was created, in ISO 8601 format (UTC)

hoursnumberrequired

Total tracked time in hours, calculated from all intervals plus any correction. Minimum value is 0.0166667 (1 minute).

hoursPaddedstringrequired

Hours portion of the tracked time, formatted as a zero-padded string (e.g., "02", "12", "00")

idstringrequired

Unique identifier for the time tracker (UUID)

intervalsTimeTrackerIntervalDto[]required

Array of time intervals that make up the total tracked time. Each interval represents a continuous period of tracking (start to end). If an interval has no end, it is currently active. Intervals are automatically ended at end of day if they span midnight.

Show properties

Array of TimeTrackerIntervalDto

endstringrequired

Interval end time in ISO 8601 format (UTC). For active (running) intervals, this is set to the current time. For completed intervals, this marks when tracking stopped. Intervals that span midnight are automatically ended at end of day.

startstringrequired

Interval start time in ISO 8601 format (UTC). This is when the time tracking period began.

isOldbooleanrequired

Whether the tracker contains intervals from previous days. True if any interval start time is not from today.

isRunningbooleanrequired

Whether the tracker currently has an active (running) interval. True if any interval has no end time, meaning time is being tracked right now.

minutesPaddedstringrequired

Minutes portion of the tracked time, formatted as a zero-padded string (e.g., "05", "30", "59")

projectIdobject | nullrequired

UUID of the project this tracker is associated with. Can be null if tracking general work.

taskIdobject | nullrequired

UUID of the task this tracker is associated with. Only used when timeTrackingType is Task. Can be null for project-level tracking.

timeTrackingTypestringrequired

Type of time tracking: Task (tracking time on a specific task) or Project (tracking time at project level). Determines whether taskId is required.

Allowed:TaskProject

400Invalid input data

401Unauthorized - Invalid or missing authentication token

403Forbidden - Insufficient API scopes or permissions

Request

curl -X POST "https://leadtime.app/api/public/account/time-tracker" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "activityId": "550e8400-e29b-41d4-a716-446655440003",
  "comment": "Working on feature implementation",
  "correction": 0,
  "projectId": "550e8400-e29b-41d4-a716-446655440001",
  "taskId": "550e8400-e29b-41d4-a716-446655440002",
  "timeTrackingType": "Task"
}'

const response = await fetch("https://leadtime.app/api/public/account/time-tracker", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "activityId": "550e8400-e29b-41d4-a716-446655440003",
  "comment": "Working on feature implementation",
  "correction": 0,
  "projectId": "550e8400-e29b-41d4-a716-446655440001",
  "taskId": "550e8400-e29b-41d4-a716-446655440002",
  "timeTrackingType": "Task"
})
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/account/time-tracker",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "activityId": "550e8400-e29b-41d4-a716-446655440003",
  "comment": "Working on feature implementation",
  "correction": 0,
  "projectId": "550e8400-e29b-41d4-a716-446655440001",
  "taskId": "550e8400-e29b-41d4-a716-446655440002",
  "timeTrackingType": "Task"
},
)

Response

{
  "activityId": "550e8400-e29b-41d4-a716-446655440003",
  "autoEnded": false,
  "comment": "Working on feature implementation",
  "correction": 0,
  "createdAt": "2024-01-15T10:00:00Z",
  "hours": 2.5,
  "hoursPadded": "02",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "intervals": [
    {
      "end": "2024-01-15T11:30:00Z",
      "start": "2024-01-15T10:00:00Z"
    }
  ],
  "isOld": false,
  "isRunning": true,
  "minutesPadded": "30",
  "projectId": "550e8400-e29b-41d4-a716-446655440001",
  "taskId": "550e8400-e29b-41d4-a716-446655440002",
  "timeTrackingType": "Task"
}