Get workspace workflow usage

GET/api/v2/workspaces/{slug}/workflows/{pk}/usage/

Return what references a catalog workflow: the projects and work item types whose pick points at it, and the work item types whose governance lists it. Call it before you delete a workflow, remove states from its chain, or change an allowlist, to see which projects and types the change affects.

A pin writes the project's pick, so pinned projects appear in projects too.

The response names every project that resolves to the workflow, including private projects you aren't a member of, so the endpoint needs permission to view workspace workflows rather than workspace membership alone. It takes no fields and isn't paginated.

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.

pk:requiredstring (uuid)

The id of the catalog workflow. A project workflow's id returns 404.

Response

• projects array of object. One entry per project with a pick that points at the workflow:
  • project_id string (uuid)
  • name string. The project name.
  • types array of string. The work item type ids whose pick in this project points at the workflow. null stands for the project's pick for work items without a type.
• types_allowing array of string. Work item types that list this workflow in their allowlist.
• types_mandating array of string. The subset of types_allowing whose governance mode is required, so the type mandates this workflow in every project.

Scopes

workspaces.workflows:read

Errors

Status	Code	Cause
401	unauthorized	Missing or invalid credentials.
402	payment_required	The OpenAPI schema declares 402 for every catalog route. This endpoint checks no plan feature, so it never returns 402.
403	forbidden	Your role or token scope can't view workspace workflows.
404	not_found	No such workflow in this workspace's catalog, or it's outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	states_managed_at_project	The workspace doesn't have governance turned on. Use the project's workflows instead.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Get workspace workflow usage

curl -X GET \
  "https://api.plane.so/api/v2/workspaces/my-team/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/usage/" \
  -H "X-Api-Key: $PLANE_API_KEY"

import requests

response = requests.get(
    "https://api.plane.so/api/v2/workspaces/my-team/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/usage/",
    headers={"X-Api-Key": "your-api-key"},
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/workflows/9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88/usage/",
  {
    headers: {
      "X-Api-Key": "your-api-key",
    },
  },
);
const data = await response.json();

Response200

{
  "projects": [
    {
      "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
      "name": "Mobile App",
      "types": ["2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4"]
    },
    {
      "project_id": "d1e8a3c5-7f2b-4a96-8e04-3b6c9d1f5a27",
      "name": "Platform",
      "types": ["2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4"]
    }
  ],
  "types_mandating": [],
  "types_allowing": ["2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4"]
}