---
title: "Create Flow Run"
method: POST
path: "/api/flow_runs/"
tags: ["Flow Runs"]
---

# Create Flow Run

`POST /api/flow_runs/`

Create a flow run. If a flow run with the same flow_id and
idempotency key already exists, the existing flow run will be returned.

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

## Headers

- `x-prefect-api-version` string

## Request body

- FlowRunCreate — Data used by the Prefect REST API to create a flow run.
  - `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 — The name of the flow run. Defaults to a random slug if not specified.
  - `flow_id` string, uuid, required — The id of the flow being run.
  - `flow_version` string — The version of the flow being run.
  - `parameters` object
  - `context` object — The context of the flow run.
  - `parent_task_run_id` string, uuid
  - `infrastructure_document_id` string, uuid
  - `empirical_policy` FlowRunPolicy — Defines of how a flow 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` integer — The delay time between retries, in seconds.
    - `pause_keys` unknown[] — Tracks pauses this run has observed.
      - unknown
    - `resuming` boolean — Indicates if this run is resuming from a pause.
    - `retry_type` 'in_process' | 'reschedule' — The type of retry this run is undergoing.
  - `tags` string[] — A list of tags for the flow run.
  - `idempotency_key` string — An optional idempotency key. If a flow run with the same idempotency key has already been created, the existing flow run will be returned.
  - `deployment_id` string, uuid — DEPRECATED: The id of the deployment associated with this flow run, if available.

## Response `200`

Successful Response

- FlowRunResponse — A PrefectBaseModel with an auto-generated UUID ID value and created / updated timestamps, intended for compatibility with our standard ORM models. The ID, created, and updated fields are reset on copy() and not included in equality comparisons.
  - `id` string, uuid
  - `created` string, date-time
  - `updated` string, date-time
  - `name` string — The name of the flow run. Defaults to a random slug if not specified.
  - `flow_id` string, uuid, required — The id of the flow being run.
  - `state_id` string, uuid — The id of the flow run's current state.
  - `deployment_id` string, uuid — The id of the deployment associated with this flow run, if available.
  - `deployment_version` string — The version of the deployment associated with this flow run.
  - `work_queue_id` string, uuid — The id of the run's work pool queue.
  - `work_queue_name` string — The work queue that handled this flow run.
  - `flow_version` string — The version of the flow executed in this flow run.
  - `parameters` object — Parameters for the flow run.
  - `idempotency_key` string — An optional idempotency key for the flow run. Used to ensure the same flow run is not created multiple times.
  - `context` object — Additional context for the flow run.
  - `empirical_policy` FlowRunPolicy — Defines of how a flow 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` integer — The delay time between retries, in seconds.
    - `pause_keys` unknown[] — Tracks pauses this run has observed.
      - unknown
    - `resuming` boolean — Indicates if this run is resuming from a pause.
    - `retry_type` 'in_process' | 'reschedule' — The type of retry this run is undergoing.
  - `tags` string[] — A list of tags on the flow run
  - `parent_task_run_id` string, uuid — If the flow run is a subflow, the id of the 'dummy' task in the parent flow used to track subflow state.
  - `state_type` 'SCHEDULED' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'CRASHED' | 'PAUSED' | 'CANCELLING' — Enumeration of state types.
  - `state_name` string — The name of the current flow run state.
  - `run_count` integer — The number of times the flow run was executed.
  - `expected_start_time` string, date-time — The flow run's expected start time.
  - `next_scheduled_start_time` string, date-time — The next time the flow 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 flow run was executed multiple times, the time of each run will be summed.
  - `estimated_run_time` number — A real-time estimate of the total run time.
  - `estimated_start_time_delta` number — The difference between actual and expected start time.
  - `auto_scheduled` boolean — Whether or not the flow run was automatically scheduled.
  - `infrastructure_document_id` string, uuid — The block document defining infrastructure to use this flow run.
  - `infrastructure_pid` string — The id of the flow run as returned by an infrastructure block.
  - `created_by` CreatedBy
    - `id` string, uuid — The id of the creator of the object.
    - `type` string — The type of the creator of the object.
    - `display_value` string — The display value for the creator.
  - `work_pool_id` string, uuid — The id of the flow run's work pool.
  - `work_pool_name` string — The name of the flow run's work pool.
  - `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
  - `job_variables` object — Variables used as overrides in the base job template

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