List cycles

GET/api/v2/workspaces/{slug}/projects/{project_id}/cycles/

Return the cycles in a project as a paginated page. Use it to build a sprint picker, to find the cycle covering a date range, or to reconcile cycles you imported from another tracker.

Filters combine with AND. For example, ?owned_by_id=…&search=sprint returns only cycles that match both.

Path parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

project_id:requiredstring (uuid)

The project whose cycles you want.

Query parameters

Filters

name:optionalstring

Return only cycles whose name matches exactly, ignoring case. For a partial match, use search.

owned_by_id:optionalstring (uuid)

Return only cycles owned by this user. To build a "my cycles" view, pass the authenticated user's id. Plane assigns ownership, so you can filter on it but not set it.

external_id:optionalstring

Return only cycles whose external_id matches exactly. Pair it with external_source when the same identifier could come from more than one system.

external_source:optionalstring

Return only cycles imported from this source, for example jira.

is_archived:optionalboolean

true returns only archived cycles. false returns only active cycles, the same set as the default.

include_archived:optionalboolean

true returns archived and active cycles together. Without it, the list hides archived cycles. When you also pass is_archived, is_archived decides the result.

Search

search:optionalstring

Free-text search term matched against the cycle.

Ordering

order_by:optionalstring

Field to sort by. Prefix with - for descending.

sort_order / -sort_order: the project's manual cycle ordering
created_at / -created_at: oldest first or newest first
id / -id

Pagination

per_page:optionalinteger

Page size. Defaults to 50, maximum 200.

offset:optionalinteger

Number of rows to skip from the start of the result set. Maximum 10000. Past that, switch to cursor pagination.

paginate:optionalstring

Set to cursor to switch from the default offset envelope to the keyset envelope, which skips the COUNT query. The response then has next_cursor and has_more instead of next, previous, and total_count. Pass next_cursor back as cursor to get the next page. Use it for deep traversal, where offset paging gets expensive.

count:optionalboolean

Defaults to true. Set to false to skip the COUNT(*) behind total_count. The envelope then leaves out total_count. Use it when you only need the rows.

Archived cycles are hidden by default

The list leaves out cycles with archived_at set unless you pass is_archived or include_archived. Send true or false in lowercase. Neither parameter is validated. include_archived widens the list only for true. Any is_archived value other than true or false lifts the default filter, so archived and active cycles come back together.

Bad enum values fail silently

order_by and paginate are not validated against their allowed values. An unrecognized order_by falls back to the default cycle ordering, and any paginate value other than cursor uses offset pagination. A typo shows up as an unexpected sort order or envelope, not an error, so check your spelling.

Response shaping

fields:optionalstring

Comma-separated list of fields to return on each row. Fields you don't request are left out of the response instead of coming back as null, so a missing key means you didn't ask for it and null means the value is null. id is always included, whether or not you name it.

Pass all to get every requestable field. An unknown field name returns 400 with the list of valid names and the closest match, so a typo is caught instead of being silently ignored.

Requestable here: archived_at, backlog_issues, cancelled_issues, completed_issues, created_at, created_by_id, description, end_date, external_id, external_source, id, logo_props, name, owned_by_id, progress_snapshot, sort_order, start_date, started_issues, timezone, total_issues, unstarted_issues, updated_at, updated_by_id.

List rows leave out the six progress counts (total_issues, backlog_issues, unstarted_issues, started_issues, completed_issues, cancelled_issues). Name them here, or pass all, to get them. See Progress counts.

See Sparse fields.

expand:optionalstring

Comma-separated relations to embed alongside the ids: owned_by (the cycle owner).

Expanded objects get their own key: ?expand=state keeps state_id and adds a state object next to it, so an id is never replaced by an object. An unknown value returns 400.

?fields= and ?expand= take separate sets of names. Relation names aren't valid in ?fields=, field names aren't valid in ?expand=, and field filtering never removes an expanded object: ?fields=id,name&expand=state returns id, name and state. See Expanding relations.

