---
title: "Set Task Run State"
method: POST
path: "/api/task_runs/{id}/set_state"
tags: ["Task Runs"]
---

# Set Task Run State

`POST /api/task_runs/{id}/set_state`

Set a task run state, invoking any orchestration rules.

## Path parameters

- `id` string, uuid, required — The task run id

## Headers

- `x-prefect-api-version` string

## Request body

- BodySetTaskRunStateTaskRunsIdSetStatePost
  - `state` StateCreate, required — Data used by the Prefect REST API to create a new state.
    - `type` 'SCHEDULED' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'CRASHED' | 'PAUSED' | 'CANCELLING', required — Enumeration of state types.
    - `name` string — The name of the state to create
    - `message` string — The message of the state to create
    - `data` unknown
    - `state_details` StateDetails — A base pydantic.BaseModel for all Prefect schemas and pydantic models. As the basis for most Prefect schemas, this base model usually ignores extra fields that are passed to it at instantiation. Because adding new fields to API payloads is not considered a breaking change, this ensures that any Prefect client loading data from a server running a possibly-newer version of Prefect will be able to process those new fields gracefully. However, when PREFECT_TEST_MODE is on, extra fields are forbidden in order to catch subtle unintentional testing errors.
      - `flow_run_id` string, uuid
      - `task_run_id` string, uuid
      - `child_flow_run_id` string, uuid
      - `scheduled_time` string, date-time
      - `cache_key` string
      - `cache_expiration` string, date-time
      - `untrackable_result` boolean
      - `pause_timeout` string, date-time
      - `pause_reschedule` boolean
      - `pause_key` string
      - `run_input_keyset` object
      - `refresh_cache` boolean
      - `retriable` boolean
      - `transition_id` string, uuid
      - `task_parameters_id` string, uuid
    - `timestamp` string, date-time
    - `id` string, uuid
  - `force` boolean — If false, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied.

## Response `200`

Successful Response

- OrchestrationResult — A container for the output of state orchestration.
  - `state` State — Represents the state of a run.
    - `id` string, uuid
    - `type` 'SCHEDULED' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'CRASHED' | 'PAUSED' | 'CANCELLING', required — Enumeration of state types.
    - `name` string
    - `timestamp` string, date-time
    - `message` string
    - `data` unknown
    - `state_details` StateDetails — A base pydantic.BaseModel for all Prefect schemas and pydantic models. As the basis for most Prefect schemas, this base model usually ignores extra fields that are passed to it at instantiation. Because adding new fields to API payloads is not considered a breaking change, this ensures that any Prefect client loading data from a server running a possibly-newer version of Prefect will be able to process those new fields gracefully. However, when PREFECT_TEST_MODE is on, extra fields are forbidden in order to catch subtle unintentional testing errors.
      - `flow_run_id` string, uuid
      - `task_run_id` string, uuid
      - `child_flow_run_id` string, uuid
      - `scheduled_time` string, date-time
      - `cache_key` string
      - `cache_expiration` string, date-time
      - `untrackable_result` boolean
      - `pause_timeout` string, date-time
      - `pause_reschedule` boolean
      - `pause_key` string
      - `run_input_keyset` object
      - `refresh_cache` boolean
      - `retriable` boolean
      - `transition_id` string, uuid
      - `task_parameters_id` string, uuid
  - `status` 'ACCEPT' | 'REJECT' | 'ABORT' | 'WAIT', required — Enumerates return statuses for setting run states.
  - `details` union, required
    - StateAcceptDetails — Details associated with an ACCEPT state transition.
      - `type` 'accept_details' — The type of state transition detail. Used to ensure pydantic does not coerce into a different type.
    - StateWaitDetails — Details associated with a WAIT state transition.
      - `type` 'wait_details' — The type of state transition detail. Used to ensure pydantic does not coerce into a different type.
      - `delay_seconds` integer, required — The length of time in seconds the client should wait before transitioning states.
      - `reason` string — The reason why the state transition should wait.
    - StateRejectDetails — Details associated with a REJECT state transition.
      - `type` 'reject_details' — The type of state transition detail. Used to ensure pydantic does not coerce into a different type.
      - `reason` string — The reason why the state transition was rejected.
    - StateAbortDetails — Details associated with an ABORT state transition.
      - `type` 'abort_details' — The type of state transition detail. Used to ensure pydantic does not coerce into a different type.
      - `reason` string — The reason why the state transition was aborted.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/prefecthq/apis/untitled-api-2.md) · [All operations](https://skmtc.net/prefecthq/apis/untitled-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prefecthq/untitled-api-2/versions/29ba6c4f8837/schema)