Home

Awesome

Toggl API Documentation

⚠️ Important ⚠️

We have migrated our documentation to https://developers.track.toggl.com/docs/. There, you will find up-to date API docs for the Toggl Track, Reports and Webhooks services.

If you're running into issues or require help with anything, please contact our dedicated 24/5 support staff over on our support pages. You can chat with them using the icon on the right bottom.

Toggl API is divided into three:

For changing data, including tracking time, you'll need to use the Toggl API.

If you want to get time entries of all the workspace users and aggregated data for reporting, you need to use the read-only Reports API, which gives you many options for filtering, grouping and sorting.

For monitoring data changes in a workspace, you'll need the Webhooks API.

The API Format

The API accepts only JSON requests. Please make sure you're setting Content-Type: application/jsonin your request header. Each request returns a JSON-encoded body.

The result of each action is communicated via standard HTTP response codes.

Times and dates use the ISO 8601 standard, more specifically a subset described in RFC 3339.

Please do note that the times and dates are stored in UTC (GMT), on return the data is set into the appropriate timezone according to the setting in user profile. 3rd party applications should make sure that they are using correct timezones and also consider daylight saving (where applicable).

For rate limiting we have implemented a Leaky bucket. When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be 1 request per second. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately.

Example requests

The example requests here are done using a command line tool called cURL. If you want to try the requests out yourself, you can download cURL from here. It is available for all possible operating systems.

Under Ubuntu installing cURL is very easy:

sudo apt-get install curl

API token

Each user in Toggl.com has an API token. They can find it under "My Profile" in their Toggl account.

Help us towards a better API

The Toggl API has moved to Github so you could actively participate in helping us making the API better. If you have any requests or you found a bug, you can use Github issues to let us know. You can also fork the docs and send a pull request with improvements

Code examples

Java

Python

Ruby

Node.js

C++

.NET

Scala

PHP

Go

Elixir

3rd party apps

Perl

R

Swift