Scopes

projects.cycles:read

Errors

Status	Code	Cause
`401`	`unauthorized`	Missing or invalid credentials.
`402`	`payment_required`	The feature this endpoint belongs to isn't enabled on your plan, or is switched off.
`403`	`forbidden`	Your role or token scope can't read cycles in this project.
`404`	`not_found`	No such workspace or project, or it's outside your tenant.
`406`	`not_acceptable`	The `Accept` header asks for a representation the API can't produce.
`429`	`rate_limited`	Throttled. Honor the `Retry-After` header before retrying.

List cycles

bash

curl -X GET \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/cycles/?per_page=50&order_by=-created_at" \
  -H "X-Api-Key: $PLANE_API_KEY"

python

import requests

response = requests.get(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/cycles/",
    headers={"X-Api-Key": "your-api-key"},
    params={"per_page": 50, "order_by": "-created_at"},
)
print(response.json())

javascript

const params = new URLSearchParams({ per_page: "50", order_by: "-created_at" });
const response = await fetch(
  `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/cycles/?${params}`,
  {
    headers: { "X-Api-Key": "your-api-key" },
  },
);
const data = await response.json();

Response200

json

{
  "data": [
    {
      "id": "7c1f9a4e-3b6d-4a52-8f0c-2d9e6b18c3a7",
      "name": "Sprint 24",
      "description": "Checkout rewrite and billing cleanup",
      "start_date": "2026-01-05T00:00:00Z",
      "end_date": "2026-01-19T00:00:00Z",
      "owned_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "sort_order": 65535,
      "timezone": "America/New_York",
      "external_id": null,
      "external_source": null,
      "logo_props": {},
      "progress_snapshot": {},
      "archived_at": null,
      "created_at": "2026-01-14T09:22:41.478363Z",
      "updated_at": "2026-01-14T09:22:41.478363Z",
      "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "updated_by_id": null
    },
    {
      "id": "2b8d5e07-9a41-4c6f-b3d2-71e8a4c05f96",
      "name": "Sprint 23",
      "description": "",
      "start_date": "2025-12-22T00:00:00Z",
      "end_date": "2026-01-05T00:00:00Z",
      "owned_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "sort_order": 55535,
      "timezone": "America/New_York",
      "external_id": "SPR-23",
      "external_source": "jira",
      "logo_props": {},
      "progress_snapshot": {},
      "archived_at": null,
      "created_at": "2025-12-18T11:04:07.912004Z",
      "updated_at": "2025-12-18T11:04:07.912004Z",
      "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "updated_by_id": null
    }
  ],
  "next": 50,
  "previous": null,
  "total_count": 27,
  "pagination": {
    "style": "offset"
  }
}

Response200

json

{
  "data": [
    {
      "id": "7c1f9a4e-3b6d-4a52-8f0c-2d9e6b18c3a7",
      "name": "Sprint 24",
      "description": "Checkout rewrite and billing cleanup",
      "start_date": "2026-01-05T00:00:00Z",
      "end_date": "2026-01-19T00:00:00Z",
      "owned_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "sort_order": 65535,
      "timezone": "America/New_York",
      "external_id": null,
      "external_source": null,
      "logo_props": {},
      "progress_snapshot": {},
      "archived_at": null,
      "created_at": "2026-01-14T09:22:41.478363Z",
      "updated_at": "2026-01-14T09:22:41.478363Z",
      "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "updated_by_id": null
    }
  ],
  "next_cursor": "b3A9MTcxOjA6MA==",
  "has_more": true,
  "pagination": {
    "style": "cursor"
  }
}

List cycles ​

Path parameters ​

Query parameters ​

Response shaping ​

Scopes ​

Errors ​

List cycles

Path parameters

Query parameters

Response shaping

Scopes

Errors