Fork me on GitHub

Toggl API v8

Gem Version Build Status Coverage Status Code Climate

Toggl is a time tracking tool.

togglv8 is a Ruby Wrapper for Toggl API v8. It is designed to mirror the Toggl API as closely as possible.

togglv8 supports both Toggl API and Reports API

Change Log

See CHANGELOG for a summary of notable changes in each version.


Add this line to your application's Gemfile:

gem 'togglv8'

And then execute:

$ bundle

Or install it yourself as:

$ gem install togglv8



TogglV8::API communicates with Toggl API v8 and can be initialized in one of three ways.                      # reads API token from file ~/.toggl           # explicit API token, password)     # email & password


TogglV8::ReportsV2 communicates with Toggl Reports API v2 and can be initialized in one of three ways. requires authentication with an API token for Reports API v2.                              # reads API token from file ~/.toggl toggl_file)  # reads API token from toggl_file api_token)        # explicit API token

Note: workspace_id must be set in order to generate reports.

toggl =
reports =
reports.workspace_id = toggl.workspaces.first['id']


This short example shows one way to create a time entry for the first workspace of the user identified by <API_TOKEN>. It then generates various reports containing that time entry.

require 'togglv8'
require 'json'

toggl_api    =<API_TOKEN>)
user         =
workspaces   = toggl_api.my_workspaces(user)
workspace_id = workspaces.first['id']
time_entry   = toggl_api.create_time_entry({
  'description' => "My awesome workspace time entry",
  'wid' => workspace_id,
  'duration' => 1200,
  'start' => toggl_api.iso8601(( - 3600).to_datetime),
  'created_with' => "My awesome Ruby application"

  reports               = <API_TOKEN>)
  rescue Exception => e
    puts e.message      # workspace_id is required
  reports.workspace_id  = workspace_id
  summary               = reports.summary
  puts "Generating summary JSON..."
  puts JSON.pretty_generate(summary)
  puts "Generating summary PDF..."
  puts "Generating weekly CSV..."
  puts "Generating details XLS..."
  # Note: does not generate Weekly XLS report (as of 2016-07-24)

See specs for more examples.

Note: Requests are rate-limited. The togglv8 gem will handle a 429 response by pausing for 1 second and trying again, for up to 3 attempts. See Toggl API docs:

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.


The TogglV8::API#debug method determines if debug output is printed to STDOUT. This code snippet demonstrates the debug output.

require 'togglv8'

toggl =

toggl.debug(true)  # or simply toggl.debug
user1 =
puts "user: #{user1['fullname']}, debug: true"

puts '-'*80

user2 =
puts "user: #{user2['fullname']}, debug: false"


Run rdoc to generate documentation. Open doc/index.html in your browser.

Also available on DocumentUp



  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Pull Requests that include tests are much more likely to be accepted and merged quickly.


Copyright (c) 2013-2016 Tom Kane. Released under the MIT License. See LICENSE.txt for details.