Archive a cycle

POST/api/v2/workspaces/{slug}/projects/{project_id}/cycles/{pk}/archive/

Set a cycle's archived_at to the current time and take the cycle out of the default cycle list.

This is a bodyless POST. A successful call returns 204 with an empty body. Read the cycle with Get a cycle when you need the new archived_at.

Only a completed cycle, one whose end_date is in the past, can be archived. A cycle that is still running, or that has no end_date, returns 409 conflict and stays active.

Archiving is reversible with Unarchive a cycle, and it is separate from deleting. An archived cycle still exists and still resolves by id.

Path Parameters

slug:requiredstring

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

project_id:requiredstring (uuid)

The project the cycle belongs to.

pk:requiredstring (uuid)

The cycle's UUID. A cycle from another project returns 404.

Body Parameters

None. The endpoint takes no request body, and anything you send is ignored.

Safe to repeat

Archiving a cycle that is already archived returns 204 and changes nothing. The end_date check does not run again, and archived_at keeps its first timestamp.

Scopes

projects.cycles:write

Errors

Status	Code	Cause
400	invalid_request	A malformed path parameter, for example a pk that isn't a UUID.
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 archive cycles in this project.
404	not_found	No such cycle, wrong project, or the record is outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	conflict	The cycle has not ended. Its end_date is in the future or not set.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Archive a cycle

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/cycles/7c1f9a4e-3b6d-4a52-8f0c-2d9e6b18c3a7/archive/" \
  -H "X-Api-Key: $PLANE_API_KEY"

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/cycles/7c1f9a4e-3b6d-4a52-8f0c-2d9e6b18c3a7/archive/",
    headers={"X-Api-Key": "your-api-key"},
)
print(response.status_code)  # 204

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/cycles/7c1f9a4e-3b6d-4a52-8f0c-2d9e6b18c3a7/archive/",
  {
    method: "POST",
    headers: { "X-Api-Key": "your-api-key" },
  },
);
console.log(response.status); // 204

Response204

No response body.

Response409

{
  "type": "conflict",
  "code": "conflict",
  "detail": "Only completed cycles can be archived."
}

What archiving changes

• archived_at goes from null to a timestamp. Nothing else on the cycle changes. Its work items stay in it, and its progress counts and progress_snapshot are untouched.
• The cycle drops out of List cycles. Pass ?is_archived=true to list only archived cycles, or ?include_archived=true to list them with the active ones. Get a cycle still returns it.
• Plane removes the cycle from every user's favorites. Unarchiving does not add it back.

archived_at is read-only on the cycle itself, so a PATCH cannot archive it. This endpoint sets archived_at, and Unarchive a cycle clears it.