Skip to main content

​
Cycles API

Cycles represent time-boxed iterations or sprints in Plane projects. This API allows you to create, manage, and track cycles and their associated work items.

​
Endpoints

​
List Cycles

GET
Retrieve all cycles in a project.

​
Path Parameters

​
slug
string
required
Workspace slug identifier
​
project_id
uuid
required
Project UUID

​
Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/" \
  -H "X-Api-Key: your_api_key"

​
Response

[
  {
    "id": "450e8400-e29b-41d4-a716-446655440000",
    "name": "Sprint 24",
    "description": "Q1 2024 Sprint 24",
    "start_date": "2024-03-11T00:00:00Z",
    "end_date": "2024-03-24T23:59:59Z",
    "owned_by": "350e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "total_issues": 42,
    "completed_issues": 28,
    "started_issues": 10,
    "unstarted_issues": 4,
    "backlog_issues": 0,
    "cancelled_issues": 0,
    "total_estimates": 89.0,
    "completed_estimates": 56.0,
    "started_estimates": 25.0,
    "created_at": "2024-03-01T10:00:00Z",
    "updated_at": "2024-03-09T14:30:00Z"
  }
]

​
Create Cycle

POST
Create a new cycle in a project.
Cycles must be enabled for the project (cycle_view: true) before creating cycles.

​
Path Parameters

​
slug
string
required
Workspace slug identifier
​
project_id
uuid
required
Project UUID

​
Request Body

​
name
string
required
Cycle name
​
description
string
Cycle description
​
start_date
datetime
required
Cycle start date and time (converted to project timezone)
​
end_date
datetime
required
Cycle end date and time (cannot be before start_date)
​
owned_by
uuid
User ID of cycle owner (defaults to current user)
​
timezone
string
Timezone for the cycle (e.g., “America/New_York”)
​
external_source
string
External integration source
​
external_id
string
External system identifier

​
Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 25",
    "description": "Q1 2024 Sprint 25",
    "start_date": "2024-03-25T00:00:00",
    "end_date": "2024-04-07T23:59:59",
    "owned_by": "350e8400-e29b-41d4-a716-446655440000"
  }'

​
Response

{
  "id": "460e8400-e29b-41d4-a716-446655440000",
  "name": "Sprint 25",
  "description": "Q1 2024 Sprint 25",
  "start_date": "2024-03-25T04:00:00Z",
  "end_date": "2024-04-08T03:59:59Z",
  "owned_by": "350e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_issues": 0,
  "completed_issues": 0,
  "created_at": "2024-03-09T15:30:00Z",
  "updated_at": "2024-03-09T15:30:00Z"
}

​
Get Cycle

GET
Retrieve a specific cycle by ID.

​
Path Parameters

​
slug
string
required
Workspace slug identifier
​
project_id
uuid
required
Project UUID
​
pk
uuid
required
Cycle UUID

​
Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key"

​
Update Cycle

PATCH
Update a cycle’s properties.

​
Example Request

curl -X PATCH "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 24 - Extended",
    "end_date": "2024-03-26T23:59:59"
  }'

​
Delete Cycle

DELETE
Delete a cycle permanently.

​
Example Request

curl -X DELETE "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key"

​
Cycle Issues

​
List Cycle Issues

GET
Retrieve all work items assigned to a cycle.

​
Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/cycle-issues/" \
  -H "X-Api-Key: your_api_key"

​
Add Issues to Cycle

POST
Assign work items to a cycle in bulk.

​
Request Body

​
issues
array
required
Array of issue UUIDs to add to the cycle

​
Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/cycle-issues/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "issues": [
      "650e8400-e29b-41d4-a716-446655440000",
      "660e8400-e29b-41d4-a716-446655440000"
    ]
  }'

​
Remove Issue from Cycle

DELETE
Remove a work item from a cycle.

​
Example Request

curl -X DELETE "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/cycle-issues/650e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key"

​
Transfer Issues Between Cycles

POST
Move all issues from one cycle to another.

​
Request Body

​
new_cycle_id
uuid
required
Target cycle UUID to transfer issues to

​
Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/transfer-issues/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "new_cycle_id": "460e8400-e29b-41d4-a716-446655440000"
  }'

​
Cycle Archive

​
Archive Cycle

POST
Archive a cycle to remove it from active cycle lists.

​
Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/cycles/450e8400-e29b-41d4-a716-446655440000/archive/" \
  -H "X-Api-Key: your_api_key"

​
List Archived Cycles

GET
Retrieve all archived cycles in a project.

​
Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/archived-cycles/" \
  -H "X-Api-Key: your_api_key"

​
Unarchive Cycle

DELETE
Restore an archived cycle.

​
Example Request

curl -X DELETE "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/archived-cycles/450e8400-e29b-41d4-a716-446655440000/unarchive/" \
  -H "X-Api-Key: your_api_key"

​
Cycle Response Fields

​
id
uuid
Unique cycle identifier
​
name
string
Cycle name
​
description
string
Cycle description
​
start_date
datetime
Cycle start date and time (UTC)
​
end_date
datetime
Cycle end date and time (UTC)
​
owned_by
uuid
User ID of cycle owner
​
total_issues
integer
Total number of work items in the cycle
​
completed_issues
integer
Number of completed work items
​
started_issues
integer
Number of started work items
​
unstarted_issues
integer
Number of unstarted work items
​
backlog_issues
integer
Number of backlog work items
​
cancelled_issues
integer
Number of cancelled work items
​
total_estimates
float
Total story point estimates
​
completed_estimates
float
Completed story point estimates
​
started_estimates
float
Started story point estimates
​
created_at
datetime
Cycle creation timestamp
​
updated_at
datetime
Last update timestamp

​
Validation Rules

  • Project Cycles Enabled: Cycles must be enabled for the project (cycle_view: true)
  • Date Range: start_date cannot exceed end_date
  • Timezone Conversion: Dates are automatically converted to UTC based on project timezone
  • Owner: If not specified, defaults to the current authenticated user

​
Error Responses

​
Cycles Not Enabled

{
  "error": "Cycles are not enabled for this project"
}

​
Invalid Date Range

{
  "error": "Start date cannot exceed end date"
}

​
Project Not Found

{
  "error": "Project not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us