---

name: clickup-performance-tuning description: >- Analyze and improve ClickUp throughput and freshness with endpoint-aware pagination, bounded concurrency, caching, and webhook invalidation. Use when ClickUp syncs are slow or rate constrained. Trigger with "ClickUp performance", "speed up ClickUp sync", or "ClickUp pagination". argument-hint: "[sync-path] [baseline-window]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.8.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags:

• saas
• clickup
• performance model: inherit effort: high compatibility: Designed for Claude Code; benchmarks require authorized synthetic or non-sensitive data

---

ClickUp Throughput and Freshness Tuning

Overview

Tune measured bottlenecks while preserving completeness, ordering, freshness, and rate safety. Reject optimizations that improve speed by dropping provider records.

Prerequisites

• A baseline of request volume, p50/p95 latency, page counts, payload sizes, 429s, queue age, and reconciliation
• Completeness and freshness assertions plus synthetic load fixtures
• Known endpoint-specific pagination and current token limit

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Get Tasks returns 100 tasks per zero-based page and has explicit filters for closed tasks and subtasks; use include_timl for Tasks in Multiple Lists.
• Task comments use start plus start_id after the first 25 newest comments.
• The v2 task surface does not offer a general fields-selection parameter; do not invent one.
• Webhook invalidation can reduce polling, but delivery must be signed, idempotent, and reconciled.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Measure each endpoint and business operation before changing caching or concurrency.
2. Verify pagination termination, ordering, filters, and reconciliation on boundary fixtures.
3. Coalesce duplicate reads and cache stable hierarchy metadata with explicit invalidation.
4. Set concurrency from the token's current remaining/reset headers and downstream queue capacity.
5. Use webhooks to invalidate or enqueue targeted reads while retaining a reconciliation sweep.
6. Benchmark the same cohort and reject improvements that lose records or violate freshness.

Approval Boundaries

Do not raise concurrency, lengthen freshness windows, omit pages, or replace reconciliation with webhooks without owner-approved SLOs.

Output

Return baseline/after latency and requests, completeness, freshness, cache hit rate, concurrency, 429s, and rollback decision.

Error Handling

Condition	Response
Page loop repeats or skips records	Stop and fix cursor/page state before tuning.
Cache serves stale task state	Invalidate and roll back the cache change.
429 rate increases	Reduce concurrency and honor reset headers.
Webhook gap appears	Restore reconciliation reads and repair event handling.

Examples

The example below is a redacted operator receipt; it contains no task text, member data, credential, or webhook secret.

cohort=500-tasks; complete=yes; requests=-31%; p95=-22%; 429=0; freshness=within-slo

Resources

• Skill-specific official documentation
• Get Tasks reference
• Authentication
• Rate limits