List a release's work items
Return the work items in a workspace release as full work item objects, paginated. You get the release's scope and the work items behind it in one call. A workspace release can hold work items from any project, so rows can come from several projects. ?fields= and ?expand= apply to the work items.
The list takes no filters and no order_by. Rows come back ordered by the work item's created_at, newest first. Some work items on the release are left out:
- Work items you can't see
- Archived work items, and work items in archived projects
- Drafts
- Work items still in intake triage
This route serves workspace releases only. A project release, a release you can't view, and an unknown id all return 404. For a project release, use List a project release's work items.
Need to filter? Use the work items list
To narrow the release's work items, for example by state group or assignee, or to sort them, call the workspace work items list with ?release_id={pk} and any other filter. The project work items list takes the same filter for one project's share of the release. Use this child list for a one-call read, and the release_id filter when you need to combine it with other filters.
To add or remove work items, use Add or remove release work items.
Path Parameters
slug:requiredstringThe workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.
pk:requiredstring (uuid)The id of the release whose work items you want.
Pagination
per_page:optionalintegerPage size. Defaults to 50, maximum 200.
offset:optionalintegerNumber of rows to skip from the start of the result set. Maximum 10000. Read the next value from the response rather than computing offsets yourself.
count:optionalbooleanDefaults to true. Set to false to skip the COUNT(*) behind total_count. The field is then left out of the response.
Response shaping
fields:optionalstringComma-separated list of work item 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.
Rows leave out description_html unless you name it or pass all. 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, assignee_ids, completed_at, created_at, created_by_id, cycle_id, description_html, estimate_point_id, external_id, external_source, id, identifier, is_draft, label_ids, module_ids, name, parent_id, priority, project_id, sequence_id, sort_order, start_date, state_id, target_date, type_id, updated_at, updated_by_id.
See Sparse fields.
expand:optionalstringComma-separated relations to embed on each work item: assignees, cycle, estimate_point, labels, modules, parent, state, type.
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. See Expanding relations.
Scopes
releases:read
Errors
| Status | Code | Cause |
|---|---|---|
401 | unauthorized | Missing or invalid credentials. |
402 | payment_required | Releases aren't enabled on your plan. |
403 | forbidden | Your token scope doesn't allow this. |
404 | not_found | No workspace release with this id, the id belongs to a project release, or you can't view the release. |
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. |
curl -X GET \
"https://api.plane.so/api/v2/workspaces/my-team/releases/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/work-items/" \
-H "X-Api-Key: $PLANE_API_KEY"import requests
response = requests.get(
"https://api.plane.so/api/v2/workspaces/my-team/releases/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/work-items/",
headers={"X-Api-Key": "your-api-key"},
)
print(response.json())const response = await fetch(
"https://api.plane.so/api/v2/workspaces/my-team/releases/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/work-items/",
{
headers: {
"X-Api-Key": "your-api-key",
},
},
);
const data = await response.json();{
"data": [
{
"id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
"name": "Fix login redirect loop",
"identifier": "PROJ-142",
"sequence_id": 142,
"priority": "high",
"project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
"state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
"type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
"assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
"label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
"cycle_id": null,
"module_ids": [],
"parent_id": null,
"estimate_point_id": null,
"start_date": "2026-01-12",
"target_date": "2026-01-20",
"is_draft": false,
"sort_order": 85535.0,
"completed_at": null,
"archived_at": null,
"external_id": null,
"external_source": 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": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
},
{
"id": "c5a83e17-4f2d-4b90-8e61-0d9b7a3c2f58",
"name": "Update API docs for bulk endpoints",
"identifier": "DOCS-57",
"sequence_id": 57,
"priority": "medium",
"project_id": "e2b7c941-6d3a-4f18-a5c0-8b1d9e4f7a26",
"state_id": "4d8a1e63-2b7f-4c95-9e30-6f1a8c2d5b74",
"type_id": null,
"assignee_ids": [],
"label_ids": [],
"cycle_id": null,
"module_ids": [],
"parent_id": null,
"estimate_point_id": null,
"start_date": null,
"target_date": "2026-01-22",
"is_draft": false,
"sort_order": 65535.0,
"completed_at": "2026-01-13T16:20:55.104738Z",
"archived_at": null,
"external_id": null,
"external_source": null,
"created_at": "2026-01-08T13:47:02.663159Z",
"updated_at": "2026-01-13T16:20:55.104738Z",
"created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
"updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}
],
"next": null,
"previous": null,
"total_count": 2,
"pagination": {
"style": "offset"
}
}{
"type": "not_found",
"code": "not_found",
"detail": "The requested resource was not found."
}