Skip to main content

Time entries

GET TimeEntries

https://api.track.toggl.com/api/v9/me/time_entries

Lists latest time entries.

curl  https://api.track.toggl.com/api/v9/me/time_entries \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Query

nametyperequireddescription
metabooleanfalseShould the response contain data for meta entities
include_sharingbooleanfalseInclude sharing details in the response

Query

nametyperequireddescription
sinceintegerfalseGet entries modified since this date using UNIX timestamp, including deleted ones.
beforestringfalseGet entries with start time, before given date (YYYY-MM-DD) or with time in RFC3339 format.
start_datestringfalseGet entries with start time, from start_date YYYY-MM-DD or with time in RFC3339 format. To be used with end_date.
end_datestringfalseGet entries with start time, until end_date YYYY-MM-DD or with time in RFC3339 format. To be used with start_date.

Response

200

Array of:

nametypedescription
atstringWhen was last updated
billablebooleanWhether the time entry is marked as billable
client_namestringRelated entities meta fields - if requested
descriptionstring | nullTime Entry description, null if not provided at creation/update
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanUsed to create a TE with a duration but without a stop time, this field is deprecated for GET endpoints where the value will always be true.
idintegerTime Entry ID
permissionsArray of stringPermission list
pidintegerProject ID, legacy field
project_activeboolean-
project_colorstring-
project_idinteger | nullProject ID. Can be null if project was not provided or project was later deleted
project_namestring-
shared_withArray of
nametypedescription
acceptedboolean-
user_idinteger-
user_namestring-
Indicates who the time entry has been shared with
startstringStart time in UTC
stopstringStop time in UTC, can be null if it's still running or created with "duration" and "duronly" fields
tag_idsArray of integerTag IDs, null if tags were not provided or were later deleted
tagsArray of stringTag names, null if tags were not provided or were later deleted
task_idinteger | nullTask ID. Can be null if task was not provided or project was later deleted
task_namestring-
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_avatar_urlstring-
user_idintegerTime Entry creator ID
user_namestring-
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID

403

User does not have access to this resource.

500

Internal Server Error

GET Get current time entry

https://api.track.toggl.com/api/v9/me/time_entries/current

Load running time entry for user ID.

curl  https://api.track.toggl.com/api/v9/me/time_entries/current \
-H "Content-Type: application/json" \
-u <email>:<password>

Response

200

nametypedescription
atstringWhen was last updated
billablebooleanWhether the time entry is marked as billable
client_namestringRelated entities meta fields - if requested
descriptionstring | nullTime Entry description, null if not provided at creation/update
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanUsed to create a TE with a duration but without a stop time, this field is deprecated for GET endpoints where the value will always be true.
idintegerTime Entry ID
permissionsArray of stringPermission list
pidintegerProject ID, legacy field
project_activeboolean-
project_colorstring-
project_idinteger | nullProject ID. Can be null if project was not provided or project was later deleted
project_namestring-
shared_withArray of
nametypedescription
acceptedboolean-
user_idinteger-
user_namestring-
Indicates who the time entry has been shared with
startstringStart time in UTC
stopstringStop time in UTC, can be null if it's still running or created with "duration" and "duronly" fields
tag_idsArray of integerTag IDs, null if tags were not provided or were later deleted
tagsArray of stringTag names, null if tags were not provided or were later deleted
task_idinteger | nullTask ID. Can be null if task was not provided or project was later deleted
task_namestring-
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_avatar_urlstring-
user_idintegerTime Entry creator ID
user_namestring-
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID

403

User does not have access to this resource.

404

Resource can not be found

500

Internal Server Error

GET Get a time entry by ID.

https://api.track.toggl.com/api/v9/me/time_entries/{time_entry_id}

Load time entry by ID that is accessible by the current user.

curl  https://api.track.toggl.com/api/v9/me/time_entries/{time_entry_id} \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
time_entry_idintegertrueTimeEntry ID.

Query

nametyperequireddescription
metabooleanfalseShould the response contain data for meta entities
include_sharingbooleanfalseInclude sharing details in the response

Response

200

nametypedescription
atstringWhen was last updated
billablebooleanWhether the time entry is marked as billable
client_namestringRelated entities meta fields - if requested
descriptionstring | nullTime Entry description, null if not provided at creation/update
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanUsed to create a TE with a duration but without a stop time, this field is deprecated for GET endpoints where the value will always be true.
idintegerTime Entry ID
permissionsArray of stringPermission list
pidintegerProject ID, legacy field
project_activeboolean-
project_colorstring-
project_idinteger | nullProject ID. Can be null if project was not provided or project was later deleted
project_namestring-
shared_withArray of
nametypedescription
acceptedboolean-
user_idinteger-
user_namestring-
Indicates who the time entry has been shared with
startstringStart time in UTC
stopstringStop time in UTC, can be null if it's still running or created with "duration" and "duronly" fields
tag_idsArray of integerTag IDs, null if tags were not provided or were later deleted
tagsArray of stringTag names, null if tags were not provided or were later deleted
task_idinteger | nullTask ID. Can be null if task was not provided or project was later deleted
task_namestring-
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_avatar_urlstring-
user_idintegerTime Entry creator ID
user_namestring-
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID

404

Resource can not be found

500

Internal Server Error

POST TimeEntries

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries

Creates a new workspace TimeEntry.

curl -X POST https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries \
-H "Content-Type: application/json" \
-d '{"billable":"boolean","created_with":"string","description":"string","duration":"integer","duronly":"boolean","pid":"integer","project_id":"integer","shared_with_user_ids":["integer"],"start":"string","start_date":"string","stop":"string","tag_action":"string","tag_ids":["integer"],"tags":["string"],"task_id":"integer","tid":"integer","uid":"integer","user_id":"integer","wid":"integer","workspace_id":"integer"}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Query

nametyperequireddescription
metabooleanfalseShould the response contain data for meta entities

Body

nametypedescription
billablebooleanWhether the time entry is marked as billable, optional, default false
created_withstringMust be provided when creating a time entry and should identify the service/application used to create it
descriptionstringTime entry description, optional
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanDeprecated: Used to create a time entry with a duration but without a stop time. This parameter can be ignored.
pidintegerProject ID, legacy field
project_idintegerProject ID, optional
shared_with_user_idsArray of integerList of user IDs to share this time entry with
startstringStart time in UTC, required for creation. Format: 2006-01-02T15:04:05Z
start_datestringIf provided during creation, the date part will take precedence over the date part of "start". Format: 2006-11-07
stopstringStop time in UTC, can be omitted if it's still running or created with "duration". If "stop" and "duration" are provided, values must be consistent (start + duration == stop)
tag_actionstringCan be "add" or "delete". Used when updating an existing time entry
tag_idsArray of integerIDs of tags to add/remove
tagsArray of stringNames of tags to add/remove. If name does not exist as tag, one will be created automatically
task_idintegerTask ID, optional
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_idintegerTime Entry creator ID, if omitted will use the requester user ID
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID, required

Response

200

A workspace TimeEntry.
nametypedescription
atstringWhen was last updated
billablebooleanWhether the time entry is marked as billable
client_namestringRelated entities meta fields - if requested
descriptionstring | nullTime Entry description, null if not provided at creation/update
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanUsed to create a TE with a duration but without a stop time, this field is deprecated for GET endpoints where the value will always be true.
idintegerTime Entry ID
permissionsArray of stringPermission list
pidintegerProject ID, legacy field
project_activeboolean-
project_colorstring-
project_idinteger | nullProject ID. Can be null if project was not provided or project was later deleted
project_namestring-
shared_withArray of
nametypedescription
acceptedboolean-
user_idinteger-
user_namestring-
Indicates who the time entry has been shared with
startstringStart time in UTC
stopstringStop time in UTC, can be null if it's still running or created with "duration" and "duronly" fields
tag_idsArray of integerTag IDs, null if tags were not provided or were later deleted
tagsArray of stringTag names, null if tags were not provided or were later deleted
task_idinteger | nullTask ID. Can be null if task was not provided or project was later deleted
task_namestring-
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_avatar_urlstring-
user_idintegerTime Entry creator ID
user_namestring-
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID

403

User does not have access to this resource.

500

Internal Server Error

PATCH Bulk editing time entries

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_ids}

In short: http://tools.ietf.org/html/rfc6902 and http://tools.ietf.org/html/rfc6901 with some additions. Patch will be executed partially when there are errors with some records. No transaction, no rollback.

curl -X PATCH https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_ids} \
-H "Content-Type: application/json" \
-d '{"array":[{"op":{"description":"Operation (add/remove/replace)","type":"string"},"path":{"description":"The path to the entity to patch (e.g. /description)","type":"string"},"value":{"object":{},"description":"The new value for the entity in path."}}]}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
time_entry_idsstringtrueNumeric IDs of time_entries, separated by comma. E.g.: 204301830,202700150,202687559. The limit is 100 IDs per request.

Query

nametyperequireddescription
metabooleanfalseShould the response contain data for meta entities

Body

nametypedescription
arrayArray of
nametypedescription
opstringOperation (add/remove/replace)
pathstringThe path to the entity to patch (e.g. /description)
valueThe new value for the entity in path.
Array of batch operations

Response

200

nametypedescription
failureArray of
nametypedescription
idintegerThe ID for which the patch operation failed.
messagestringThe operation failure reason.
-
successArray of integerThe IDs for which the patch was succesful.

500

Internal Server Error

PUT TimeEntries

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id}

Updates a workspace time entry.

