Time Tracking

This section describes how to start and stop a task timer for implementing our real-time tracking functionality.

Available Endpoints

Start Tracking Time

Starts a timer on a specific task on-the-fly.


Endpoint

https://app.trackingtime.co/api/v4/tasks/track/:id

Parameters

Type Parameter Description Required
Date date The event's start date. Format ISO 8601: yyyy-MM-dd HH:mm:ss like '2014-01-31 17:30:59' YES
String timezone The user's timezone as 'GMT+3' or 'GMT+03:00' NO
String task_name Select or add a task with this name NO
String project_name Select or add a project with this name NO
Boolean return_task If set to true, a task object is returned. Otherwise a time entry will be returned. Default: false NO
Boolean stop_running_task If set to true, any currently running task will be stopped before the new one is started. Default: false NO
JSON json JSON metadata NO
Double estimated_time Set a new estimated time for this task NO
Integer project_id Enter a project id to start tracking time on a project. NO
JSON tags An array of tags to be added to the newly created time entry. 

[{"n":"name","c":"color","v":"value","t":"type"}]
 NO

Smart Task Selection

Instead of setting the task id in the request path, you can use the parameters task_name and project_name to set the task dynamically.

https://app.trackingtime.co/api/v4/tasks/track?date=2015-10-05%2000:00:00&task_name=Task&project_name=Project

We'll try to find an active task with the given task_name assigned to the current user within the project with the given project_name.

  • If a task is found, you'll start tracking this task right away.
  • If no task is found, a new task will be automatically created with the given task_name.
  • If a project with the given project_name is found, the task will be assigned to this existing project.
  • If no project is found, a new one with the given project_name will be automatically created and the task will be assigned to it.

Tracking Projects

Since version v4 you no longer need a task id to start tracking time. Now, users can track time directly on projects, without having to specify a task first. Additionally, users can now track time just by entering a note. No task id or project id required.


To track a project, pass the project_id parameter and avoid the task id in request path:

https://app.trackingtime.co/api/v4/tasks/track?project_id=10

If you don't need to specify a project just call:

https://app.trackingtime.co/api/v4/tasks/track

Response


{
  "name": "03. Fitnity",
  "project_id": 7063,
  "priority": 0,

 ...

"now_tracking": true,
"tracking_event": {
    "start": "2013-03-24 19:35:27",
    "loc_start": "24.03.2013 19:35:27",
    "end": null,
    "loc_end": null,
    "duration": 0,
    "loc_duration": "0",
    "formated_duration": "00:00:00",
    "task_id": 19360,
    "task": "03. Fitnity",
    "id": 67408
  }

Rules

  • You can't track archived tasks
  • This action returns a user exception (status code 502) if the user is currently tracking another task and you didn't set stop_running_task to true.

Stop Tracking Time

Stop the currently active timer on the requested task.


Endpoint

https://app.trackingtime.co/api/v4/tasks/stop/:id

Parameters

Type Parameter Description Required
Date date The event's end date. Format ISO 8601: yyyy-MM-dd HH:mm:ss like '2014-01-31 17:30:59' YES
String timezone The user's timezone as 'GMT+3' or 'GMT+03:00' NO
Boolean return_task If set to true, a task object is returned. Otherwise a time entry will be returned. Default: false NO

Sync Event

Sync your task tracking event by setting the current date as the event's end date. Normally, your client app would call this request in a cronjob to notify the system that the user is still actively tracking this task. Please use a reasonable refresh rate like one, two or five minutes depending on your needs.


Endpoint

https://app.trackingtime.co/api/v4/tasks/sync/:id

Parameters

Type Parameter Description Required
Integer event_id The ID of the event you got when calling the track action YES
Date date The current date. Format ISO 8601: yyyy-MM-dd HH:mm:ss like '2014-01-31 17:30:59' YES
String timezone The user's timezone as 'GMT+3' or 'GMT+03:00' NO
Boolean return_task If set to true, a task object is returned. Otherwise a time entry will be returned. Default: false NO

Rules

  • If the tracking event no longer exists – because the user has already stopped tracking this task on another device or the task was archived in the meantime – you'll get a user exception (status code 502).