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

string

required

Workspace slug identifier

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

string

required

Workspace slug identifier

uuid

required

Project UUID

Request Body

string

required

Cycle name

string

Cycle description

datetime

required

Cycle start date and time (converted to project timezone)

datetime

required

Cycle end date and time (cannot be before start_date)

uuid

User ID of cycle owner (defaults to current user)

string

Timezone for the cycle (e.g., “America/New_York”)

string

External integration source

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

string

required

Workspace slug identifier

uuid

required

Project UUID

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

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

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

uuid

Unique cycle identifier

string

Cycle name

string

Cycle description

datetime

Cycle start date and time (UTC)

datetime

Cycle end date and time (UTC)

uuid

User ID of cycle owner

integer

Total number of work items in the cycle

integer

Number of completed work items

integer

Number of started work items

integer

Number of unstarted work items

integer

Number of backlog work items

integer

Number of cancelled work items

float

Total story point estimates

float

Completed story point estimates

float

Started story point estimates

datetime

Cycle creation timestamp

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"
}

​Cycles API

​Endpoints

​List Cycles

​Path Parameters

​Example Request

​Response

​Create Cycle

​Path Parameters

​Request Body

​Example Request

​Response

​Get Cycle

​Path Parameters

​Example Request

​Update Cycle

​Example Request

​Delete Cycle

​Example Request

​Cycle Issues

​List Cycle Issues

​Example Request

​Add Issues to Cycle

​Request Body

​Example Request

​Remove Issue from Cycle

​Example Request

​Transfer Issues Between Cycles

​Request Body

​Example Request

​Cycle Archive

​Archive Cycle

​Example Request

​List Archived Cycles

​Example Request

​Unarchive Cycle

​Example Request

​Cycle Response Fields

​Validation Rules

​Error Responses

​Cycles Not Enabled

​Invalid Date Range

​Project Not Found

Cycles API

Endpoints

List Cycles

Path Parameters

Example Request

Response

Create Cycle

Path Parameters

Request Body

Example Request

Response

Get Cycle

Path Parameters

Example Request

Update Cycle

Example Request

Delete Cycle

Example Request

Cycle Issues

List Cycle Issues

Example Request

Add Issues to Cycle

Request Body

Example Request

Remove Issue from Cycle

Example Request

Transfer Issues Between Cycles

Request Body

Example Request

Cycle Archive

Archive Cycle

Example Request

List Archived Cycles

Example Request

Unarchive Cycle

Example Request

Cycle Response Fields

Validation Rules

Error Responses

Cycles Not Enabled

Invalid Date Range

Project Not Found