How to Integrate Retool with Toggl

Toggl Track provides a personal API token in your profile settings. This token grants access to all workspaces your account belongs to and does not expire unless manually regenerated. In the Toggl Track web app (track.toggl.com), click your name or avatar in the bottom left of the sidebar to open the account menu. Select Profile Settings. On the Profile Settings page, scroll to the very bottom of the page. In the section labeled API Token, you will see your current API token displayed as a string of lowercase alphanumeric characters. Click the eye icon to reveal it if it is masked. Click Copy to clipboard. If you need to regenerate the token (e.g., for security reasons), click Reset and confirm — this immediately invalidates the old token. Note your workspace ID as well: you can find it by clicking your workspace name in the Toggl sidebar, then selecting Settings — the workspace ID appears in the browser URL (track.toggl.com/workspaces/{id}/settings). Alternatively, call the /me/workspaces endpoint after setting up the Resource to retrieve all workspaces your account has access to. The workspace_id is required for most workspace-scoped endpoints including the Reports API. Most teams have a single workspace, but multi-workspace accounts must specify the correct workspace_id for each query.

In Retool, navigate to the Resources tab and click Add Resource. Select REST API from the list. Name the resource Toggl Track API. In the Base URL field, enter https://api.track.toggl.com/api/v9 — this is the current Toggl API v9 base URL. Toggl's API has two separate base URLs: the main API (api.track.toggl.com/api/v9) for CRUD operations, and the Reports API (api.track.toggl.com/reports/api/v3) for analytics. You will need two separate Resources in Retool to access both, since they have different base URLs. Create the main API Resource now. In the Authentication section, select Basic Auth from the dropdown (not Bearer Token — Toggl uses Basic Auth with a special password value). Set the Username field to {{ config.TOGGL_API_TOKEN }} and the Password field to api_token — literally the text 'api_token', not a variable. This is Toggl's documented authentication method: the API token acts as the username while the literal string 'api_token' serves as the password in the Basic Auth pair. Create the configuration variable: navigate to Settings → Configuration Variables. Click Add variable, name it TOGGL_API_TOKEN, paste your Toggl API token as the value, and enable the secret toggle. Click Save on the Toggl Track API Resource. Test it by creating a GET query to /me — this returns your user profile including your id and all workspace memberships. Create a second Resource named Toggl Reports API with Base URL https://api.track.toggl.com/reports/api/v3 using the same Basic Auth configuration. The Reports API requires the same credentials as the main API.

For dashboard use, the Toggl Reports API is more efficient than the raw time entries API because it returns pre-aggregated data. Create a query targeting your Toggl Reports API Resource. Set Method to POST (the Reports API v3 uses POST for summary reports despite being a read operation). Set Path to /workspace/{{ retoolContext.configVars.TOGGL_WORKSPACE_ID }}/summary/time_entries. Set the Body type to JSON. The request body specifies your report parameters: add start_date set to {{ formatDate(dateRangePicker.value[0], 'YYYY-MM-DD') }}, end_date set to {{ formatDate(dateRangePicker.value[1], 'YYYY-MM-DD') }}, and grouping set to 'projects' to aggregate by project. Optionally add sub_grouping set to 'users' for a breakdown by user within each project. The Reports API returns a groups array where each group represents a project with its total seconds worked, billable seconds, and sub-groups showing per-user breakdowns. Add a JavaScript transformer to convert the seconds values to hours, join with project and client names using a lookup from the /workspace/{id}/projects endpoint, and format the output for display. Create a second GET query to /workspace/{{ retoolContext.configVars.TOGGL_WORKSPACE_ID }}/projects on the main Toggl Track API Resource to fetch project metadata including project names, client associations, and whether the project is billable.

1// JavaScript transformer for Toggl Reports API summary response
2// Input: data = Reports API summary response object
3// Also references: getProjects.data = project list from main API
4const groups = data.groups || [];
5const projects = getProjects.data || [];
6
7// Build project lookup map
8const projectMap = {};
9projects.forEach(p => {
10  projectMap[p.id] = {
11    name: p.name,
12    client_id: p.client_id,
13    billable: p.billable,
14    color: p.color
15  };
16});
17
18return groups.map(group => {
19  const projectId = group.id;
20  const project = projectMap[projectId] || {};
21  const totalSeconds = group.seconds || 0;
22  const billableSeconds = group.billable_seconds || 0;
23
24  return {
25    project_id: projectId,
26    project_name: project.name || `Project ${projectId}`,
27    is_billable: project.billable || false,
28    total_seconds: totalSeconds,
29    billable_seconds: billableSeconds,
30    non_billable_seconds: totalSeconds - billableSeconds,
31    hours_total: (totalSeconds / 3600).toFixed(2),
32    hours_billable: (billableSeconds / 3600).toFixed(2),
33    hours_display: `${Math.floor(totalSeconds / 3600)}h ${Math.floor((totalSeconds % 3600) / 60)}m`,
34    billable_pct: totalSeconds > 0
35      ? ((billableSeconds / totalSeconds) * 100).toFixed(0) + '%'
36      : '0%'
37  };
38}).sort((a, b) => b.total_seconds - a.total_seconds);

