List work items across a workspace

GET/api/v2/workspaces/{slug}/work-items/

Work items are the issues, tasks and epics in a project. List the workspace work items you can see. Results are scoped to the path and to what your token is allowed to read.

This list takes the same filters, search, ordering, ?expand=, and pagination as List work items, plus project_id and project_id__in to narrow it to some projects. Filters combine with AND.

Use initiative_id, release_id, and customer_id to find the work items linked to an initiative, a release, or a customer across every project. They combine with the other filters, so ?initiative_id=…&state_group=started returns the initiative's started work items in one call. The initiative's own work item list can't apply that filter. A malformed UUID in any id filter is a 400 invalid_request.

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.

Query Parameters

archived:optionalstring

Include archived work items. false, the default, lists active work items only. true lists active and archived work items together, and only lists archived work items only.

true and only drop all of the default list's exclusions, including the archive one. Drafts and work items in the triage state group come back too, and true also returns work items in archived projects. Add ?is_draft=false to leave drafts out. The value is not validated, and an unrecognized value behaves like false.

One of false, only, true.

assignee_id:optionalstring (uuid)

Filter by assignee_id.

assignee_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

assignee_id__isnull:optionalboolean

Filter by assignee_id__isnull.

count:optionalboolean

Set to false to skip the total_count COUNT(*) (omits total_count).

created_at__gte:optionalstring (date-time)

Filter by created_at__gte.

created_at__lte:optionalstring (date-time)

Filter by created_at__lte.

customer_id:optionalstring (uuid)

Match work items linked to a customer, whether the link is direct or made through one of the customer's requests. A work item linked more than once still appears once.

customer_id__in:optionalarray of string (uuid)

Match work items linked to any of these customers. Multiple values may be separated by commas.

cycle_id:optionalstring (uuid)

Filter by cycle_id.

cycle_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

cycle_id__isnull:optionalboolean

Filter by cycle_id__isnull.

external_id:optionalstring

Filter by external_id.

external_source:optionalstring

Filter by external_source.

initiative_id:optionalstring (uuid)

Match work items linked to an initiative.

initiative_id__in:optionalarray of string (uuid)

Match work items linked to any of these initiatives. Multiple values may be separated by commas.

is_draft:optionalboolean

Filter by is_draft. The default list leaves drafts out, so ?is_draft=true returns nothing unless you also pass ?archived=true or ?archived=only.

label_id:optionalstring (uuid)

Filter by label_id.

label_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

label_id__isnull:optionalboolean

Filter by label_id__isnull.

module_id:optionalstring (uuid)

Filter by module_id.

module_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

module_id__isnull:optionalboolean

Filter by module_id__isnull.

offset:optionalinteger

Number of rows to skip from the start of the result set.

order_by:optionalstring

Field to order the list by. Prefix with '-' for descending (e.g. '-created_at'). Annotation-backed orders sort semantically and ride the default offset page.

paginate:optionalstring

Set to 'cursor' to opt into the COUNT-free keyset cursor envelope (use for deep traversal); omit for the default offset envelope with total_count.

One of cursor.

parent_id:optionalstring (uuid)

Filter by parent_id.

parent_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

parent_id__isnull:optionalboolean

Filter by parent_id__isnull.

per_page:optionalinteger

Page size (max 200).

priority:optionalstring

urgent - Urgent
high - High
medium - Medium
low - Low
none - None

One of high, low, medium, none, urgent.

priority__in:optionalarray of string

Multiple values may be separated by commas.

urgent - Urgent
high - High
medium - Medium
low - Low
none - None

project_id:optionalstring (uuid)

Filter by project_id.

project_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

release_id:optionalstring (uuid)

Match work items in a release.

release_id__in:optionalarray of string (uuid)

Match work items in any of these releases. Multiple values may be separated by commas.

search:optionalstring

A search term.

sequence_id:optionalinteger

Filter by sequence_id.

start_date__gte:optionalstring (date)

Filter by start_date__gte.

start_date__lte:optionalstring (date)

Filter by start_date__lte.

state_group:optionalstring

backlog - Backlog
unstarted - Unstarted
started - Started
completed - Completed
cancelled - Cancelled
triage - Triage

