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 /deployments/{id}/create_flow_run

Create Flow Run From Deployment

cURL

curl --request POST \
  --url https://api.example.com/deployments/{id}/create_flow_run \
  --header 'Content-Type: application/json' \
  --data '
{
  "state": {
    "name": "<string>",
    "message": "<string>",
    "data": "<unknown>",
    "state_details": {
      "flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "child_flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "scheduled_time": "2023-11-07T05:31:56Z",
      "cache_key": "<string>",
      "cache_expiration": "2023-11-07T05:31:56Z",
      "deferred": false,
      "untrackable_result": false,
      "pause_timeout": "2023-11-07T05:31:56Z",
      "pause_reschedule": false,
      "pause_key": "<string>",
      "run_input_keyset": {},
      "refresh_cache": true,
      "retriable": true,
      "transition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "task_parameters_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "traceparent": "<string>",
      "deployment_concurrency_lease_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  },
  "name": "my-flow-run",
  "parameters": {},
  "enforce_parameter_schema": true,
  "context": {},
  "infrastructure_document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "empirical_policy": {
    "max_retries": 0,
    "retry_delay_seconds": 0,
    "retries": 123,
    "retry_delay": 123,
    "pause_keys": [
      "<string>"
    ],
    "resuming": false
  },
  "tags": [
    "tag-1",
    "tag-2"
  ],
  "idempotency_key": "<string>",
  "labels": {
    "key": "value1",
    "key2": 42
  },
  "parent_task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "work_queue_name": "<string>",
  "job_variables": {}
}
'

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "updated": "2023-11-07T05:31:56Z",
  "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "my-flow-run",
  "state_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "deployment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "deployment_version": "1.0",
  "work_queue_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "work_queue_name": "<string>",
  "flow_version": "1.0",
  "parameters": {},
  "idempotency_key": "<string>",
  "context": {
    "my_var": "my_val"
  },
  "empirical_policy": {
    "max_retries": 0,
    "retry_delay_seconds": 0,
    "retries": 123,
    "retry_delay": 123,
    "pause_keys": [
      "<string>"
    ],
    "resuming": false,
    "retry_type": "in_process"
  },
  "tags": [
    "tag-1",
    "tag-2"
  ],
  "labels": {
    "key": "value1",
    "key2": 42
  },
  "parent_task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "state_type": "SCHEDULED",
  "state_name": "<string>",
  "run_count": 0,
  "expected_start_time": "2023-11-07T05:31:56Z",
  "next_scheduled_start_time": "2023-11-07T05:31:56Z",
  "start_time": "2023-11-07T05:31:56Z",
  "end_time": "2023-11-07T05:31:56Z",
  "total_run_time": 0,
  "estimated_run_time": 0,
  "estimated_start_time_delta": 0,
  "auto_scheduled": false,
  "infrastructure_document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "infrastructure_pid": "<string>",
  "created_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "<string>",
    "display_value": "<string>"
  },
  "work_pool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "work_pool_name": "my-work-pool",
  "state": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "SCHEDULED",
    "name": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "message": "Run started",
    "data": "<unknown>",
    "state_details": {
      "flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "child_flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "scheduled_time": "2023-11-07T05:31:56Z",
      "cache_key": "<string>",
      "cache_expiration": "2023-11-07T05:31:56Z",
      "deferred": false,
      "untrackable_result": false,
      "pause_timeout": "2023-11-07T05:31:56Z",
      "pause_reschedule": false,
      "pause_key": "<string>",
      "run_input_keyset": {},
      "refresh_cache": true,
      "retriable": true,
      "transition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "task_parameters_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "traceparent": "<string>",
      "deployment_concurrency_lease_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  },
  "job_variables": {}
}

Headers

x-prefect-api-version · string

Path Parameters

id · string<uuid> · required

The deployment id

Body

application/json

Data used by the Prefect REST API to create a flow run from a deployment.

state · StateCreate · object | null

The state of the flow run to create

Show child attributes

name · string

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

Example:

"my-flow-run"

parameters · Parameters · object

enforce_parameter_schema · boolean | null

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

context · Context · object

infrastructure_document_id · string<uuid> | null

empirical_policy · FlowRunPolicy · object

The empirical policy for the flow run.

Show child attributes

tags · string[]

A list of tags for the flow run.

Example:

["tag-1", "tag-2"]

idempotency_key · string | null

An optional idempotency key. If a flow run with the same idempotency key has already been created, the existing flow run will be returned.

labels · Labels · object | null

A dictionary of key-value labels. Values can be strings, numbers, or booleans.

Show child attributes

Example:

{ "key": "value1", "key2": 42 }

parent_task_run_id · string<uuid> | null

work_queue_name · string | null

job_variables · Job Variables · object

Response

200

application/json

Successful Response

id · string<uuid> · required

created · string<date-time> | null · required

updated · string<date-time> | null · required

flow_id · string<uuid> · required

The id of the flow being run.

name · string

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

Example:

"my-flow-run"

state_id · string<uuid> | null

The id of the flow run's current state.

deployment_id · string<uuid> | null

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

deployment_version · string | null

The version of the deployment associated with this flow run.

Example:

"1.0"

work_queue_id · string<uuid> | null

The id of the run's work pool queue.

work_queue_name · string | null

The work queue that handled this flow run.

flow_version · string | null

The version of the flow executed in this flow run.

Example:

"1.0"

parameters · Parameters · object

Parameters for the flow run.

idempotency_key · string | null

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

context · Context · object

Additional context for the flow run.

Example:

{ "my_var": "my_val" }

empirical_policy · FlowRunPolicy · object

Defines of how a flow run should retry.

Show child attributes

tags · string[]

A list of tags on the flow run

Example:

["tag-1", "tag-2"]

labels · Labels · object

A dictionary of key-value labels. Values can be strings, numbers, or booleans.

Show child attributes

Example:

{ "key": "value1", "key2": 42 }

parent_task_run_id · string<uuid> | null

If the flow run is a subflow, the id of the 'dummy' task in the parent flow used to track subflow state.

state_type · enum<string> | null

The type of the current flow run state.

Available options: SCHEDULED, PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, CRASHED, PAUSED, CANCELLING

state_name · string | null

The name of the current flow run state.

run_count · integer · default: 0

The number of times the flow run was executed.

expected_start_time · string<date-time> | null

The flow run's expected start time.

next_scheduled_start_time · string<date-time> | null

The next time the flow run is scheduled to start.

start_time · string<date-time> | null

The actual start time.

end_time · string<date-time> | null

The actual end time.

total_run_time · number · default: 0

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

estimated_run_time · number · default: 0

A real-time estimate of the total run time.

estimated_start_time_delta · number · default: 0

The difference between actual and expected start time.

auto_scheduled · boolean · default: false

Whether or not the flow run was automatically scheduled.

infrastructure_document_id · string<uuid> | null

The block document defining infrastructure to use this flow run.

infrastructure_pid · string | null

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

created_by · CreatedBy · object | null

Optional information about the creator of this flow run.

Show child attributes

work_pool_id · string<uuid> | null

The id of the flow run's work pool.

work_pool_name · string | null

The name of the flow run's work pool.

Example:

"my-work-pool"

state · State · object | null

The current state of the flow run.

Show child attributes

job_variables · Job Variables · object | null

Variables used as overrides in the base job template