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 — ?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. This is how you build a "my cycles" view — pass the authenticated user's id. Ownership is assigned by Plane, so this is a read-side filter only.

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 — newest or oldest 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 opt into the COUNT-free keyset envelope instead of the default offset envelope. The response then carries next_cursor and has_more rather than next, previous, and total_count; pass next_cursor back as cursor to walk to the following 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 field is then omitted from the envelope. Worth doing 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 cycle default ordering, and anything other than paginate=cursor uses offset pagination — so check your spelling, because a typo shows up as an unexpected sort order or envelope rather than an error.

Response shaping

fields:optionalstring

Comma-separated list of fields to return on each row. Unrequested keys are omitted from the response, not returned as null, so absent means "not requested" and null means "actually null". id always comes back whether or not you name it.

Pass all for every requestable field. An unknown name is a 400 that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.

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).

Expansion is separate-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 is a 400.

?fields= and ?expand= are independent namespaces. Relation names are not valid ?fields= tokens (and vice versa), and an expanded object survives field filtering — ?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