Skip to main content

Milestones

GET List milestones​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones

Returns a list of milestones based on the provided workspace ID and filter params.

curl  https://focus.toggl.com/api/workspaces/{workspace_id}/milestones \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID

Query​

nametyperequireddescription
pageintegerfalsepage number
per_pageintegerfalseresults per page
order_by[]stringfalseorder by
due_date_fromstringfalsefilter by due date from
due_date_tostringfalsefilter by due date to
project_id[]integerfalsefilter by project id
team_id[]integerfalsefilter by team id

Response​

200​

NameTypeDescription
dataArray of object-
pageinteger-
per_pageinteger-
data​
NameTypeDescription
colorstring-
completed_atstring-
created_atstring-
deleted_atstring-
due_datestring-
idinteger-
namestring-
project_idsArray of integer-
team_idsArray of integer-
updated_atstring-
workspace_idinteger-

400​

Invalid request

500​

Internal Server Error

POST Create milestone​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones

Creates a new milestone.

curl -X POST https://focus.toggl.com/api/workspaces/{workspace_id}/milestones \
-H "Content-Type: application/json" \
-d '\{"color":"string","completed_at":"string","due_date":"string","name":"string","project_ids":[\{\}],"team_ids":[\{\}]\}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID

Body​

NameTypeDescription
colorstring-
completed_atstringnolint:lll
due_datestringnolint:lll
namestring-
project_idsArray of integer-
team_idsArray of integer-

Response​

201​

Successful operation

400​

Invalid request

402​

Milestone limit reached; upgrade required

500​

Internal Server Error

GET List milestones​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/stream

Returns a list of milestones based on the provided workspace ID and filter params.

curl  https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/stream \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID

Query​

nametyperequireddescription
order_by[]stringfalseorder by
due_date_fromstringfalsefilter by due date from
due_date_tostringfalsefilter by due date to
project_id[]integerfalsefilter by project id
team_id[]integerfalsefilter by team id

Response​

200​

NameTypeDescription
itemsArray of object-
items​
NameTypeDescription
colorstring-
completed_atstring-
created_atstring-
deleted_atstring-
due_datestring-
idinteger-
namestring-
project_idsArray of integer-
team_idsArray of integer-
updated_atstring-
workspace_idinteger-

400​

Invalid request

500​

Internal Server Error

GET Get milestone​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id}

Get an existing milestone

curl  https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id} \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID
milestone_idintegertruemilestone ID

Response​

200​

NameTypeDescription
colorstring-
completed_atstring-
created_atstring-
deleted_atstring-
due_datestring-
idinteger-
namestring-
project_idsArray of integer-
team_idsArray of integer-
updated_atstring-
workspace_idinteger-

400​

Invalid request

500​

Internal Server Error

PUT Update milestone​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id}

Update an existing milestone

curl -X PUT https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id} \
-H "Content-Type: application/json" \
-d '\{"color":"string","completed_at":"string","due_date":"string","name":"string","project_ids":[\{\}],"team_ids":[\{\}]\}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID
milestone_idintegertruemilestone ID

Body​

NameTypeDescription
colorstring-
completed_atstringnolint:lll
due_datestringnolint:lll
namestring-
project_idsArray of integer-
team_idsArray of integer-

Response​

204​

No Content

400​

Invalid request

500​

Internal Server Error

DELETE Delete milestone​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id}

Delete an existing milestone

curl -X DELETE https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id} \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID
milestone_idintegertruemilestone ID

Response​

204​

No Content

400​

Invalid request

500​

Internal Server Error

PATCH Partial update milestone​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id}

Partial update an existing milestone

curl -X PATCH https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id} \
-H "Content-Type: application/json" \
-d '\{"color":"string","completed_at":"string","due_date":"string","name":"string","project_ids":[\{\}],"team_ids":[\{\}]\}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID
milestone_idintegertruemilestone ID

Body​

NameTypeDescription
colorstringnull
completed_atstringnull
due_datestringnolint:lll
namestringnolint:lll
project_idsArray of integernolint:lll
team_idsArray of integernolint:lll

Response​

204​

No Content

400​

Invalid request

500​

Internal Server Error

PATCH Restore milestone​

https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id}/restore

Restore a deleted milestone

curl -X PATCH https://focus.toggl.com/api/workspaces/{workspace_id}/milestones/{milestone_id}/restore \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueworkspace ID
milestone_idintegertruemilestone ID

Response​

204​

No Content

400​

Invalid request

500​

Internal Server Error

© 2026 Toggl. All rights reserved.