Toggl | Composio Docs

Overview

SLUG: TOGGL

Description

Toggl is a time tracking application that helps users monitor and manage their work hours efficiently.

Authentication Details

API Key

generic_api_key

stringRequired

Connecting to Toggl

Create an auth config

Use the dashboard to create an auth config for the Toggl toolkit. This allows you to connect multiple Toggl accounts to Composio for agents to use.

Select App

Navigate to Toggl.

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

Create and Get auth config ID

Click “Create Toggl Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1 from composio import Composio
2 
3 # Replace these with your actual values
4 toggl_auth_config_id = "ac_YOUR_TOGGL_CONFIG_ID" # Auth config ID created above
5 user_id = "0000-0000-0000"  # UUID from database/app
6 
7 composio = Composio()
8 
9 def authenticate_toolkit(user_id: str, auth_config_id: str):
10     # Replace this with a method to retrieve an API key from the user.
11     # Or supply your own.
12     user_api_key = input("[!] Enter API key")
13 
14     connection_request = composio.connected_accounts.initiate(
15         user_id=user_id,
16         auth_config_id=auth_config_id,
17         config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18     )
19 
20     # API Key authentication is immediate - no redirect needed
21     print(f"Successfully connected Toggl for user {user_id}")
22     print(f"Connection status: {connection_request.status}")
23     
24     return connection_request.id
25 
26 
27 connection_id = authenticate_toolkit(user_id, toggl_auth_config_id)
28 
29 # You can verify the connection using:
30 connected_account = composio.connected_accounts.get(connection_id)
31 print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Toggl toolkit’s playground

OpenAI (Python)

Anthropic (TypeScript)

Google (Python)

Vercel (TypeScript)

Python

1 from composio import Composio
2 from openai import OpenAI
3 import json
4 
5 openai = OpenAI()
6 composio = Composio()
7 
8 # User ID must be a valid UUID format
9 user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10 
11 tools = composio.tools.get(user_id=user_id, toolkits=["TOGGL"])
12 
13 print("[!] Tools:")
14 print(json.dumps(tools))
15 
16 def invoke_llm(task = "What can you do?"):
17     completion = openai.chat.completions.create(
18         model="gpt-4o",
19         messages=[
20             {
21                 "role": "user",
22                 "content": task,  # Your task here!
23             },
24         ],
25         tools=tools,
26     )
27 
28     # Handle Result from tool call
29     result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30     print(f"[!] Completion: {completion}")
31     print(f"[!] Tool call result: {result}")
32 
33 invoke_llm()

Tool List

TOGGL_CREATE_CLIENT

Tool Name: Create Client

Description

Tool to create a new client in a workspace. use when you need to add a client to a workspace after workspace setup.

Action Parameters

name

stringRequired

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_CREATE_ORGANIZATION

Tool Name: Create Organization

Description

Tool to create a new organization with a default workspace. use when initializing a werklog organization and workspace in one step.

Action Parameters

name

stringRequired

workspace_name

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_CREATE_PROJECT

Tool Name: Create Project

Description

Tool to create a new project in a workspace. use after confirming workspace id and desired project parameters.

Action Parameters

active

booleanDefaults to True

billable

boolean

client_id

integer

color

integer

currency

string

estimated_hours

number

fixed_fee

number

hourly_rate

number

is_private

boolean

is_template

boolean

name

stringRequired

template_id

integer

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_CREATE_TAG

Tool Name: Create Tag

Description

Tool to create a new tag in a workspace. use when you need to add a tag after confirming workspace id and desired tag name.

Action Parameters

client_id

integer

name

stringRequired

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_CREATE_TIME_ENTRY

Tool Name: Create Time Entry

Description

Tool to create a new time entry in the specified workspace. use when you have workspace id, start time, and client name ready.

Action Parameters

billable

boolean

created_with

stringRequired

description

string

duration

integer

project_id

integer

start

stringRequired

stop

string

TOGGL_DELETE_CLIENT

Tool Name: Delete Toggl Client

Description

Tool to delete a client in toggl. use when you have confirmed the workspace and client ids and want to remove a client permanently.

Action Parameters

client_id

stringRequired

workspace_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_DELETE_TAG

Tool Name: Delete Tag

Description

Tool to delete a tag from a workspace. use when you need to remove an unused tag after confirming its workspace and tag ids.

Action Parameters

tag_id

stringRequired

workspace_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_CLIENT_DETAILS

Tool Name: Get Client Details

Description

Tool to retrieve details of a specific client. use when you need to fetch client metadata by its id from toggl.

Action Parameters

client_id

integerRequired

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_CURRENT_TIME_ENTRY

Tool Name: Get Current Time Entry

Description

Tool to retrieve the current running time entry for the authenticated user. use after starting the timer to fetch the active time entry.

Action Parameters

Action Response