curl -X PUT https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id} \
-H "Content-Type: application/json" \
-d '{"billable":"boolean","created_with":"string","description":"string","duration":"integer","duronly":"boolean","pid":"integer","project_id":"integer","shared_with_user_ids":["integer"],"start":"string","start_date":"string","stop":"string","tag_action":"string","tag_ids":["integer"],"tags":["string"],"task_id":"integer","tid":"integer","uid":"integer","user_id":"integer","wid":"integer","workspace_id":"integer"}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
time_entry_idintegertrueTimeEntry ID.

Query

nametyperequireddescription
metabooleanfalseShould the response contain data for meta entities
include_sharingbooleanfalseShould the response contain time entry sharing details

Body

nametypedescription
billablebooleanWhether the time entry is marked as billable, optional, default false
created_withstringMust be provided when creating a time entry and should identify the service/application used to create it
descriptionstringTime entry description, optional
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanDeprecated: Used to create a time entry with a duration but without a stop time. This parameter can be ignored.
pidintegerProject ID, legacy field
project_idintegerProject ID, optional
shared_with_user_idsArray of integerList of user IDs to share this time entry with
startstringStart time in UTC, required for creation. Format: 2006-01-02T15:04:05Z
start_datestringIf provided during creation, the date part will take precedence over the date part of "start". Format: 2006-11-07
stopstringStop time in UTC, can be omitted if it's still running or created with "duration". If "stop" and "duration" are provided, values must be consistent (start + duration == stop)
tag_actionstringCan be "add" or "delete". Used when updating an existing time entry
tag_idsArray of integerIDs of tags to add/remove
tagsArray of stringNames of tags to add/remove. If name does not exist as tag, one will be created automatically
task_idintegerTask ID, optional
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_idintegerTime Entry creator ID, if omitted will use the requester user ID
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID, required

Response

200

A workspace TimeEntry.
nametypedescription
atstringWhen was last updated
billablebooleanWhether the time entry is marked as billable
client_namestringRelated entities meta fields - if requested
descriptionstring | nullTime Entry description, null if not provided at creation/update
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanUsed to create a TE with a duration but without a stop time, this field is deprecated for GET endpoints where the value will always be true.
idintegerTime Entry ID
permissionsArray of stringPermission list
pidintegerProject ID, legacy field
project_activeboolean-
project_colorstring-
project_idinteger | nullProject ID. Can be null if project was not provided or project was later deleted
project_namestring-
shared_withArray of
nametypedescription
acceptedboolean-
user_idinteger-
user_namestring-
Indicates who the time entry has been shared with
startstringStart time in UTC
stopstringStop time in UTC, can be null if it's still running or created with "duration" and "duronly" fields
tag_idsArray of integerTag IDs, null if tags were not provided or were later deleted
tagsArray of stringTag names, null if tags were not provided or were later deleted
task_idinteger | nullTask ID. Can be null if task was not provided or project was later deleted
task_namestring-
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_avatar_urlstring-
user_idintegerTime Entry creator ID
user_namestring-
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID

403

User does not have access to this resource.

500

Internal Server Error

DELETE TimeEntries

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id}

Deletes a workspace time entry.

curl -X DELETE https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id} \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
time_entry_idintegertrueTimeEntry ID.

Response

200

Returns only status code.

403

User does not have access to this resource.

500

Internal Server Error

PATCH Stop TimeEntry

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id}/stop

Stops a workspace time entry.

curl -X PATCH https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id}/stop \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
time_entry_idintegertrueTimeEntry ID.

Response

200

The stopped workspace TimeEntry.
nametypedescription
atstringWhen was last updated
billablebooleanWhether the time entry is marked as billable
client_namestringRelated entities meta fields - if requested
descriptionstring | nullTime Entry description, null if not provided at creation/update
durationintegerTime entry duration. For running entries should be negative, preferable -1
duronlybooleanUsed to create a TE with a duration but without a stop time, this field is deprecated for GET endpoints where the value will always be true.
idintegerTime Entry ID
permissionsArray of stringPermission list
pidintegerProject ID, legacy field
project_activeboolean-
project_colorstring-
project_idinteger | nullProject ID. Can be null if project was not provided or project was later deleted
project_namestring-
shared_withArray of
nametypedescription
acceptedboolean-
user_idinteger-
user_namestring-
Indicates who the time entry has been shared with
startstringStart time in UTC
stopstringStop time in UTC, can be null if it's still running or created with "duration" and "duronly" fields
tag_idsArray of integerTag IDs, null if tags were not provided or were later deleted
tagsArray of stringTag names, null if tags were not provided or were later deleted
task_idinteger | nullTask ID. Can be null if task was not provided or project was later deleted
task_namestring-
tidintegerTask ID, legacy field
uidintegerTime Entry creator ID, legacy field
user_avatar_urlstring-
user_idintegerTime Entry creator ID
user_namestring-
widintegerWorkspace ID, legacy field
workspace_idintegerWorkspace ID

400

Invalid or missing time_entry_id

403

User does not have access to this resource.

404

Time entry not found

409

Time entry already stopped

500

Internal Server Error
© 2024 Toggl. All rights reserved.