Skip to main content
Version: v2 (current)

ClickUp Integration with PanDev Metrics

import IdealImage from "@theme/IdealImage"; import Head from "@docusaurus/Head";

TL;DR. This guide connects ClickUp to PanDev Metrics in about 10 minutes. You will generate a Personal API Token in ClickUp, paste it into Settings → Integrations → ClickUp, pick the workspaces and spaces to monitor, and verify that tasks, statuses, and worklog start flowing into your dashboards. Audience: admin.

Before you begin​

  • PanDev Metrics is up and running (Cloud workspace or on-prem instance)
  • Admin access to your PanDev Metrics tenant
  • A ClickUp user with Admin or Workspace Owner role on the workspaces you want to track — admin rights are required because PanDev Metrics registers webhooks during connect
  • For on-prem PanDev Metrics: outbound 443 to api.clickup.com
  • For ClickUp to reach an on-prem PanDev Metrics deployment: the PanDev Metrics host must be reachable from ClickUp at the public webhook URL

:::tip Use a service account Create a dedicated ClickUp user (for example pandev-metrics-bot) and add it to the relevant workspaces with admin rights. This keeps automated webhook activity separate from human history and survives staff turnover. :::

Step 1 — Generate a Personal API Token in ClickUp​

PanDev Metrics authenticates as the service user with a Personal API Token (the simplest auth flow for ClickUp — no OAuth callback needed).

  1. Sign in to ClickUp as the service account.
  2. Select your avatar in the top-right → Settings.
  3. Open My Settings → Apps (the section is labeled Apps or API, depending on plan).
  4. Under API Token, select Generate (or Regenerate if one already exists).
  5. Copy the token immediately — it starts with pk_… and ClickUp does not show it again.

:::warning Keep the token private The Personal API Token grants the same access the service user has. Store it in a secrets manager. :::

Step 2 — Open the ClickUp integration screen in PanDev Metrics​

Sign in to PanDev Metrics as a workspace admin and open Settings → Integrations → ClickUp.

Toggle Enable integration with ClickUp.

Step 3 — Enter the API token​

Fill in the form:

FieldValue
API TokenThe pk_… value from Step 1

Select Check connection. PanDev Metrics calls GET /api/v2/team on ClickUp and reports the authenticated user plus the list of workspaces available to the token.

When the check passes, select Save.

Step 4 — Pick workspaces and spaces to monitor​

After saving, PanDev Metrics shows the list of ClickUp workspaces, spaces, and folders visible to the service account. Select the spaces you want to analyse and save.

PanDev Metrics starts a one-time backfill of the last 90 days of tasks, statuses, and worklog entries.

Step 5 — Verify webhook registration​

PanDev Metrics registers ClickUp webhooks automatically. To confirm, open ClickUp → Settings → Integrations → Webhooks for any selected workspace. You should see one or more hooks pointing at the PanDev Metrics ingest URL.

Recent deliveries should return HTTP 200 within seconds. PanDev Metrics also runs a reconciliation poll every 15 minutes to catch any missed deliveries.

Verify​

Open Settings → Integrations → ClickUp in PanDev Metrics. You should see:

  • A green Connected badge
  • The count of selected workspaces and spaces
  • The timestamp of the Last sync (no older than 30 minutes once backfill completes)

Then open a dashboard with a task-tracker widget and confirm that:

  • Recent ClickUp tasks appear next to commits
  • Task statuses match ClickUp (Open / In Progress / Closed, plus your custom statuses)
  • IDE time is attributed to tasks whose ClickUp ID appears in branch names or commit messages (for example CU-abc123)

To force a fresh poll, select Sync now on the integration tile.

What gets synced​

PanDev Metrics ingests a focused slice of ClickUp data — no attachments, no comment bodies by default.

SourceDirectionWhat is stored
Task fieldsPull + webhookID, name, status, status group, priority, assignee, creator, list, folder, space, tags, due date, story points / estimate
Status transitionsWebhookFrom, to, timestamp, actor — used for cycle time and time-in-status
Worklog (Time Tracked)Webhook + pullAuthor, start, duration, task ID — used to enrich IDE-based time tracking
Sprints (if Sprints ClickApp is enabled)PullSprint id, name, start / end dates
UsersPullClickUp user id, display name, email — matched against PanDev Metrics employees

Attachments, custom-field values (beyond mapping basics), and comment bodies are not stored.

Troubleshooting​

Check connection returns "401 Unauthorized"

The API token is wrong, expired, or was regenerated. Open ClickUp → My Settings → Apps, generate a fresh token, and paste it into PanDev Metrics. Tokens cannot be reused across users — the new value replaces the old one for the service account.

Connection works but no tasks appear after 30 minutes

The service user is not a member of the selected spaces, or the backfill is still running for a large workspace. Confirm membership in ClickUp → Workspace settings → People and select Sync now on the integration tile.

Webhook deliveries fail with timeout

ClickUp can't reach the PanDev Metrics webhook URL. For on-prem PanDev Metrics, confirm the host is reachable from ClickUp on its public URL. From any host with general internet access, run curl -I <pandev-public-url> — it must return an HTTP response, not a connection error.

Worklog entries do not appear

The ClickUp Time Tracking ClickApp is disabled on the workspace, or the service user lacks read access to time entries. Enable Time Tracking in ClickUp → Workspace settings → ClickApps, then Sync now in PanDev Metrics.

Custom statuses always map to "UNDEFINED"

PanDev Metrics maps statuses by status type (Open / Custom / Closed) rather than by name. Open the ClickUp space, edit each custom status, and set its Type to In Progress or Closed as appropriate. PanDev Metrics re-reads the mapping on the next sync.

FAQ​

Are ClickUp custom fields included?​

PanDev Metrics reads the standard fields (status, priority, assignee, tags, due date, story points). Arbitrary custom fields are not synced by default. If you need a specific custom field on dashboards, contact support — most can be added on request.

What are the minimum ClickUp permissions?​

The service user needs Admin role on the workspace because PanDev Metrics registers webhooks during connect. Member-level access can read tasks but cannot create webhooks, which would force a polling-only fallback.

Does PanDev Metrics work with ClickUp's free plan?​

Yes. The integration uses the standard ClickUp API v2 and Personal API Tokens, both available on the free plan. Webhooks are also free. Some features depend on paid ClickApps (Sprints, Time Tracking) — disable those features in PanDev Metrics if you don't have them.

Yes. ClickUp assigns each task a short ID like abc1d2. Add the prefix CU- (configurable) and the task ID to your branch name, commit message, or pull request title — feature/CU-abc1d2 - description. PanDev Metrics extracts the ID and joins it with ClickUp data on the dashboards.

Will the integration write to ClickUp?​

PanDev Metrics writes IDE-based worklog entries to the Time Tracked field when automatic worklog mode is enabled. In read-only mode it performs no writes. Issue status, assignee, and comments are never modified.

Can I rotate the Personal API Token?​

Yes. Generate a new token in ClickUp, then open Settings → Integrations → ClickUp → Update token in PanDev Metrics. Webhooks stay registered.

Can I connect multiple ClickUp workspaces?​

Yes. A single Personal API Token gives access to every workspace the service user belongs to. Toggle workspaces on or off in PanDev Metrics at any time.

How long does the initial backfill take?​

PanDev Metrics backfills the last 90 days of tasks and worklog when you activate the integration. For 10k tasks this typically takes 5-15 minutes; very large workspaces (100k+ tasks) can take an hour or more.

Next steps​