ClickUp

Connect & Ingest data from ClickUp

ClickUp is a project management platform for teams to organize, track, and manage tasks, goals, and time. The Sling ClickUp connector extracts data from both ClickUp REST API versions:

• API v2 — workspaces (teams), spaces, folders, lists, tasks, comments, goals, time entries, tags, custom fields, and members.

• API v3 — Chat (channels, members, followers, messages, replies, reactions, tagged users) and Docs (docs and pages).

ClickUp's v3 API is not a replacement for v2 — it only exposes Chat, Docs, and Attachments. The core project-management hierarchy (teams, spaces, folders, lists, tasks, goals, time entries) remains v2-only. This connector uses both versions side by side, so a single connection covers all endpoints.

CLI Pro Required: APIs require a CLI Pro token or Platform Plan.

Setup

The following credentials are accepted:

Secrets:

• api_key (required) -> Your ClickUp Personal 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 1 year ago.

Getting Your Personal API Token

1. Log in to ClickUp

2. Click your avatar (bottom-left corner)

3. Go to Settings

4. Navigate to Apps in the left sidebar

5. Under API Token, click Generate (or Regenerate if one exists)

6. Copy the token

Important: Personal API tokens grant the same access as your user account. Use a service account with minimal permissions for production workloads.

Using sling conns

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

sling conns set CLICKUP type=api spec=clickup secrets='{ api_key: pk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx }'

Environment Variable

See here to learn more about the .env.sling file.

export CLICKUP='{ type: api, spec: clickup, secrets: { api_key: "pk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }'

Sling Env File YAML

See here to learn more about the sling env.yaml file.

connections:
  CLICKUP:
    type: api
    spec: clickup
    secrets:
      api_key: "pk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Replication

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

source: CLICKUP
target: MY_POSTGRES

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

streams:
  # sync all endpoints
  '*':

Incremental sync for tasks and time entries:

source: CLICKUP
target: MY_POSTGRES

defaults:
  object: clickup.{stream_name}

streams:
  teams:
    mode: full-refresh

  spaces:
    mode: full-refresh

  folders:
    mode: full-refresh

  lists:
    mode: full-refresh

  folderless_lists:
    mode: full-refresh

  tasks:
    mode: incremental
    primary_key: [id]
    update_key: date_updated

  task_comments:
    mode: full-refresh

  goals:
    mode: full-refresh

  time_entries:
    mode: incremental
    primary_key: [id]

  space_tags:
    mode: full-refresh

  custom_fields:
    mode: full-refresh

  list_members:
    mode: full-refresh

Endpoints

Endpoint	Description	Incremental	Depends On
teams	All workspaces (teams) accessible to the authenticated user	No	—
spaces	All spaces within each workspace	No	teams
folders	All folders within each space	No	spaces
lists	All lists within each folder	No	folders
folderless_lists	All lists not in a folder (directly under a space)	No	spaces
tasks	All tasks across all lists with incremental sync	Yes	lists, folderless_lists
task_comments	Comments for each task	No	tasks
goals	All goals for each workspace	No	teams
time_entries	Time tracking entries for each workspace	Yes	teams
space_tags	All tags for each space	No	spaces
custom_fields	Accessible custom fields for each list	No	lists, folderless_lists
list_members	Members with access to each list	No	lists, folderless_lists

API v3 Endpoints

Endpoint	Description	Incremental	Depends On
chat_channels	All chat channels in the workspace	No	—
chat_channel_members	Members of each chat channel	No	chat_channels
chat_channel_followers	Followers of each chat channel	No	chat_channels
chat_messages	Messages in each chat channel	Yes	chat_channels
chat_message_replies	Replies to each chat message	Yes	chat_messages
chat_message_reactions	Reactions on each chat message	No	chat_messages
chat_message_tagged_users	Users tagged in each chat message	No	chat_messages
docs	All Docs in the workspace	Yes	—
doc_pages	All pages (with content) for each Doc	Yes	docs

The connector uses a queue-based architecture to handle ClickUp's hierarchical structure. The teams endpoint runs first and populates team IDs, which are used by spaces, goals, and time_entries. The spaces endpoint populates space IDs for folders, folderless_lists, and space_tags. Both folders and folderless_lists populate list IDs for lists, tasks, custom_fields, and list_members. The tasks endpoint populates task IDs for task_comments.

The v3 endpoints follow the same pattern: chat_channels populates channel IDs for its member, follower, and message endpoints; chat_messages populates message IDs for replies, reactions, and tagged users; and docs populates doc IDs for doc_pages.

Because child endpoints read IDs from a queue, always include the parent stream when selecting a subset of streams. For example, syncing chat_messages alone yields no rows — include chat_channels as well (or use '*').

To discover available endpoints:

sling conns discover CLICKUP

Endpoint Details

teams — Returns all workspaces (called "teams" in the ClickUp API) the authenticated user belongs to. Team IDs are queued for child endpoints.

spaces — Returns all spaces within each workspace, including feature flags, statuses, and privacy settings.

folders — Returns all folders within each space. Folder IDs are queued for the lists endpoint.

lists — Returns all lists within each folder, including status, priority, and task count.

