---
title: "Create Task Run"
method: POST
path: "/api/task_runs/"
tags: ["Task Runs"]
---

# Create Task Run

`POST /api/task_runs/`

Create a task run. If a task run with the same flow_run_id,
task_key, and dynamic_key already exists, the existing task
run will be returned.

If no state is provided, the task run will be created in a PENDING state.

## Headers

- `x-prefect-api-version` string

## Request body

- TaskRunCreate — Data used by the Prefect REST API to create a task run
  - `id` string, uuid — The ID to use for the task run. If not provided, a random UUID will be generated.
  - `state` StateCreate — 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
  - `name` string
  - `flow_run_id` string, uuid — The flow run id of the task run.
  - `task_key` string, required — A unique identifier for the task being run.
  - `dynamic_key` string, required — A dynamic key used to differentiate between multiple runs of the same task within the same flow run.
  - `cache_key` string — An optional cache key. If a COMPLETED state associated with this cache key is found, the cached COMPLETED state will be used instead of executing the task run.
  - `cache_expiration` string, date-time — Specifies when the cached state should expire.
  - `task_version` string — The version of the task being run.
  - `empirical_policy` TaskRunPolicy — Defines of how a task run should retry.
    - `max_retries` integer — The maximum number of retries. Field is not used. Please use `retries` instead.
    - `retry_delay_seconds` number — The delay between retries. Field is not used. Please use `retry_delay` instead.
    - `retries` integer — The number of retries.
    - `retry_delay` union — A delay time or list of delay times between retries, in seconds.
      - integer
      - integer[]
    - `retry_jitter_factor` number — Determines the amount a retry should jitter
  - `tags` string[] — A list of tags for the task run.
  - `task_inputs` object — The inputs to the task run.

## Response `200`

Successful Response

- TaskRun — An ORM representation of task run data.
  - `id` string, uuid
  - `created` string, date-time
  - `updated` string, date-time
  - `name` string
  - `flow_run_id` string, uuid — The flow run id of the task run.
  - `task_key` string, required — A unique identifier for the task being run.
  - `dynamic_key` string, required — A dynamic key used to differentiate between multiple runs of the same task within the same flow run.
  - `cache_key` string — An optional cache key. If a COMPLETED state associated with this cache key is found, the cached COMPLETED state will be used instead of executing the task run.
  - `cache_expiration` string, date-time — Specifies when the cached state should expire.
  - `task_version` string — The version of the task being run.
  - `empirical_policy` TaskRunPolicy — Defines of how a task run should retry.
    - `max_retries` integer — The maximum number of retries. Field is not used. Please use `retries` instead.
    - `retry_delay_seconds` number — The delay between retries. Field is not used. Please use `retry_delay` instead.
    - `retries` integer — The number of retries.
    - `retry_delay` union — A delay time or list of delay times between retries, in seconds.
      - integer
      - integer[]
    - `retry_jitter_factor` number — Determines the amount a retry should jitter
  - `tags` string[] — A list of tags for the task run.
  - `state_id` string, uuid — The id of the current task run state.
  - `task_inputs` object — Tracks the source of inputs to a task run. Used for internal bookkeeping.
  - `state_type` 'SCHEDULED' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'CRASHED' | 'PAUSED' | 'CANCELLING' — Enumeration of state types.
  - `state_name` string — The name of the current task run state.
  - `run_count` integer — The number of times the task run has been executed.
  - `flow_run_run_count` integer — If the parent flow has retried, this indicates the flow retry this run is associated with.
  - `expected_start_time` string, date-time — The task run's expected start time.
  - `next_scheduled_start_time` string, date-time — The next time the task run is scheduled to start.
  - `start_time` string, date-time — The actual start time.
  - `end_time` string, date-time — The actual end time.
  - `total_run_time` number — Total run time. If the task run was executed multiple times, the time of each run will be summed.
  - `estimated_run_time` number — A real-time estimate of total run time.
  - `estimated_start_time_delta` number — The difference between actual and expected start time.
  - `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

## 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)