Stop Time Entries in ClickUp

/ ClickUp / By

How to Stop a Time Entry with the ClickUp API

The ClickUp developer platform provides a clear Time Tracking endpoint that lets you stop an active time entry programmatically. This how-to guide walks you through the required URL, headers, body parameters, and responses so you can safely integrate time tracking controls into your own applications.

This tutorial is based entirely on the official Stop a Time Entry endpoint in the ClickUp API reference and is designed for developers who need precise, implementation-ready details.

Overview of the ClickUp Time Tracking Endpoint

The Stop a Time Entry endpoint in the ClickUp API allows you to end a running timer or update the duration and metadata of an existing tracked period. It is part of the Time Tracking API surface and uses a straightforward URL structure and JSON payload.

  • Method: PUT
  • Base URL: https://api.clickup.com/api/v2
  • Endpoint: /team/{team_id}/time_entries/{time_entry_id}

To use this endpoint successfully, you must authenticate with an API token and send valid JSON in the request body, even when you are only stopping the time entry without modifying any other fields.

Prerequisites for Using the ClickUp API

Before you call the Stop a Time Entry endpoint, make sure the following prerequisites are in place within your ClickUp environment and development stack.

Authentication requirements in ClickUp

  • A valid ClickUp API token associated with your workspace.
  • Permissions to manage time tracking for the chosen team and tasks.
  • Secure storage for the token, such as environment variables or a secrets manager.

Your token is sent in the Authorization header of every request. Treat this token as sensitive and never hard-code it in client-side code or public repositories.

Data you need from ClickUp

To stop a time entry, you must know:

  • team_id: The unique identifier of the team (workspace) in ClickUp.
  • time_entry_id: The identifier of the specific time entry you want to stop.

These values are typically obtained from earlier API calls such as listing time entries, or from responses when you create and start a time entry.

Endpoint URL Structure in ClickUp

The Stop a Time Entry URL is constructed by replacing the path parameters with real values:

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

Replace the braces with concrete IDs:

  • {team_id} → your workspace team identifier in ClickUp.
  • {time_entry_id} → the ID for the running or existing time entry.

Be sure that both IDs refer to items that exist and are accessible under your token, otherwise you will receive an error response.

Required Headers for the ClickUp Request

Every request to the Stop a Time Entry endpoint must include specific HTTP headers. These headers ensure that ClickUp understands the request format and can authenticate the caller.

Core headers

  • Authorization: Your ClickUp API token.
    Authorization: <your_clickup_api_token>
  • Content-Type: JSON payload format.
    Content-Type: application/json

If either header is missing or malformed, the API will not process your request correctly.

Request Body for Stopping a Time Entry in ClickUp

Although the primary goal is to stop the timer, the endpoint expects a JSON body. Some properties are required, while others are optional but useful for updating metadata.

Required body fields

  • start (number): Start time of the entry in milliseconds since Unix epoch.
  • end (number): End time in milliseconds since Unix epoch.
  • tid (string): Task ID associated with the time entry.
  • description (string): A descriptive label for the tracked work.

These fields ensure the resulting time block in ClickUp has a defined range and related task.

Optional body fields

  • tags (array of strings): Labels to categorize the time entry.
  • billable (boolean): Marks the time entry as billable or non-billable.
  • duration (number): Duration in milliseconds. When both start and end are provided, duration is implied, but you may still include it as needed.

Use these fields to keep your time records in ClickUp aligned with billing rules and reporting structures.

Step-by-Step: Stop a Time Entry via the ClickUp API

Follow the steps below to send a valid request to the endpoint.

1. Collect necessary identifiers from ClickUp

  1. Determine the team_id for your workspace.
  2. Locate the time_entry_id for the specific tracked session you want to stop.
  3. Confirm the related task ID (tid) and ensure that it exists.

2. Choose an end timestamp

  1. Use the current time in milliseconds since epoch to represent when the timer should stop.
  2. Ensure the end value is greater than start to avoid validation errors.

3. Build the JSON body

Create a JSON object similar to the following structure (be sure to use your real data):

{
  "start": 1710000000000,
  "end": 1710003600000,
  "tid": "task_id_here",
  "description": "Work on feature implementation",
  "tags": ["development", "frontend"],
  "billable": true
}

Adjust description, tags, and billable status to reflect how you want the time to appear inside ClickUp.

4. Send the PUT request to ClickUp

Use your preferred HTTP client or language library to send the request:

  • Set the method to PUT.
  • Set the URL using the full path with your team_id and time_entry_id.
  • Attach the Authorization and Content-Type headers.
  • Include the JSON body in the request.

Understanding the ClickUp API Response

When your request is successful, the endpoint returns a JSON representation of the updated time entry.

Successful status code

  • 200 OK — The time entry has been successfully updated and stopped.

The response body will mirror the time entry resource as stored in ClickUp, including start and end times, description, tags, and billable status.

Error responses from ClickUp

Common error scenarios include:

  • Missing or invalid Authorization header.
  • Invalid team_id or time_entry_id.
  • Incorrectly formatted JSON body.
  • Logical errors, such as an end timestamp that is earlier than start.

Check the HTTP status code and body message to determine why the request failed and adjust your call accordingly.

Best Practices for Using the ClickUp Time Tracking API

To keep your integration reliable and maintainable, follow these best practices when working with time entries in ClickUp.

Validate timestamps before calling ClickUp

  • Always compute start and end in milliseconds and verify that they match expected ranges.
  • Guard against user input errors that could generate negative or zero durations.

Align ClickUp data with your own system

  • Store references to time_entry_id values in your application so you can stop or update them later.
  • Use consistent tags and descriptions to keep reporting clear inside ClickUp.

Secure handling of ClickUp API tokens

  • Do not log tokens in plain text or expose them in client-side JavaScript.
  • Rotate tokens periodically according to your security policies.

Where to Learn More About the ClickUp Endpoint

For the complete and authoritative specification of the Stop a Time Entry endpoint, including all fields and any future updates, consult the official documentation:

If you need broader help planning integrations, optimizing automations, or designing robust workflows around time tracking, you can explore expert consulting resources such as Consultevo to complement what you build on the ClickUp platform.

By following the structure and rules described here, you can reliably stop time entries through the ClickUp API and keep your time tracking data accurate, consistent, and ready for reporting or billing workflows.

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

“`