folderless_lists — Returns lists that exist directly under a space (not inside any folder). List IDs are queued for tasks, custom_fields, and list_members.

tasks — Returns all tasks across all lists with full detail: assignees, status, priority, dates, custom fields, tags, and dependencies. Supports incremental sync via date_updated_gt. Task IDs are queued for task_comments.

task_comments — Returns all comments for each task, including comment text, author, and reactions. Returns a 404 continue rule for deleted tasks.

goals — Returns all goals for each workspace, including progress, owners, and due dates.

time_entries — Returns time tracking entries within a configurable date range for each workspace. Supports incremental sync.

space_tags — Returns all tags defined for each space.

custom_fields — Returns all accessible custom field definitions for each list.

list_members — Returns all members with access to each list, including their role and profile information.

chat_channels (v3) — Returns all chat channels in the workspace, including DMs, group DMs, and channels. Channel IDs are queued for the channel member, follower, and message endpoints.

chat_channel_members / chat_channel_followers (v3) — Return the members and followers of each channel. A channel_id column is added to each record so rows can be joined back to chat_channels.

chat_messages (v3) — Returns messages for each channel with content rendered as Markdown. Message IDs are queued for the reply, reaction, and tagged-user endpoints.

chat_message_replies (v3) — Returns threaded replies for each message, including the parent_message reference.

chat_message_reactions (v3) — Returns reactions for each message. Reactions have no ID of their own, so the primary key is the composite message_id + user_id + reaction; a message_id column is added to each record.

chat_message_tagged_users (v3) — Returns users tagged (@-mentioned) in each message, with a message_id column added.

docs (v3) — Returns all Docs in the workspace via the Docs search endpoint. Doc IDs are queued for doc_pages.

doc_pages (v3) — Returns every page of each Doc, including the page body as Markdown in the content field.

Incremental Sync

The following v2 endpoints support incremental sync:

tasks — Uses the date_updated_gt parameter (millisecond epoch timestamp):

• First run: Fetches all tasks modified in the last 365 days (or since anchor_date if provided)

• Subsequent runs: Only fetches tasks modified after the last sync timestamp

time_entries — Uses start_date and end_date parameters:

• First run: Fetches all time entries from the last 365 days (or since anchor_date)

• Subsequent runs: Only fetches time entries created after the last sync timestamp

The v3 Chat and Docs endpoints support incremental sync client-side, using the record timestamp as the update_key:

chat_messages / chat_message_replies — Use date (millisecond epoch) as the update key.

docs / doc_pages — Use date_updated as the update key.

Configure them with mode: incremental and the matching update_key:

streams:
  chat_channels:
  chat_messages:
    mode: incremental
    primary_key: [id]
    update_key: date
  docs:
    mode: incremental
    primary_key: [id]
    update_key: date_updated

All other endpoints run in full-refresh mode since ClickUp does not provide server-side time-based filtering for those resources.

Rate Limiting

The ClickUp API enforces rate limits:

• Standard limit: 100 requests per minute for free plans, higher for paid plans

The connector automatically:

• Uses rate limiting (2 requests/second with concurrency of 3)

• Retries with exponential backoff on 429 (rate limit) responses, up to 5 attempts

• Retries with linear backoff on 5xx server errors, up to 3 attempts

Common Use Cases

Sync All ClickUp Data

source: CLICKUP
target: MY_POSTGRES

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

streams:
  '*':

Sync Tasks Incrementally

source: CLICKUP
target: MY_POSTGRES

defaults:
  object: clickup.{stream_name}

streams:
  teams:
    mode: full-refresh
  spaces:
    mode: full-refresh
  folders:
    mode: full-refresh
  lists:
    mode: full-refresh
  folderless_lists:
    mode: full-refresh
  tasks:
    mode: incremental
    primary_key: [id]
    update_key: date_updated

Extract Task Comments for Analysis

source: CLICKUP
target: MY_POSTGRES

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

streams:
  teams:
  spaces:
  folders:
  lists:
  folderless_lists:
  tasks:
  task_comments:

Track Time Entries

source: CLICKUP
target: MY_POSTGRES

defaults:
  object: clickup.{stream_name}

streams:
  teams:
    mode: full-refresh
  time_entries:
    mode: incremental
    primary_key: [id]

Sync Chat Messages (API v3)

source: CLICKUP
target: MY_POSTGRES

defaults:
  object: clickup.{stream_name}

streams:
  # parent stream is required to populate channel IDs
  chat_channels:
    mode: full-refresh
  chat_messages:
    mode: incremental
    primary_key: [id]
    update_key: date
  chat_message_replies:
    mode: incremental
    primary_key: [id]
    update_key: date
  chat_message_reactions:
    mode: full-refresh

Sync Docs and Page Content (API v3)

source: CLICKUP
target: MY_POSTGRES

defaults:
  object: clickup.{stream_name}

streams:
  docs:
    mode: incremental
    primary_key: [id]
    update_key: date_updated
  doc_pages:
    mode: incremental
    primary_key: [id]
    update_key: date_updated

If you are facing issues connecting, please reach out to us at [e-mail], on discord or open a Github Issue here.