Search documentation

Search for a topic, a control, or an event type.

    Docs / Workflows / Integrations / Toggl 2.0

    Toggl 2.0

    Read time entries, manage timers and logged time, and look up projects, tasks and tags in a Toggl 2.0 workspace.

    What you can do

    Each Toggl 2.0 integration’s page in OAIZ shows these uses, with its events and its read and write actions, under What you can do with Toggl 2.0.

    Weekly hours
    Send a weekly summary of hours per project.
    Running timers
    Remind people whose timer is still running in the evening.
    Case time entries
    Log a time entry when a support case is closed.

    Connecting

    The connection uses a personal API key and one organization and workspace in the Toggl app at focus.toggl.com. The key uses your Toggl permissions, including when you share the connection with other OAIZ users.

    In Toggl, open Profile Settings and find API Token. Select an expiration period, choose Generate and copy the token immediately. Toggl shows it once and allows one active token per user. Generating another revokes the previous token, including its use by other connections.

    Open the workspace you want to connect and copy its HTTPS address. In OAIZ, choose Toggl 2.0 and enter that address in Focus workspace URL and the token in Personal API key. The address must contain the organization and workspace IDs, such as https://focus.toggl.com/123/workspaces/456/calendar. Remove any query string or fragment before using it.

    Your Toggl account needs access to the selected workspace and permission for each operation you use. Connection validation reads workspace permissions and the current timer. A successful connection does not grant additional Toggl permissions.

    Read actions

    Get Current Time Entry
    Read the active timer in the selected workspace. An idle result does not establish whether a timer is running in another workspace.
    Get Time Entry
    Read one entry by its timeEntryId when the connected account can access it in the selected workspace.
    List Time Entries
    Read one page of the connected account’s entries within a date range. Results can include logged, planned and running entries.
    List Projects
    Read one page of existing projects, with their IDs and the query’s total count.
    List Tasks
    Read one page of existing tasks, optionally filtered by project, with their IDs and the query’s total count.
    List Tags
    Read one page of existing workspace tags, with their IDs and the query’s total count.

    Write actions

    Start Time Entry
    Start an activity or break timer. Toggl can stop an existing timer in another workspace when starting the new one.
    Stop Time Entry
    Stop the selected workspace’s current timer and return its completed entry. The operation requires an active timer.
    Create Time Entry
    Create a completed activity or break with an explicit start and duration in seconds, including a zero duration.
    Update Time Entry
    Change supplied fields on an accessible entry. The result acknowledges the update and identifies the entry, without returning a refreshed snapshot.
    Delete Time Entry
    Soft-delete an accessible entry. The result acknowledges deletion and identifies the entry.

    Assignments use existing project, task and tag IDs from the read actions. Starting or creating an entry requires an activity or break type. Start and end times use RFC3339 timestamps with a timezone, such as 2026-10-14T09:00:00Z. Omitted timer timestamps use the current time.

    History and pagination

    List Time Entries reads the connected account’s history. An exact Get Time Entry can read other entries that this account has permission to access. These operations do not provide an employee selector or a company-wide time report.

    The first entry-list request needs dateFrom and dateTo, at most 31 days apart. Entry, project, task and tag pages default to 20 rows and accept a limit from 1 to 100. To continue the same query, pass a page’s nextCursor as cursor, alone or with unchanged filters, sort and limit. Changing the query requires a new first page.

    Time-entry pages return returnedCount and completeness set to unknown. Toggl provides no total count for this endpoint. A continuation cursor or an empty page does not prove complete coverage, so totals based on these pages remain partial unless their coverage is independently verified. Project, task and tag pages include totalCount.

    Plans and API quotas

    Toggl’s plan guide lists public API access on Starter, Premium and Enterprise. Confirm API access for the selected organization, especially when a trial ends. The engineering reference also lists a Free quota, which does not establish lasting Free-plan eligibility.

    The published quotas apply per user, per Toggl organization, per hour. Other applications using the same account can consume this allowance. One OAIZ action can make several provider requests to verify scope or assignments before completing the operation.

    Free
    30 requests, when API access is available.
    Starter
    240 requests.
    Premium
    600 requests.
    Enterprise
    A custom quota agreed with Toggl.

    Toggl returns HTTP 402 when the hourly allowance is exhausted. OAIZ reports this as a quota or plan error. Wait for the quota window to reset, or check the organization’s subscription if access remains unavailable.

    Settings and key renewal

    Connection settings show the selected organization and workspace IDs. To change the key or workspace, disconnect and connect again. When the token expires or is revoked, generate a replacement in Toggl and reconnect OAIZ with it.

    Disconnecting removes the OAIZ connection and pauses live workflows that use it. It leaves the personal Toggl token and Toggl data in place. Connection sharing and removal follow the access rules in Integrations.