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
sincestringfalseGet entries with start time, since given unix timestamp.
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

[
{
"at": {
"description": "When was last updated",
"type": "string"
},
"billable": {
"description": "Whether the time entry is marked as billable",
"type": "boolean"
},
"description": {
"description": "Time Entry description, null if not provided at creation/update",
"type": "string",
"nullable": true
},
"duration": {
"description": "Time entry duration. For running entries should be -1 * (Unix start time)",
"type": "integer"
},
"duronly": {
"description": "Used to create a TE with a duration but without a stop time",
"type": "boolean"
},
"id": {
"description": "Time Entry ID",
"type": "integer"
},
"pid": {
"description": "Project ID, legacy field",
"type": "integer"
},
"project_id": {
"description": "Project ID. Can be null if project was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"server_deleted_at": {
"description": "When was deleted, null if not deleted",
"type": "string",
"nullable": true
},
"start": {
"description": "Start time in UTC",
"type": "string"
},
"stop": {
"description": "Stop time in UTC, can be null if it's still running or created with \"duration\" and \"duronly\" fields",
"type": "string"
},
"tag_ids": {
"description": "Tag IDs, null if tags were not provided or were later deleted",
"type": [
"integer"
]
},
"tags": {
"description": "Tag names, null if tags were not provided or were later deleted",
"type": [
"string"
]
},
"task_id": {
"description": "Task ID. Can be null if task was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"tid": {
"description": "Task ID, legacy field",
"type": "integer"
},
"uid": {
"description": "Time Entry creator ID, legacy field",
"type": "integer"
},
"user_id": {
"description": "Time Entry creator ID",
"type": "integer"
},
"wid": {
"description": "Workspace ID, legacy field",
"type": "integer"
},
"workspace_id": {
"description": "Workspace ID",
"type": "integer"
}
}
]

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

{
"at": {
"description": "When was last updated",
"type": "string"
},
"billable": {
"description": "Whether the time entry is marked as billable",
"type": "boolean"
},
"description": {
"description": "Time Entry description, null if not provided at creation/update",
"type": "string",
"nullable": true
},
"duration": {
"description": "Time entry duration. For running entries should be -1 * (Unix start time)",
"type": "integer"
},
"duronly": {
"description": "Used to create a TE with a duration but without a stop time",
"type": "boolean"
},
"id": {
"description": "Time Entry ID",
"type": "integer"
},
"pid": {
"description": "Project ID, legacy field",
"type": "integer"
},
"project_id": {
"description": "Project ID. Can be null if project was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"server_deleted_at": {
"description": "When was deleted, null if not deleted",
"type": "string",
"nullable": true
},
"start": {
"description": "Start time in UTC",
"type": "string"
},
"stop": {
"description": "Stop time in UTC, can be null if it's still running or created with \"duration\" and \"duronly\" fields",
"type": "string"
},
"tag_ids": {
"description": "Tag IDs, null if tags were not provided or were later deleted",
"type": [
"integer"
]
},
"tags": {
"description": "Tag names, null if tags were not provided or were later deleted",
"type": [
"string"
]
},
"task_id": {
"description": "Task ID. Can be null if task was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"tid": {
"description": "Task ID, legacy field",
"type": "integer"
},
"uid": {
"description": "Time Entry creator ID, legacy field",
"type": "integer"
},
"user_id": {
"description": "Time Entry creator ID",
"type": "integer"
},
"wid": {
"description": "Workspace ID, legacy field",
"type": "integer"
},
"workspace_id": {
"description": "Workspace ID",
"type": "integer"
}
}

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","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

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 -1 * (Unix start time)
duronlybooleanUsed to create a time entry with a duration but without a stop time
pidintegerProject ID, legacy field
project_idintegerProject ID, optional
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" and "duronly" fields
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

{
"at": {
"description": "When was last updated",
"type": "string"
},
"billable": {
"description": "Whether the time entry is marked as billable",
"type": "boolean"
},
"description": {
"description": "Time Entry description, null if not provided at creation/update",
"type": "string",
"nullable": true
},
"duration": {
"description": "Time entry duration. For running entries should be -1 * (Unix start time)",
"type": "integer"
},
"duronly": {
"description": "Used to create a TE with a duration but without a stop time",
"type": "boolean"
},
"id": {
"description": "Time Entry ID",
"type": "integer"
},
"pid": {
"description": "Project ID, legacy field",
"type": "integer"
},
"project_id": {
"description": "Project ID. Can be null if project was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"server_deleted_at": {
"description": "When was deleted, null if not deleted",
"type": "string",
"nullable": true
},
"start": {
"description": "Start time in UTC",
"type": "string"
},
"stop": {
"description": "Stop time in UTC, can be null if it's still running or created with \"duration\" and \"duronly\" fields",
"type": "string"
},
"tag_ids": {
"description": "Tag IDs, null if tags were not provided or were later deleted",
"type": [
"integer"
]
},
"tags": {
"description": "Tag names, null if tags were not provided or were later deleted",
"type": [
"string"
]
},
"task_id": {
"description": "Task ID. Can be null if task was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"tid": {
"description": "Task ID, legacy field",
"type": "integer"
},
"uid": {
"description": "Time Entry creator ID, legacy field",
"type": "integer"
},
"user_id": {
"description": "Time Entry creator ID",
"type": "integer"
},
"wid": {
"description": "Workspace ID, legacy field",
"type": "integer"
},
"workspace_id": {
"description": "Workspace ID",
"type": "integer"
}
}

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.

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

