Preview a workflow fallback

POST/api/v2/workspaces/{slug}/projects/{project_id}/workflow-fallback-preview/

Count the work items in a project that would have to change state if they moved to another workflow, without changing anything. Plane moves a work item to a fallback state when its state isn't part of the workflow that applies to it, for example after its type changes or after the project switches workflows. This call shows how many work items that would affect, and which states they sit in now.

The response is a preview object with a total and a per_state breakdown of state_id and count. The call writes nothing and is safe to repeat.

type_id picks the work items. With it, the preview checks the work items of that type. Without it, the preview checks every work item in the project against one target workflow, regardless of each work item's type.

The target workflow is the first of these that applies:

1. new_type_id: the workflow that applies to that type in this project. This previews re-typing the work items.
2. workflow_id: that catalog workflow. This previews a workflow switch.
3. Neither: the workflow that applies to type_id in this project now, or to work items with no type when type_id is omitted.

The preview never counts drafts, work items in triage group states, or work items with no state. It does count archived work items.

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.

project_id:requiredstring

The project. Accepts the project UUID or its bare identifier, for example ENG.

Body Parameters

Every field is optional and accepts null.

type_id:optionalstring (uuid)

The work item type whose work items the preview checks. Omit it to check every work item in the project.

new_type_id:optionalstring (uuid)

Preview re-typing the type_id work items to this type. The target is the workflow that applies to this type in the project.

workflow_id:optionalstring (uuid)

Preview switching to this catalog workflow. The preview doesn't check that the workflow is active or in this workspace. An unknown workflow, or one with no states, previews as total: 0.

Scopes

projects.workflows:write

Errors

Status	Code	Cause
400	invalid_request	A body field that isn't a UUID.
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 can't view this project.
404	not_found	No such workspace or project, 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, so the project owns its workflows.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Governed workspaces only

This route returns 409 states_managed_at_project in a workspace without workspace governance. See Work item type governance for how a governed workspace decides which workflow applies.

Preview a workflow fallback

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflow-fallback-preview/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type_id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
  "new_type_id": "c3b81f5d-7a29-4e64-9d0b-2f6e8a1c4d73"
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflow-fallback-preview/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "type_id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
        "new_type_id": "c3b81f5d-7a29-4e64-9d0b-2f6e8a1c4d73",
    },
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/workflow-fallback-preview/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type_id: "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
      new_type_id: "c3b81f5d-7a29-4e64-9d0b-2f6e8a1c4d73",
    }),
  },
);
const data = await response.json();

Response200

{
  "total": 5,
  "per_state": [
    {
      "state_id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
      "count": 5
    }
  ]
}

Response200

{
  "total": 0,
  "per_state": []
}

Response409

{
  "type": "conflict",
  "code": "states_managed_at_project",
  "detail": "Work item type governance is managed at the project level in this workspace."
}

Where the moved work items land

This preview reports only where work items are now. To see each state's target, use Update a work item type workflow with ?dry_run=true, which also returns target_state_id per state.