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.

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

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.

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.

is_draft:optionalboolean

Filter by is_draft.

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.

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, created_at, created_by_id, cycle_id, id, identifier, is_draft, label_ids, module_ids, name, parent_id, priority, project_id, sequence_id, start_date, state_id, target_date, type_id.

expand:optionalstring

Comma-separated relations to embed: assignees, cycle, 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
`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": [
    {
      "archived_at": null,
      "assignee_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
      "created_at": "2026-01-14T09:22:41.478363Z",
      "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      "custom_fields": {},
      "cycle_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
      "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
      "identifier": "PROJ",
      "is_draft": false,
      "label_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
      "module_ids": [["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]],
      "name": "Example name",
      "parent_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
      "priority": "high",
      "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
      "sequence_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
      "start_date": "2026-01-12",
      "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
      "target_date": "2026-01-20",
      "type_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f"
    }
  ],
  "next": 1,
  "pagination": {
    "style": "offset"
  },
  "previous": 1,
  "total_count": 3
}

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