With project aggregates available, build the billing dashboard. Add a DateRangePicker at the top of the canvas defaulting to the current month (first to last day). Add a Select dropdown for client filtering — populate it from a GET query to /workspace/{{ retoolContext.configVars.TOGGL_WORKSPACE_ID }}/clients on the main Toggl API. Drag a Table component and bind it to the Reports transformer output. Configure columns: Project Name, Hours Total, Hours Billable, Hours Non-Billable, and Billable %. Add conditional formatting to highlight rows where billable percentage falls below a threshold (reference a Number input for the minimum billable rate target). Add a Stat component row at the top with three key metrics: Total Hours tracked (sum of all hours), Total Billable Hours (sum of billable hours), and Blended Billable Rate (total billable hours / total hours as a percentage) — compute these in a JavaScript query. Drag a Bar Chart and bind it to the project aggregates, setting the X axis to project_name and adding two data series: hours_billable (green) and non_billable_seconds converted to hours (orange) — this creates a stacked bar showing the split between billable and non-billable work per project at a glance. Add a Line Chart bound to a second Reports API query with grouping set to 'days' to show daily hours trend over the selected period.

1// JavaScript query: period-level summary stats for Stat components
2const projects = getReportSummary.data || [];
3
4const totalSeconds = projects.reduce((s, p) => s + (p.total_seconds || 0), 0);
5const billableSeconds = projects.reduce((s, p) => s + (p.billable_seconds || 0), 0);
6const nonBillableSeconds = totalSeconds - billableSeconds;
7
8return {
9  total_hours: (totalSeconds / 3600).toFixed(1),
10  billable_hours: (billableSeconds / 3600).toFixed(1),
11  non_billable_hours: (nonBillableSeconds / 3600).toFixed(1),
12  billable_rate: totalSeconds > 0
13    ? ((billableSeconds / totalSeconds) * 100).toFixed(0) + '%'
14    : '0%',
15  project_count: projects.length
16};

Supplement the summary view with a detailed time entries panel for auditing individual sessions. Create a GET query targeting /workspace/{{ retoolContext.configVars.TOGGL_WORKSPACE_ID }}/time_entries on the main Toggl Track API Resource. Add URL parameters: start_date and end_date for the date range, and optionally user_ids for team member filtering. The time entries endpoint returns individual sessions with description, project_id, start, stop, duration (in seconds — negative values indicate a currently running timer), billable flag, and tags. Add a JavaScript transformer to enrich entries with project names from the projects lookup and format the duration into hours:minutes display strings. Drag a second Table component onto the canvas (place it in a Tab container to keep the layout clean) and bind it to the enriched time entries. Configure the Table with: Description, Project, User, Date, Start, End, Duration, and Billable columns. Add a CSV export button — in Retool, add a Button component with an event handler that triggers a downloadFile action, passing the Table data formatted as CSV. This creates a one-click export of filtered time entries for payroll or invoice documentation. For production agency tools integrating Toggl billing data with project management systems, client portals, and accounting software in Retool, RapidDev's team can architect comprehensive billing operations platforms.

1// JavaScript transformer for raw time entries
2// Adds project names and formats duration for display
3const entries = data || [];
4const projects = getProjects.data || [];
5
6const projectMap = {};
7projects.forEach(p => { projectMap[p.id] = p.name; });
8
9return entries
10  .filter(e => e.duration > 0) // Exclude currently running timers
11  .map(entry => {
12    const durationSec = entry.duration || 0;
13    const hours = Math.floor(durationSec / 3600);
14    const minutes = Math.floor((durationSec % 3600) / 60);
15    const seconds = durationSec % 60;
16
17    return {
18      id: entry.id,
19      description: entry.description || '(no description)',
20      project_name: projectMap[entry.project_id] || 'No Project',
21      project_id: entry.project_id,
22      date: entry.start ? entry.start.substring(0, 10) : '',
23      start_time: entry.start ? new Date(entry.start).toLocaleTimeString() : '',
24      end_time: entry.stop ? new Date(entry.stop).toLocaleTimeString() : '',
25      duration_seconds: durationSec,
26      duration_display: `${hours}h ${String(minutes).padStart(2, '0')}m`,
27      billable: entry.billable ? 'Yes' : 'No',
28      tags: entry.tags?.join(', ') || ''
29    };
30  })
31  .sort((a, b) => new Date(b.date) - new Date(a.date));