# Toggl Track

Toggl Track is a time tracking tool used by teams and freelancers to log hours, manage projects, and generate reports. The Sling Toggl Track connector extracts data from the Toggl Track REST API v9, supporting user profiles, workspaces, projects, clients, tags, tasks, workspace users, and time entries.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials are accepted:

**Secrets:**

* `api_token` **(required)** -> Your Toggl Track API Token

**Inputs (optional):**

* `anchor_date` -> Starting date for first sync of incremental endpoints (ISO 8601 format, e.g., `2024-01-01T00:00:00Z`). Defaults to 90 days ago (Toggl API maximum lookback).

### Getting Your API Token

1. Log in to [Toggl Track](https://track.toggl.com)
2. Click your profile icon (bottom-left corner)
3. Go to **Profile Settings**
4. Scroll down to **API Token** at the bottom of the page
5. Copy the token (or click to reveal and copy)

{% hint style="warning" %}
**Important:** The API token grants access to all your Toggl Track data. Keep it secure and use a dedicated account for production workloads.
{% endhint %}

### Using `sling conns`

Here are examples of setting a connection named `TOGGL_TRACK`. We must provide the `type=api` property:

{% code overflow="wrap" %}

```bash
sling conns set TOGGL_TRACK type=api spec=toggl-track secrets='{ api_token: your_api_token_here }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export TOGGL_TRACK='{ type: api, spec: toggl-track, secrets: { api_token: "your_api_token_here" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  TOGGL_TRACK:
    type: api
    spec: toggl-track
    secrets:
      api_token: "your_api_token_here"
```

## Replication

Here's an example replication configuration to sync Toggl Track data to a PostgreSQL database:

```yaml
source: TOGGL_TRACK
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: toggl.{stream_name}

streams:
  # sync all endpoints
  '*':
```

**Incremental sync for time entries:**

```yaml
source: TOGGL_TRACK
target: MY_POSTGRES

defaults:
  object: toggl.{stream_name}

streams:
  me:
    mode: full-refresh

  workspaces:
    mode: full-refresh

  projects:
    mode: full-refresh

  clients:
    mode: full-refresh

  tags:
    mode: full-refresh

  tasks:
    mode: full-refresh

  workspace_users:
    mode: full-refresh

  time_entries:
    mode: incremental
    primary_key: [id]
    update_key: at
```

## Endpoints

| Endpoint          | Description                                          | Incremental | Depends On   |
| ----------------- | ---------------------------------------------------- | ----------- | ------------ |
| `me`              | Authenticated user profile                           | No          | —            |
| `workspaces`      | All workspaces for the authenticated user            | No          | —            |
| `projects`        | All projects across workspaces (active and archived) | No          | `workspaces` |
| `clients`         | All clients across workspaces                        | No          | `workspaces` |
| `tags`            | All tags across workspaces                           | No          | `workspaces` |
| `tasks`           | All tasks across workspaces (may require paid plan)  | No          | `workspaces` |
| `workspace_users` | All users in each workspace                          | No          | `workspaces` |
| `time_entries`    | Time entries with incremental sync support           | Yes         | —            |

The connector uses a **queue-based architecture** for workspace-dependent endpoints. The `workspaces` endpoint runs first and populates workspace IDs into a queue, which is consumed by `projects`, `clients`, `tags`, `tasks`, `workspace_users`. The `time_entries` and `me` endpoints are independent and do not depend on the queue.

To discover available endpoints:

```bash
sling conns discover TOGGL_TRACK
```

### Endpoint Details

**`me`** — Returns the authenticated user's profile including name, email, timezone, and default workspace.

**`workspaces`** — Returns all workspaces the user belongs to. Workspace IDs are queued for child endpoints.

**`projects`** — Returns all projects (both active and archived) within each workspace, including client associations, colors, billing status, and time tracking data. Supports page-based pagination.

**`clients`** — Returns all clients within each workspace, including both active and archived clients.

**`tags`** — Returns all tags defined in each workspace.

**`tasks`** — Returns all tasks across workspaces. Note: Tasks may require a paid Toggl plan and will return empty results on free plans. Supports page-based pagination.

**`workspace_users`** — Returns all users in each workspace with their roles and activity status.

**`time_entries`** — Returns time entries for the authenticated user within a date range. Supports incremental sync via the `at` (last modified) timestamp. Uses `start_date` and `end_date` parameters with a maximum 90-day lookback window (Toggl API limitation).

## Incremental Sync

One endpoint supports incremental sync:

**`time_entries`** — Uses `start_date` and `end_date` parameters:

* **First run:** Fetches all time entries from the last 90 days (or since `anchor_date` if provided, max 90 days)
* **Subsequent runs:** Only fetches time entries modified after the last sync timestamp
* **Update key:** `at` (the last-modified timestamp from Toggl)

{% hint style="info" %}
**Toggl API Limitation:** The `start_date` parameter cannot be more than 3 months (90 days) in the past. The connector automatically defaults to a 90-day lookback window.
{% endhint %}

All other endpoints run in full-refresh mode since they return complete datasets without server-side time-based filtering.

## Rate Limiting

The Toggl Track API enforces rate limits:

* **Free plan:** 30 requests per hour
* **Premium plan:** 600 requests per hour

The connector automatically:

* Uses conservative rate limiting (1 request/second with concurrency of 1)
* Retries with exponential backoff on 429 (rate limit) responses, up to 5 attempts with a 10-second base

## Common Use Cases

### Sync All Toggl Data

```yaml
source: TOGGL_TRACK
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: toggl.{stream_name}

streams:
  '*':
```

### Track Time Entries Incrementally

```yaml
source: TOGGL_TRACK
target: MY_POSTGRES

defaults:
  object: toggl.{stream_name}

streams:
  workspaces:
    mode: full-refresh
  projects:
    mode: full-refresh
  clients:
    mode: full-refresh
  time_entries:
    mode: incremental
    primary_key: [id]
    update_key: at
```

### Export Projects and Clients

```yaml
source: TOGGL_TRACK
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: toggl.{stream_name}

streams:
  workspaces:
  projects:
  clients:
```

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/toggl-track.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.