---
title: "List a task's transitions"
method: GET
path: "/v1/projects/{project_id}/tasks/{task_id}/transitions"
tags: ["Tasks"]
---

# List a task's transitions

`GET /v1/projects/{project_id}/tasks/{task_id}/transitions`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/tasks/{task_id}/transitions`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Lists every transition of the workflow version the task is pinned to, with whether firing it now as the caller would be accepted and, when not, the error code firing it would answer. The guard runs with the caller as `principal`. A `requires_approval` transition is allowed before its guard passes: the guard runs when the approval resolves. Advisory: firing re-validates under the task's lock.

## Path parameters

- `task_id` string, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

The pinned version's transitions, in definition order

- object
  - `data` TaskTransitionOption[], required
    - `name` string, required
    - `to` string, required: The state the transition moves the task to.
    - `requires_approval` boolean, required: Firing it parks an approval instead of moving the task.
    - `allowed` boolean, required: Whether firing it now as the caller would be accepted.
    - `error_code` 'TASK_TRANSITION_CONFLICT' | 'TASK_GUARD_REJECTED' | 'null', nullable, required: The code firing it would answer: `TASK_TRANSITION_CONFLICT` when the task is closed, has a transition pending approval, or is not in one of the transition's `from` states; `TASK_GUARD_REJECTED` when its guard fails. Null when `allowed`.
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Task not found

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)