How to Get Tracked Time with the ClickUp API

The ClickUp API lets you retrieve detailed tracked time entries so you can audit work, build reports, or integrate time data into your own apps. This guide walks you through how to use the Get Tracked Time endpoint step by step, based strictly on the official API reference.

Understanding the ClickUp Tracked Time Endpoint

The Get Tracked Time endpoint returns time entries recorded in workspaces that you can access. You can filter by user, task, date range, and more, then use the results in your reporting or automation workflows.

This endpoint is a GET request to the ClickUp API and supports several query parameters to narrow your search and control pagination.

ClickUp Get Tracked Time Endpoint URL

The base format of the endpoint is:

GET https://api.clickup.com/api/v2/team/{team_id}/time_entries

{team_id} is the ID of the Workspace (team) whose time entries you want to retrieve.

Authentication Requirements for the ClickUp API

To call the tracked time endpoint, you must authenticate against the ClickUp API with a valid personal or app token.

Required Authorization Header

Every request must include an Authorization header:

Authorization: <your_clickup_token>

Use your ClickUp API token as the header value.
Do not expose this token in client-side code or public repos.

The endpoint also typically expects a Content-Type: application/json header, even though it is a GET request.

Query Parameters for ClickUp Time Entries

The Get Tracked Time endpoint supports several query parameters to filter and control the returned results.

Core Filtering Parameters

start_date (optional): Filter time entries with a start time on or after this value, in Unix time (milliseconds).
end_date (optional): Filter time entries with a start time before or on this value, in Unix time (milliseconds).
assignee (optional): Filter by the user ID of the person who logged the time.
task_id (optional): Return only entries associated with a specific task ID.

If you omit start_date and end_date, the ClickUp API returns a default range defined by the endpoint’s standard behavior in the reference.

Pagination Parameters

The API can return many time entries, so pagination is important.

page (optional): The page number to retrieve, starting from 0.
limit (optional): Maximum number of items per page, according to the constraints described in the reference.

Use these parameters to iterate over all time entries without overloading your integration.

Step-by-Step: Call the ClickUp Tracked Time Endpoint

Follow these steps to retrieve tracked time data from the ClickUp API.

1. Get Your Workspace (Team) ID

Use the relevant ClickUp endpoint (for example, the teams endpoint in the API) to list teams.
Locate the id for the Workspace whose time entries you need.
Use that value as {team_id} in the tracked time URL.

2. Build the Request URL with Filters

Construct the URL with the necessary query parameters. For example:

https://api.clickup.com/api/v2/team/123456/time_entries?start_date=1704067200000&end_date=1706745599000&page=0&limit=100

Adjust dates, page, and limit according to your needs. You can add assignee or task_id when needed.

3. Send the HTTP GET Request

Use any HTTP client or library (such as curl, Postman, or your preferred language SDK) to call the ClickUp endpoint. Example with curl:

curl -X GET "https://api.clickup.com/api/v2/team/123456/time_entries?start_date=1704067200000&end_date=1706745599000" \  -H "Authorization: <your_clickup_token>" \  -H "Content-Type: application/json"

4. Handle the Response from the ClickUp API

The response returns JSON with:

An array of time entries.
Linked task information, including task IDs.
Metadata useful for pagination and reporting.

Each entry typically includes:

Entry ID
User (assignee) details
Task ID and references
Start and end times (usually in Unix milliseconds)
Duration and notes where applicable

Parse this JSON in your application to display, aggregate, or store the time data.

Interpreting ClickUp Time Entry Data

Once you receive the JSON payload, you can map each field to your reporting or billing logic.

Common Use Cases

Time reports per user: Sum durations by user ID.
Task-level analysis: Aggregate by task ID to see total time spent.
Billing and invoicing: Use date filters to compute billable time for a period.
Productivity dashboards: Feed data into BI tools or custom dashboards.

Tips for Working with Time Values

Convert Unix milliseconds to readable dates in your language or framework of choice.
Store original Unix values if you need precise calculations or timezone-independent processing.
Be consistent with timezones when comparing ClickUp data to external systems.

Error Handling and Limits in the ClickUp API

The tracked time endpoint contains standard behaviors for HTTP status codes and rate limits as described in the API documentation.

Typical Error Scenarios

401 Unauthorized: Invalid or missing Authorization header.
403 Forbidden: The token does not have permission to view that Workspace or its time entries.
400 Bad Request: Invalid parameter types or malformed query string.

Always log response codes and error messages from the ClickUp API so you can troubleshoot issues quickly.

Rate Limiting Practices

Check headers described in the reference to understand remaining quota.
Implement retries with backoff when you receive rate limit responses.
Batch your requests using date ranges and pagination to minimize calls.

Best Practices for ClickUp Time Integrations

When integrating the tracked time endpoint into your workflows, follow these recommendations.

Designing Reliable ClickUp Integrations

Use environment variables or a secure vault for tokens.
Centralize all ClickUp API calls in a dedicated service or module.
Validate all query parameters before calling the API.

Keeping Data in Sync

Schedule periodic sync jobs for recent time entries (for example, the last 7–30 days).
Use incremental ranges (by date or ID) rather than requesting the entire history at once.
Combine tracked time data with task details for richer reporting.

Official ClickUp Documentation and Further Help

To see the newest fields, constraints, and examples, always refer to the official endpoint reference:

ClickUp Get Tracked Time API reference

If you need strategic guidance on building dashboards, automation, or analytics around this endpoint, you can also explore expert consulting resources such as Consultevo.

By following this guide and the official reference, you can reliably pull tracked time from the ClickUp API and integrate it into billing systems, analytics platforms, or any custom workflow your team requires.

Need Help With ClickUp?

If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.

Get Help

“`

Track Time with ClickUp API