One of backlog, cancelled, completed, started, triage, unstarted.

state_group__in:optionalarray of string

Multiple values may be separated by commas.

backlog - Backlog
unstarted - Unstarted
started - Started
completed - Completed
cancelled - Cancelled
triage - Triage

state_id:optionalstring (uuid)

Filter by state_id.

state_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

target_date__gte:optionalstring (date)

Filter by target_date__gte.

target_date__lte:optionalstring (date)

Filter by target_date__lte.

type_id:optionalstring (uuid)

Filter by type_id.

type_id__in:optionalarray of string (uuid)

Multiple values may be separated by commas.

updated_at__gte:optionalstring (date-time)

Filter by updated_at__gte.

updated_at__lte:optionalstring (date-time)

Filter by updated_at__lte.

Response shaping

fields:optionalstring

Comma-separated list of fields to return. Unrequested keys are omitted from each row, not returned as null. id always comes back. Pass all for every requestable field.

An unknown name is a 400 that names the valid set, so a typo can't silently cost you the saving. See Sparse fields.

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.

Rows leave out description_html unless you name it, for example ?fields=id,name,description_html. custom_fields is not available on this list.

expand:optionalstring

Comma-separated relations to embed: 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. ?fields= and ?expand= are independent: naming a relation in ?fields= is a 400, and expanded objects survive field filtering. See Expanding relations.

Scopes

projects.work_items:read

Errors

Status	Code	Cause
`400`	`invalid_request`	A filter value is invalid, such as an unknown `priority` or `state_group` or a malformed UUID, or `?fields=` or `?expand=` names something unknown.
`400`	`ordering_not_cursor_eligible`	`?paginate=cursor` with an `order_by` that can't be paged by cursor: `priority`, `state_group`, or `sort_order`.
`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 doesn't allow this.
`404`	`not_found`	No such resource, 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 work items across a workspace

bash

curl -X GET \
  "https://api.plane.so/api/v2/workspaces/my-team/work-items/" \
  -H "X-Api-Key: $PLANE_API_KEY"

python

import requests

response = requests.get(
    "https://api.plane.so/api/v2/workspaces/my-team/work-items/",
    headers={"X-Api-Key": "your-api-key"},
)
print(response.json())

javascript

const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-items/", {
  method: "GET",
  headers: {
    "X-Api-Key": "your-api-key",
  },
});
const data = await response.json();

Response200

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": "e2b7c4d1-5a83-4f96-b0e2-7c1d9f3a6b58",
      "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-15T10:03:17.220981Z",
      "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    },
    {
      "id": "d41a7e92-6b05-4c3f-8e17-2a9c5d0b8f64",
      "name": "Publish the Q1 pricing page",
      "identifier": "MKT-37",
      "sequence_id": 37,
      "priority": "medium",
      "project_id": "91c3e5a7-2d64-4b80-a5f1-6e8d0c4b7a29",
      "state_id": "0b6e2f48-7c19-4d5a-9e83-5f1a6c2d7b90",
      "type_id": null,
      "assignee_ids": [],
      "label_ids": [],
      "cycle_id": null,
      "module_ids": ["6a2f9c13-8e47-4b05-a1d6-3c7e0b5f9d82"],
      "parent_id": null,
      "estimate_point_id": "3e8c1a5f-9b27-4d64-8f0a-1c6e2d7b4a95",
      "start_date": null,
      "target_date": "2026-01-31",
      "is_draft": false,
      "sort_order": 65535.0,
      "completed_at": null,
      "archived_at": null,
      "external_id": "MKT-1182",
      "external_source": "jira",
      "created_at": "2026-01-13T16:04:02.911204Z",
      "updated_at": "2026-01-13T16:04:02.911204Z",
      "created_by_id": "9b7f4c53-2d18-4a6e-8c05-1f3e7d9a2b64",
      "updated_by_id": null
    }
  ],
  "next": 50,
  "previous": null,
  "total_count": 214,
  "pagination": {
    "style": "offset"
  }
}

List work items across a workspace ​

Path Parameters ​

Query Parameters ​

Response shaping ​

Scopes ​

Errors ​

List work items across a workspace

Path Parameters

Query Parameters

Response shaping

Scopes

Errors