Skip to main content

Python library for interacting with the Toggl API.

Project description


Latest PyPI version

TogglPy is a python library for interacting with the Toggl API.


  • Make requests against any (Toggl) API endpoint with request data as a dictionary
  • Generate and save PDFs of summary, weekly, or detailed reports
  • Fetch reports as JSON
  • Get all workspaces or all clients
  • Get a specific workspace or client, by id or name
  • Query projects, by client, or by a single name
  • Add custom time entries


  • Install the project with pip:
pip install -U TogglPy
  • Import the content:
from toggl.TogglPy import Toggl
  • Create a Toggl object:
toggl = Toggl()
toggl.setAuthCredentials('<EMAIL>', '<PASSWORD>') 



I learn best by examples:

Manual GET requests against any Toggl endpoint:

from toggl.TogglPy import Toggl

# create a Toggl object and set our API key 
toggl = Toggl()

response = toggl.request("")

# print the client name and id for each client in the response
# list of returned values can be found in the Toggl docs:
for client in response:
    print "Client name: %s  Client id: %s" % (client['name'], client['id'])

Or, if you want to add some data to your request:

data = {
    'id': 42,
    'some_key': 'some_value',
    'user_agent': 'TogglPy_test',
response = toggl.request("", parameters=data)

Making a POST request to any Toggl endpoint:

data = { 
            "name": "some project", 

response = toggl.postRequest("", parameters=data)

Generating PDF reports:

# specify that we want reports from this week
data = {
    'workspace_id': 0000, # see the next example for getting a workspace id
    'since': '2015-04-27',
    'until': '2015-05-03',

# download one of each type of report for this time period
toggl.getWeeklyReportPDF(data, "weekly-report.pdf")
toggl.getDetailedReportPDF(data, "detailed-report.pdf")
toggl.getSummaryReportPDF(data, "summary-report.pdf")

Finding workspaces and clients

This will print some raw data that will give you all the info you need to identify clients and workspaces quickly:

print toggl.getWorkspaces()
print toggl.getClients()

If you want to clean it up a little replace those print statements with

for workspace in toggl.getWorkspaces():
    print "Workspace name: %s\tWorkspace id:%s" % (workspace['name'], workspace['id'])
for client in toggl.getClients():
    print "Client name: %s\tClient id:%s" % (client['name'], client['id'])

If you want to find a specific client or workspace:

john_doe = toggl.getClient(name="John Doe")
personal = toggl.getWorkspace(name="Personal")

print "John's client id is %s" % john_doe['id']
print "The workspace id for 'Personal' is %s" % personal['id']

The reverse can also be done; use .getClient(id=0000) or .getWorkspace(id=000) to find items by id.

Starting New Timer

# You can get your project pid in>Projects->(select your project)
# and copying the last number of the url
myprojectpid = 10959693
toggl.startTimeEntry("my description", myprojectpid)

Stopping Current Timer

currentTimer = currentRunningTimeEntry()

Creating a custom time entry

# Create a custom entry for today, of a 9 hour duration, starting at 10 AM:
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', hour=10)

# Or speed up the query process and provide the clien't name:
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', clientname='Google', hour=10)

# Provide *month* and/or *day* too for specific dates:
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', clientname='Google', month=1, day=31, hour=10)

# Automate missing time entries!
for day in (29, 30, 31):
	toggl.createTimeEntry(hourduration=9, projectname='someproject', day=day, hour=10)

Automate daily records

import datetime
if not in (4, 5):
	toggl.createTimeEntry(hourduration=9, projectname='someproject', hour=10)

Add your daily records as a cron job:

(crontab -l ; echo "0 22 * * *")| crontab -

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for TogglPy, version 0.1.1
Filename, size & hash File type Python version Upload date
TogglPy-0.1.1-py3-none-any.whl (9.8 kB) View hashes Wheel py3
TogglPy-0.1.1.tar.gz (9.2 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page