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:

Must authenticate with your personal API token to use these endpoints.

# 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.2
Filename, size File type Python version Upload date Hashes
Filename, size TogglPy-0.1.2-py3-none-any.whl (11.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size TogglPy-0.1.2.tar.gz (10.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page