Create Key Results in ClickUp

/ ClickUp / By

How to Create Key Results in ClickUp via API

Using the ClickUp API, you can programmatically create Key Results to support structured OKR tracking, reporting, and automation across your workspaces.

This step-by-step guide explains the HTTP endpoint, required and optional fields, request body format, and common implementation patterns based strictly on the official API reference.

Understanding the ClickUp Key Result Create Endpoint

The ClickUp API exposes a dedicated endpoint to create Key Results inside a specific Workspace and Goal. Each Key Result represents a measurable outcome that rolls up to a broader Goal.

The endpoint follows this structure:

  • HTTP method: POST
  • Base path: /goal/{goal_id}/key_result
  • Authentication: Personal Token in the Authorization header

Before you start, ensure you have:

  • A valid ClickUp API token
  • The goal_id for the Goal where the Key Result will be created
  • Permissions to manage Goals in the chosen Workspace

Required Fields for ClickUp Key Results

When calling the Key Result creation endpoint, several properties are required in the request body. These fields define the basic structure and initial state of the Key Result.

Key required fields include:

  • name: The title of the Key Result.
  • owners: An array of user IDs responsible for the Key Result.
  • type: The measurement type, such as numeric or task-based, depending on your configuration.
  • steps_start: Starting value for progress steps (for numeric type).
  • steps_end: Target value for progress steps (for numeric type).

These properties ensure that each new Key Result in ClickUp has a clear owner, metric, and target threshold.

Optional ClickUp Key Result Properties

The API also supports optional fields to refine how a Key Result behaves and how progress is calculated.

Common optional properties include:

  • description: Additional context or details about the Key Result.
  • unit: A label describing the metric, such as %, revenue, or tickets.
  • can_edit: Flag to control edit permissions for certain users.
  • creator: The user ID for the Key Result creator if you need to specify a different user.
  • task_ids: For task-based Key Results, an array of task IDs associated with this metric.

Including these fields helps you align ClickUp Key Results with your internal OKR conventions and reporting standards.

Authentication for the ClickUp API Request

To call the endpoint successfully, your integration must send the ClickUp token in the HTTP headers. Tokens are scoped to your Workspace permissions.

A standard header configuration includes:

  • Authorization: <your-clickup-api-token>
  • Content-Type: application/json

Never expose your token in client-side code or public repositories. Keep it in secure storage, such as environment variables or a secret manager.

Step-by-Step: Creating a ClickUp Key Result

Follow these steps to create a Key Result through the API.

1. Collect prerequisites from ClickUp

Gather these values before writing your code:

  1. ClickUp API token from your profile or app configuration.
  2. Workspace and Goal IDs where the Key Result will reside.
  3. User IDs for owners and creator if relevant.

2. Build the request URL for ClickUp

Construct the URL using your target Goal ID:

POST https://api.clickup.com/api/v2/goal/<goal_id>/key_result

Replace <goal_id> with the actual identifier from your ClickUp environment.

3. Define the JSON request body

Your JSON payload should include all required fields and any optional data your workflow needs. A simple numeric Key Result might look like this (pseudo-structure, not an exact copy of the reference):

{
  "name": "Increase qualified leads",
  "description": "Track marketing-sourced SQLs this quarter",
  "owners": [12345],
  "type": "number",
  "unit": "leads",
  "steps_start": 0,
  "steps_end": 200
}

Adjust names, owners, and limits to fit your specific ClickUp Goal.

4. Send the POST request to ClickUp

Use your preferred HTTP client or library. The request must include:

  • The fully formed URL with goal_id.
  • Authorization header with your ClickUp token.
  • JSON body containing Key Result details.

On success, the API returns a JSON object representing the new Key Result, including its unique identifier and current progress values.

5. Validate the ClickUp API response

Check the HTTP status code and body to ensure the Key Result was created correctly.

  • 2xx responses: Indicate success, returning the full Key Result data.
  • 4xx responses: Often indicate validation, permission, or payload issues.
  • 5xx responses: Suggest server-side or temporary issues; you may need to retry.

Log the new Key Result ID so you can update or query it later.

Error Handling and Validation for ClickUp Integrations

Robust error handling is essential when automating Key Result creation in ClickUp.

Common validation checks:

  • Ensure name is present and non-empty.
  • Verify owners is a non-empty array of valid user IDs.
  • Confirm steps_start and steps_end are numeric when using numeric types.
  • Make sure your token has access to the Goal and Workspace.

When you receive an error payload, log both the HTTP code and the returned message text to simplify troubleshooting.

Use Cases for Automating ClickUp Key Results

Automating Key Result creation through the ClickUp API supports a variety of workflows:

  • OKR rollout automation: Automatically spin up Key Results whenever a new Goal is created at the start of a quarter.
  • Integration with BI tools: Mirror metrics from analytics platforms into ClickUp as numeric Key Results.
  • Project portfolio management: Attach Key Results to Goals when new strategic initiatives are approved.

These patterns keep objectives aligned without manually configuring each Key Result inside ClickUp.

Best Practices for ClickUp API Design

When designing integrations that create Key Results, follow these guidelines:

  • Use consistent naming: Align Key Result names with your organization’s OKR templates.
  • Limit owner lists: Assign a small number of owners so responsibility for each item in ClickUp is clear.
  • Centralize configuration: Store mapping between external systems and ClickUp Goals or Workspaces in one place.
  • Rate limit awareness: Respect API limits by batching and spacing requests where necessary.

These practices help you maintain a stable, maintainable integration that scales as your use of ClickUp grows.

Official ClickUp API Reference and Further Help

For the definitive parameter list, constraints, and real-time updates to the endpoint behavior, refer directly to the official documentation:

ClickUp Create Key Result API reference

If you need expert support for planning or implementing complex ClickUp API integrations, you can also work with specialized consultants such as Consultevo, who help teams design scalable workflows and technical architectures.

By following this guide and the official reference together, you can confidently create and manage Key Results in ClickUp programmatically, ensuring your OKR process remains consistent, measurable, and tightly integrated with your broader tool stack.

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

“`

Verified by MonsterInsights