Sign in
Flow Runs

Create Flow Run

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.

post/api/flow_runs/

Headers

x-prefect-api-versionstring

Request body

namestring

The name of the flow run. Defaults to a random slug if not specified.

flow_idstring uuid required

The id of the flow being run.

flow_versionstring

The version of the flow being run.

parametersobject
contextobject

The context of the flow run.

parent_task_run_idstring uuid
infrastructure_document_idstring uuid
tagsstring[]

A list of tags for the flow run.

idempotency_keystring

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_idstring uuid

DEPRECATED: The id of the deployment associated with this flow run, if available.

Example request

{
  "name": "my-flow-run",
  "tags": [
    "tag-1",
    "tag-2"
  ]
}

Response

Successful Response

idstring uuid
createdstring date-time
updatedstring date-time
namestring

The name of the flow run. Defaults to a random slug if not specified.

flow_idstring uuid required

The id of the flow being run.

state_idstring uuid

The id of the flow run's current state.

deployment_idstring uuid

The id of the deployment associated with this flow run, if available.

deployment_versionstring

The version of the deployment associated with this flow run.

work_queue_idstring uuid

The id of the run's work pool queue.

work_queue_namestring

The work queue that handled this flow run.

flow_versionstring

The version of the flow executed in this flow run.

parametersobject

Parameters for the flow run.

idempotency_keystring

An optional idempotency key for the flow run. Used to ensure the same flow run is not created multiple times.

contextobject

Additional context for the flow run.

tagsstring[]

A list of tags on the flow run

parent_task_run_idstring 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_namestring

The name of the current flow run state.

run_countinteger

The number of times the flow run was executed.

expected_start_timestring date-time

The flow run's expected start time.

next_scheduled_start_timestring date-time

The next time the flow run is scheduled to start.

start_timestring date-time

The actual start time.

end_timestring date-time

The actual end time.

total_run_timenumber

Total run time. If the flow run was executed multiple times, the time of each run will be summed.

estimated_run_timenumber

A real-time estimate of the total run time.

estimated_start_time_deltanumber

The difference between actual and expected start time.

auto_scheduledboolean

Whether or not the flow run was automatically scheduled.

infrastructure_document_idstring uuid

The block document defining infrastructure to use this flow run.

infrastructure_pidstring

The id of the flow run as returned by an infrastructure block.

work_pool_idstring uuid

The id of the flow run's work pool.

work_pool_namestring

The name of the flow run's work pool.

job_variablesobject

Variables used as overrides in the base job template

Example response

{
  "name": "my-flow-run",
  "deployment_version": "1.0",
  "flow_version": "1.0",
  "context": {
    "my_var": "my_val"
  },
  "tags": [
    "tag-1",
    "tag-2"
  ],
  "work_pool_name": "my-work-pool",
  "state": {
    "message": "Run started"
  }
}

Changes

Changed in 6 of the 50 revisions of this API.17226

  • 29ba6c4f88372See the full diff
    • ○

      added the new optional request property empirical_policy/allOf[subschema #1: FlowRunPolicy]/retry_type

      new-optional-request-property

    • ○

      added the optional property empirical_policy/retry_type to the response with the 200 status

      response-optional-property-added

  • 0803f67b017b1See the full diff
    • ○

      added the optional property deployment_version to the response with the 200 status

      response-optional-property-added

  • 93ae2b3f2efd1721See the full diff
    • ▲

      added FlowRunPolicy to the empirical_policy request property allOf list

      request-property-all-of-added

    • ▲

      added StateDetails to the state/allOf[subschema #1: StateCreate]/state_details request property allOf list

      request-property-all-of-added

    • ▲

      added StateType to the state/allOf[subschema #1: StateCreate]/type request property allOf list

      request-property-all-of-added

    • ▲

      the request property flow_id became required

      request-property-became-required

    • ▲

      the request property state/allOf[subschema #1: StateCreate]/type became required

      request-property-became-required

    • ▲

      removed the enum value CANCELLED of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value CANCELLING of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value COMPLETED of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value CRASHED of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value FAILED of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value PAUSED of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value PENDING of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value RUNNING of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      removed the enum value SCHEDULED of the request property state/allOf[subschema #1: StateCreate]/type

      request-property-enum-value-removed

    • ▲

      the empirical_policy request property type/format changed from object/ to /

      request-property-type-changed

    • ▲

      the state/allOf[subschema #1: StateCreate]/state_details request property type/format changed from object/ to /

      request-property-type-changed

    • ▲

      the state/allOf[subschema #1: StateCreate]/type request property type/format changed from string/ to /

      request-property-type-changed

    • ●

      removed the request property empirical_policy/max_retries

      request-property-removed

    • ●

      removed the request property empirical_policy/pause_keys

      request-property-removed

    • ●

      removed the request property empirical_policy/resuming

      request-property-removed

    • ●

      removed the request property empirical_policy/retries

      request-property-removed

    • ●

      removed the request property empirical_policy/retry_delay

      request-property-removed

    • ●

      removed the request property empirical_policy/retry_delay_seconds

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/cache_expiration

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/cache_key

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/child_flow_run_id

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/flow_run_id

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/pause_key

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/pause_reschedule

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/pause_timeout

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/refresh_cache

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/retriable

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/run_input_keyset

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/scheduled_time

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/task_parameters_id

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/task_run_id

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/transition_id

      request-property-removed

    • ●

      removed the request property state/allOf[subschema #1: StateCreate]/state_details/untrackable_result

      request-property-removed

  • f5252435d1571See the full diff
    • ○

      the response property flow_id became required for the status 200

      response-property-became-required

  • 5c88f8c509861See the full diff
    • ●

      removed the request property job_variables

      request-property-removed

  • 5ea7df68007c2See the full diff
    • ○

      added the new optional request property job_variables

      new-optional-request-property

    • ○

      added the optional property job_variables to the response with the 200 status

      response-optional-property-added