Search API Connector Documentation

Print

Import Toggl Data to Google Sheets

In this guide, we’ll walk through how to pull time tracking data from the Toggl API directly into Google Sheets, using the API Connector add-on for Sheets. We'll first get an API key from Toggl, and then set up a request to pull in your time tracking stats to your spreadsheet.

Contents

Before You Begin

Click here to install the API Connector add-on from the Google Marketplace.

Part 1: Get Your Toggl API Key

  1. Log into your Toggl track account on Toggl.com (or navigate to https://track.toggl.com/timer directly)
  2. From the main dashboard, scroll down and click Profile > Profile settings
    toggl-profile
  3. Scroll down the page until you see a section called "API Token". Copy this to your clipboard.
    toggl-img2
  4. One last step: Because the Toggl API requires Basic Authentication, we need to encode our authentication info to base 64. Enter your your credentials in the format YOUR_API_KEY:api_token into this form, where you substitute in your own api key where it says YOUR_API_KEY, and follow it with a colon and then the word 'api_token' without quotes. Your encoded credentials will appear underneath.

    The encoding script runs in your browser, and none of your credentials are seen or stored by this site.

     

Part 2: Get Your Workspace ID

We'll need your workspace ID for your API requests, so let's get that now. You can retrieve your workspace ID by clicking Reports from the dashboard and checking the URL. Your workspace ID is the numeric identifier after /summary.
toggl-img3

That's it, now we can move on to fetching data.

Part 3: Pull Toggle API Data into Sheets

For this example, we'll get your time stats. Substitute in your own workspace ID, email address, and the encoded key you got above.

  1. Open up Google Sheets and click Extensions > API Connector > Open > Create request.
  2. In the request form enter the following:
    • ApplicationCustom
    • MethodPOST
    • Request URLhttps://api.track.toggl.com/reports/api/v3/workspace/your_workspace_id/search/time_entries
    • Headers:
      • AuthorizationBasic your_encoded_key
      • Content-Type: application/json
    • Request body: {"start_date":"2023-01-01","end_date":"2023-01-28"}
  3. Create a new tab and click Set current to use that tab as your data destination.
  4. Under Output options, switch to Grid mode (this makes the output easier to read).
  5. Name your request and click Run. A moment later you’ll see your time stats populate your Google Sheet.
    toggl-postresponse

The example above shows how to filter by date. You can additionally filter data by billing status, client ID, project ID, and so on, by applying any of the parameters shown in their documentation.

Part 4: More Example Requests

Check the documentation for the full list of available reports, but here are a few more examples.

  • Weekly report
    POST https://api.track.toggl.com/reports/api/v3/workspace/your_workspace_id/weekly/time_entries
  • Summary report
    POST https://api.track.toggl.com/api/v3/workspace/your_workspace_id/summary/time_entries

Part 5: Toggl's v2 API

An earlier version of this article focused on Toggl's v2 API, as it was initially the only API available. It's also a bit easier to configure requests for, since parameters are added to the URL instead of in the request body. As the v2 API is still accessible, and many users have already configured their requests for it, this section has been retained for reference.

Example Request Configuration

As above, substitute in your own workspace ID, email address, and the encoded key you got above. The dates are optional but if you leave them out you'll get data only from the current week (the maximum time span is 1 year).

  1. Open up Google Sheets and click Extensions > API Connector > Open > Create request.
  2. In the request form enter the following:
    • ApplicationCustom
    • MethodGET
    • Request URLhttps://api.track.toggl.com/reports/api/v2/summary?workspace_id=your_workspace_id&user_agent=your_email_address&since=2023-01-01&until=2023-01-28
    • Headers:
      • AuthorizationBasic your_encoded_key
  3. Create a new tab and click Set current to use that tab as your data destination.
  4. Under Output options, switch to Grid mode.
  5. Name your request and click Run.
    toggl-response

Other v2 Endpoint Examples

  • Weekly report
    GET https://api.track.toggl.com/reports/api/v2/weekly?user_agent=your_email_address&workspace_id=your_workspace_id&since=2023-01-01&until=2023-01-28
  • Detailed report
    GET https://api.track.toggl.com/reports/api/v2/details?user_agent=your_email_address&workspace_id=your_workspace_id&since=2023-01-01&until=2023-01-28

Paginating the v2 API

By default, Toggl's v2 API only returns 50 records at a time for the reports endpoint (later API versions return all data without pagination). To get more you need to use the "page" parameter. In API Connector you can do this automatically with pagination handling, like this:

  • Pagination: page parameter
  • Page parameter: page
  • Run until: choose when to stop fetching data
pagination-page-parameter

Part 6: API Documentation

Official documentation: https://developers.track.toggl.com/docs/

v2 API documentation: https://github.com/toggl/toggl_api_docs/blob/master/reports/detailed.md


12 thoughts on “Import Toggl Data to Google Sheets”

  1. Please update the article to use api.track.toggl.com:
    References:
    -https://github.com/toggl/toggl_api_docs
    -https://toggl.com/blog/api-documentation-change

    Reply
  2. Hi,

    I've been following strictly step by step several times this procedure and can't obtain another result than:

    "1) Toggl_summary time stats: Completed with errors
    - We received an error from the API server (401) show response
    {"error":{"message":"api token missing","tip":"You can find your API Token in your profile at https://www.toggl.com","code":401}}"

    I did convert my API to Base 64, referred to your article several times, reset & recreated my API and started from scratch again: same result. What can I be missing?

    Reply
    • I just went through the steps in this article and it worked for me, so I'm not sure.
      Can you try a simple URL like https://api.track.toggl.com/api/v8/me and see if that works?
      Also, can you please doublecheck that you are including your token as an Authorization/Basic header like shown in the article? The only way I can get this error in my tests is if I don't include it in as a header.

      Reply
      • Oh, dang, it has to be me of course! Thanks for your reply!
        What I was misunderstanding & missing was to *litterally* write 'API_KEY:api_token' and not to understand this part as just 'API_KEY' by itself (without the ':api_token' in it).
        *facepalm.
        Thought it's not my native language, but still, my bad : )
        While at it, do you know how I could display the results in lines and not in columns? Because one week of Toggl data (I query 'details') already go until JF column. Some sort of 'transpose' parameter within the initial query?

      • Oh yeah, it is confusing that one is the actual API key and one is just the word! Glad you got it sorted out 🙂

      • Wait, that's ok, I think I found a good compromise playing with your tool settings.
        Thanks again! Will look to automate more things with your solution!

  3. This works for me, but I get a maximum of 50 lines of data. I would like to be able to generate an entire year of data in my sheet. Is this possible?

    Reply
    • Please use 'page' parameter pagination. Under Output Options > pagination choose Pagination = "page parameter", and then enter Page parameter = "page" and the number of pages you'd like to fetch.

      Reply
  4. Hi,
    Thank you so much for this article it really helps a lot.

    May I ask if is it possible to fetch all the data from the other member? Let say, I'd like to auto fetch all the entries of 15 agents. Is it possible?

    Thank you so much.

    Reply
    • Hi Zella, thank you, I'm glad the article helped. However I'm not entirely sure of the answer to your question since I'm not really sure what "member" or "agent" corresponds to. If you check their API documentation you can see many different parameters like "client_ids", "user_ids", and so on, so you can add any of those if that's what you're looking for.

      I suspect there may also be authentication limits here as well, like most likely you can only retrieve data that you have access to in the interface.

      Reply

Leave a Comment

Jump To...