Sign in
Deployments

Create Flow Run From Deployment

Create a flow run from a deployment.

Any parameters not provided will be inferred from the deployment's parameters. If tags are not provided, the deployment's tags will be used.

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

post/api/deployments/{id}/create_flow_run

Path parameters

idstring uuid required

The deployment id

The deployment id

Headers

x-prefect-api-versionstring

Request body

namestring

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

parametersobject
enforce_parameter_schemaboolean

Whether or not to enforce the parameter schema on this run.

contextobject
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.

parent_task_run_idstring uuid
work_queue_namestring
job_variablesobject

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.16217

  • 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

  • 67400ee9e9bd1See the full diff
    • ○

      added the new optional request property enforce_parameter_schema

      new-optional-request-property

  • 0803f67b017b1See the full diff
    • ○

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

      response-optional-property-added

  • 93ae2b3f2efd1621See 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 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

  • 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