The ClickUp Goals API allows developers to create and manage goals within a Workspace. Goals can track progress toward objectives using targets based on numbers, currency, percentages, or task completion. The API supports creating goals, adding key results and targets, updating progress, and retrieving goal details. This is useful for building OKR tracking and reporting integrations.
openapi: 3.1.0
info:
title: ClickUp Goals API
description: >-
The ClickUp Goals API allows developers to create and manage goals
within a Workspace. Goals can track progress toward objectives using
targets based on numbers, currency, percentages, or task completion.
The API supports creating goals, adding key results and targets,
updating progress, and retrieving goal details. This is useful for
building OKR tracking and reporting integrations.
version: '2.0'
contact:
name: ClickUp Support
url: https://help.clickup.com
termsOfService: https://clickup.com/terms
externalDocs:
description: ClickUp Goals API Documentation
url: https://developer.clickup.com/reference/get-goals
servers:
- url: https://api.clickup.com/api/v2
description: ClickUp API v2 Production Server
tags:
- name: Goals
description: >-
Operations for managing Goals and Key Results within a ClickUp Workspace.
security:
- bearerAuth: []
paths:
/team/{team_id}/goal:
get:
operationId: getGoals
summary: Get goals
description: >-
Retrieves all Goals within a Workspace, including their key results
and progress information.
tags:
- Goals
parameters:
- $ref: '#/components/parameters/teamId'
- name: include_completed
in: query
description: >-
Include completed Goals in the response.
schema:
type: boolean
default: false
responses:
'200':
description: Successfully retrieved goals
content:
application/json:
schema:
type: object
properties:
goals:
type: array
items:
$ref: '#/components/schemas/Goal'
folders:
type: array
items:
$ref: '#/components/schemas/GoalFolder'
'401':
description: Unauthorized
post:
operationId: createGoal
summary: Create a goal
description: >-
Creates a new Goal within a Workspace. Goals can include a name,
due date, description, assignees, and color.
tags:
- Goals
parameters:
- $ref: '#/components/parameters/teamId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGoalRequest'
responses:
'200':
description: Goal created successfully
content:
application/json:
schema:
type: object
properties:
goal:
$ref: '#/components/schemas/Goal'
'400':
description: Bad request
'401':
description: Unauthorized
/goal/{goal_id}:
get:
operationId: getGoal
summary: Get a goal
description: >-
Retrieves details of a specific Goal, including its key results,
targets, and progress.
tags:
- Goals
parameters:
- $ref: '#/components/parameters/goalId'
responses:
'200':
description: Successfully retrieved goal
content:
application/json:
schema:
type: object
properties:
goal:
$ref: '#/components/schemas/Goal'
'401':
description: Unauthorized
'404':
description: Goal not found
put:
operationId: updateGoal
summary: Update a goal
description: >-
Updates the properties of an existing Goal.
tags:
- Goals
parameters:
- $ref: '#/components/parameters/goalId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGoalRequest'
responses:
'200':
description: Goal updated successfully
content:
application/json:
schema:
type: object
properties:
goal:
$ref: '#/components/schemas/Goal'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Goal not found
delete:
operationId: deleteGoal
summary: Delete a goal
description: >-
Permanently deletes a Goal and all of its key results. This action
cannot be undone.
tags:
- Goals
parameters:
- $ref: '#/components/parameters/goalId'
responses:
'200':
description: Goal deleted successfully
'401':
description: Unauthorized
'404':
description: Goal not found
/goal/{goal_id}/key_result:
post:
operationId: createKeyResult
summary: Create a key result
description: >-
Creates a new Key Result (target) within a Goal. Key Results can
be of type number, currency, boolean, percentage, or automatic
(based on task completion).
tags:
- Goals
parameters:
- $ref: '#/components/parameters/goalId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateKeyResultRequest'
responses:
'200':
description: Key result created successfully
content:
application/json:
schema:
type: object
properties:
key_result:
$ref: '#/components/schemas/KeyResult'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Goal not found
/key_result/{key_result_id}:
put:
operationId: editKeyResult
summary: Edit a key result
description: >-
Updates the properties and progress of an existing Key Result.
tags:
- Goals
parameters:
- $ref: '#/components/parameters/keyResultId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateKeyResultRequest'
responses:
'200':
description: Key result updated successfully
content:
application/json:
schema:
type: object
properties:
key_result:
$ref: '#/components/schemas/KeyResult'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Key result not found
delete:
operationId: deleteKeyResult
summary: Delete a key result
description: >-
Permanently deletes a Key Result from a Goal.
tags:
- Goals
parameters:
- $ref: '#/components/parameters/keyResultId'
responses:
'200':
description: Key result deleted successfully
'401':
description: Unauthorized
'404':
description: Key result not found
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
ClickUp personal API token or OAuth access token.
parameters:
teamId:
name: team_id
in: path
required: true
description: >-
The unique identifier of the Workspace (team).
schema:
type: integer
goalId:
name: goal_id
in: path
required: true
description: >-
The unique identifier of the Goal.
schema:
type: string
keyResultId:
name: key_result_id
in: path
required: true
description: >-
The unique identifier of the Key Result.
schema:
type: string
schemas:
Goal:
type: object
description: >-
A Goal object representing an objective with trackable key results.
properties:
id:
type: string
description: >-
The unique identifier of the Goal.
name:
type: string
description: >-
The name of the Goal.
team_id:
type: string
description: >-
The Workspace ID.
date_created:
type: string
description: >-
Unix timestamp when the Goal was created.
start_date:
type: string
nullable: true
description: >-
Unix timestamp for the Goal start date.
due_date:
type: string
description: >-
Unix timestamp for the Goal due date.
description:
type: string
nullable: true
description: >-
The description of the Goal.
private:
type: boolean
description: >-
Whether the Goal is private.
archived:
type: boolean
description: >-
Whether the Goal is archived.
creator:
type: integer
description: >-
The user ID of the Goal creator.
color:
type: string
description: >-
The hex color code of the Goal.
pretty_id:
type: string
description: >-
The human-readable ID of the Goal.
multiple_owners:
type: boolean
description: >-
Whether the Goal has multiple owners.
folder_id:
type: string
nullable: true
description: >-
The Goal Folder ID, if the Goal is in a folder.
members:
type: array
items:
type: object
description: >-
Members associated with the Goal.
owners:
type: array
items:
type: object
description: >-
Owners of the Goal.
key_results:
type: array
items:
$ref: '#/components/schemas/KeyResult'
description: >-
Key Results (targets) associated with the Goal.
percent_completed:
type: integer
minimum: 0
maximum: 100
description: >-
The overall completion percentage of the Goal.
history:
type: array
items:
type: object
description: >-
History of changes to the Goal.
pretty_url:
type: string
format: uri
description: >-
The URL to the Goal in the ClickUp web application.
KeyResult:
type: object
description: >-
A Key Result (target) within a Goal.
properties:
id:
type: string
description: >-
The unique identifier of the Key Result.
goal_id:
type: string
description: >-
The Goal ID this Key Result belongs to.
name:
type: string
description: >-
The name of the Key Result.
creator:
type: integer
description: >-
The user ID of the Key Result creator.
type:
type: string
enum:
- number
- currency
- boolean
- percentage
- automatic
description: >-
The type of the Key Result target.
date_created:
type: string
description: >-
Unix timestamp when the Key Result was created.
goal_pretty_id:
type: string
description: >-
The human-readable ID of the parent Goal.
percent_completed:
type: integer
minimum: 0
maximum: 100
description: >-
The completion percentage of the Key Result.
completed:
type: boolean
description: >-
Whether the Key Result is completed.
task_ids:
type: array
items:
type: string
description: >-
Task IDs linked to this Key Result for automatic tracking.
list_ids:
type: array
items:
type: string
description: >-
List IDs linked to this Key Result for automatic tracking.
owners:
type: array
items:
type: object
description: >-
Owners of the Key Result.
steps_start:
type: number
description: >-
The starting value of the Key Result.
steps_end:
type: number
description: >-
The target end value of the Key Result.
steps_current:
type: number
description: >-
The current value of the Key Result.
unit:
type: string
description: >-
The unit of measurement for currency type Key Results.
last_action:
type: object
description: >-
Details of the last action performed on the Key Result.
GoalFolder:
type: object
description: >-
A folder for organizing Goals.
properties:
id:
type: string
description: >-
The folder ID.
name:
type: string
description: >-
The folder name.
team_id:
type: string
description: >-
The Workspace ID.
private:
type: boolean
description: >-
Whether the folder is private.
date_created:
type: string
description: >-
Unix timestamp when the folder was created.
creator:
type: integer
description: >-
The user ID of the folder creator.
goal_count:
type: integer
description: >-
The number of Goals in the folder.
goals:
type: array
items:
$ref: '#/components/schemas/Goal'
description: >-
Goals within the folder.
CreateGoalRequest:
type: object
required:
- name
- due_date
description: >-
Request body for creating a new Goal.
properties:
name:
type: string
description: >-
The name of the Goal.
due_date:
type: integer
format: int64
description: >-
Due date as Unix timestamp in milliseconds.
description:
type: string
description: >-
The description of the Goal.
multiple_owners:
type: boolean
description: >-
Whether the Goal has multiple owners.
owners:
type: array
items:
type: integer
description: >-
Array of user IDs to set as owners.
color:
type: string
description: >-
The hex color code of the Goal.
UpdateGoalRequest:
type: object
description: >-
Request body for updating an existing Goal.
properties:
name:
type: string
description: >-
The updated name of the Goal.
due_date:
type: integer
format: int64
description: >-
Updated due date as Unix timestamp in milliseconds.
description:
type: string
description: >-
The updated description.
rem_owners:
type: array
items:
type: integer
description: >-
User IDs to remove as owners.
add_owners:
type: array
items:
type: integer
description: >-
User IDs to add as owners.
color:
type: string
description: >-
The updated hex color code.
CreateKeyResultRequest:
type: object
required:
- name
- type
description: >-
Request body for creating a new Key Result.
properties:
name:
type: string
description: >-
The name of the Key Result.
owners:
type: array
items:
type: integer
description: >-
User IDs to set as owners.
type:
type: string
enum:
- number
- currency
- boolean
- percentage
- automatic
description: >-
The type of the Key Result target.
steps_start:
type: number
description: >-
The starting value.
steps_end:
type: number
description: >-
The target end value.
unit:
type: string
description: >-
The unit of measurement for currency type.
task_ids:
type: array
items:
type: string
description: >-
Task IDs to link for automatic tracking.
list_ids:
type: array
items:
type: string
description: >-
List IDs to link for automatic tracking.
UpdateKeyResultRequest:
type: object
description: >-
Request body for updating an existing Key Result.
properties:
steps_current:
type: number
description: >-
The current progress value.
note:
type: string
description: >-
A note to add with the update.