data

object

error

string

successful

booleanRequired

TOGGL_GET_LIST_CLIENTS

Tool Name: List Clients

Description

Tool to retrieve a list of clients from a toggl workspace. use when you need to list all clients with optional filters.

Action Parameters

active

boolean

page

integer

per_page

integer

since

string

until

string

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_ORGANIZATION_DETAILS

Tool Name: Get Organization Details

Description

Tool to retrieve details of a specific organization by its id. use when you need organizational metadata after confirming the organization id.

Action Parameters

organization_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_ORGANIZATION_GROUPS

Tool Name: Get Organization Groups

Description

Tool to retrieve list of groups in a specified organization. use after confirming organization id.

Action Parameters

organization_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_ORGANIZATION_USERS

Tool Name: Get Organization Users

Description

Tool to retrieve all users in a toggl organization by organization id. use after confirming the target organization id.

Action Parameters

organization_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_PROJECT_DETAILS

Tool Name: Get Project Details

Description

Tool to retrieve details of a specific project. use after confirming the workspace id and project id.

Action Parameters

project_id

integerRequired

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_PROJECTS

Tool Name: Get Projects

Description

Tool to retrieve a list of projects from a toggl workspace. use after confirming workspace id. returns filtered and paginated projects with optional client details.

Action Parameters

clients

boolean

page

integer

page_size

integer

project_ids

string

since

string

until

string

user_id

integer

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_TAGS

Tool Name: Get Tags

Description

Tool to retrieve all tags in a toggl workspace. use after confirming the workspace id.

Action Parameters

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_TASKS

Tool Name: List Tasks

Description

Tool to list tasks in a workspace or within a specific project.

Action Parameters

active

boolean

billable

boolean

page

integer

page_size

integer

project_id

integer

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_TIME_ENTRIES

Tool Name: Get Time Entries

Description

Tool to list the latest time entries for the authenticated user. use when you need to fetch or filter your logged time entries by start date or end date.

Action Parameters

end_date

string

start_date

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_TIME_ENTRY

Tool Name: Get Time Entry

Description

Tool to retrieve a specific time entry by its id. use when you have the entry id and need its full details.

Action Parameters

time_entry_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_USER_CLIENTS

Tool Name: Get User Clients

Description

Tool to fetch the list of clients accessible by the authenticated user. use when you need to see all clients available to the current toggl user.

Action Parameters

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_USER_PREFERENCES

Tool Name: Get User Preferences

Description

Tool to retrieve current user's preferences and alpha features. use when you need to access user settings for customized experiences.

Action Parameters

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_USER_PROJECTS

Tool Name: Get User Projects

Description

Tool to retrieve all projects for the authenticated user. use after authenticating to list available projects.

Action Parameters

workspace_id

integer

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_USER_TAGS

Tool Name: Get User Tags

Description

Tool to retrieve tags associated with the current user. use when you need to list all tags visible to your account.

Action Parameters

workspace_id

integer

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_USER_TASKS

Tool Name: Get User Tasks

Description

Tool to retrieve tasks from projects in which the authenticated user is participating. use after authenticating to list all tasks across workspaces.

Action Parameters

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_USER_WORKSPACES

Tool Name: Get User Workspaces

Description

Tool to retrieve all workspaces the authenticated user belongs to. use when you need to list accessible workspaces before performing workspace-specific operations.

Action Parameters

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_WORKSPACE_DETAILS

Tool Name: Get Workspace Details

Description

Tool to retrieve details of a specific workspace. use when you need to fetch workspace configuration and settings by its id.

Action Parameters

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_WORKSPACE_PREFERENCES

Tool Name: Get Workspace Preferences

Description

Tool to retrieve workspace preferences. use after confirming workspace id to inspect settings like week start, project creation rules, and time tracking options.

Action Parameters

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_GET_WORKSPACE_USERS

Tool Name: Get Workspace Users

Description

Tool to retrieve all users in a toggl workspace by workspace id. use after confirming the target workspace id.

Action Parameters

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_PATCH_STOP_TIME_ENTRY

Tool Name: Stop Time Entry

Description

Tool to stop a running time entry in a workspace. use when a time entry needs to be ended.

Action Parameters

time_entry_id

integerRequired

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_PUT_UPDATE_TAG

Tool Name: Update Tag

Description

Tool to update an existing tag in a specified workspace. use after confirming the workspace id and tag id when renaming a tag. example: rename tag 'urgent' to 'high priority'.

Action Parameters

name

stringRequired

tag_id

integerRequired

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

TOGGL_UPDATE_CLIENT

Tool Name: Update Client

Description

Tool to update details of a specific client. use when you need to modify a client's name, notes, or other details after confirming workspace and client ids.

Action Parameters

client_id

integerRequired

name

string

notes

string

wid

integer

workspace_id

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired