List work items across a workspace

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

List the work items you can see across the workspace. Work items are the issues, tasks, and epics in a project. 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 returns 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 COUNT(*) query behind total_count. The response then leaves out 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 sort the list by. Prefix it with - for descending order, for example -created_at. Orders on computed fields sort by their logical order and use the default offset pagination.

paginate:optionalstring

Set to cursor to switch to the keyset cursor envelope, which skips the COUNT query and is better for paging deep into a list. Leave it out to get 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

Match work items with this priority. One of high, low, medium, none, urgent.

priority__in:optionalarray of string

Multiple values may be separated by commas. Each value is one of urgent, high, medium, low, or 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

Match work items whose state is in this group. One of backlog, cancelled, completed, started, triage, unstarted.

state_group__in:optionalarray of string

Multiple values may be separated by commas. Each value is one of backlog, unstarted, started, completed, cancelled, or 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. Fields you don't request are left out of each row instead of coming back as null. id is always included. Pass all to get every requestable field.

An unknown field name returns 400 with the list of valid names, so a typo is caught instead of being silently ignored. 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.

Expanded objects get their own key: ?expand=state keeps state_id and adds a state object next to it. ?fields= and ?expand= work independently. Naming a relation in ?fields= returns 400, and field filtering never removes an expanded object. 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