{
"failure": {
"items": [
{
"id": {
"description": "The ID for which the patch operation failed.",
"type": "integer"
},
"message": {
"description": "The operation failure reason.",
"type": "string"
}
}
]
},
"success": {
"description": "The IDs for which the patch was succesful.",
"type": [
"integer"
]
}
}

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","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.

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 -1 * (Unix start time)
duronlybooleanUsed to create a time entry with a duration but without a stop time
pidintegerProject ID, legacy field
project_idintegerProject ID, optional
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" and "duronly" fields
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

{
"at": {
"description": "When was last updated",
"type": "string"
},
"billable": {
"description": "Whether the time entry is marked as billable",
"type": "boolean"
},
"description": {
"description": "Time Entry description, null if not provided at creation/update",
"type": "string",
"nullable": true
},
"duration": {
"description": "Time entry duration. For running entries should be -1 * (Unix start time)",
"type": "integer"
},
"duronly": {
"description": "Used to create a TE with a duration but without a stop time",
"type": "boolean"
},
"id": {
"description": "Time Entry ID",
"type": "integer"
},
"pid": {
"description": "Project ID, legacy field",
"type": "integer"
},
"project_id": {
"description": "Project ID. Can be null if project was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"server_deleted_at": {
"description": "When was deleted, null if not deleted",
"type": "string",
"nullable": true
},
"start": {
"description": "Start time in UTC",
"type": "string"
},
"stop": {
"description": "Stop time in UTC, can be null if it's still running or created with \"duration\" and \"duronly\" fields",
"type": "string"
},
"tag_ids": {
"description": "Tag IDs, null if tags were not provided or were later deleted",
"type": [
"integer"
]
},
"tags": {
"description": "Tag names, null if tags were not provided or were later deleted",
"type": [
"string"
]
},
"task_id": {
"description": "Task ID. Can be null if task was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"tid": {
"description": "Task ID, legacy field",
"type": "integer"
},
"uid": {
"description": "Time Entry creator ID, legacy field",
"type": "integer"
},
"user_id": {
"description": "Time Entry creator ID",
"type": "integer"
},
"wid": {
"description": "Workspace ID, legacy field",
"type": "integer"
},
"workspace_id": {
"description": "Workspace ID",
"type": "integer"
}
}

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

Returns only status code.

PATCH TimeEntries

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

{
"at": {
"description": "When was last updated",
"type": "string"
},
"billable": {
"description": "Whether the time entry is marked as billable",
"type": "boolean"
},
"description": {
"description": "Time Entry description, null if not provided at creation/update",
"type": "string",
"nullable": true
},
"duration": {
"description": "Time entry duration. For running entries should be -1 * (Unix start time)",
"type": "integer"
},
"duronly": {
"description": "Used to create a TE with a duration but without a stop time",
"type": "boolean"
},
"id": {
"description": "Time Entry ID",
"type": "integer"
},
"pid": {
"description": "Project ID, legacy field",
"type": "integer"
},
"project_id": {
"description": "Project ID. Can be null if project was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"server_deleted_at": {
"description": "When was deleted, null if not deleted",
"type": "string",
"nullable": true
},
"start": {
"description": "Start time in UTC",
"type": "string"
},
"stop": {
"description": "Stop time in UTC, can be null if it's still running or created with \"duration\" and \"duronly\" fields",
"type": "string"
},
"tag_ids": {
"description": "Tag IDs, null if tags were not provided or were later deleted",
"type": [
"integer"
]
},
"tags": {
"description": "Tag names, null if tags were not provided or were later deleted",
"type": [
"string"
]
},
"task_id": {
"description": "Task ID. Can be null if task was not provided or project was later deleted",
"type": "integer",
"nullable": true
},
"tid": {
"description": "Task ID, legacy field",
"type": "integer"
},
"uid": {
"description": "Time Entry creator ID, legacy field",
"type": "integer"
},
"user_id": {
"description": "Time Entry creator ID",
"type": "integer"
},
"wid": {
"description": "Workspace ID, legacy field",
"type": "integer"
},
"workspace_id": {
"description": "Workspace ID",
"type": "integer"
}
}
© 2022 Toggl. All rights reserved.