Admin5

Artifacts9

Automations10

Block capabilities1

Block documents6

Block schemas5

Block types9

Collections1

Concurrency Limits7

Concurrency Limits V27

Deployments19

Events4

Flow Run Notification Policies5

Flow Run States2

Flow Runs17

Flows7

Logs2

Root4

SavedSearches4

Task Run States2

Task Runs10

UI1

Variables9

Work Pools15

Work Queues8

getCreate Csrf Token

Task Runs

Create Task Run

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.

post/api/task_runs/

Headers

x-prefect-api-versionstring

Request body

idstring uuid

The ID to use for the task run. If not provided, a random UUID will be generated.

namestring

flow_run_idstring uuid

The flow run id of the task run.

task_keystring required

A unique identifier for the task being run.

dynamic_keystring required

A dynamic key used to differentiate between multiple runs of the same task within the same flow run.

cache_keystring

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_expirationstring date-time

Specifies when the cached state should expire.

task_versionstring

The version of the task being run.

tagsstring[]

A list of tags for the task run.

task_inputsobject

The inputs to the task run.

Example request

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

Response

Successful Response

idstring uuid

createdstring date-time

updatedstring date-time

namestring

flow_run_idstring uuid

The flow run id of the task run.

task_keystring required

A unique identifier for the task being run.

dynamic_keystring required

A dynamic key used to differentiate between multiple runs of the same task within the same flow run.

cache_keystring

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_expirationstring date-time

Specifies when the cached state should expire.

task_versionstring

The version of the task being run.

tagsstring[]

A list of tags for the task run.

state_idstring uuid

The id of the current task run state.

task_inputsobject

Tracks the source of inputs to a task run. Used for internal bookkeeping.

Enumeration of state types.

state_namestring

The name of the current task run state.

run_countinteger

The number of times the task run has been executed.

flow_run_run_countinteger

If the parent flow has retried, this indicates the flow retry this run is associated with.

expected_start_timestring date-time

The task run's expected start time.

next_scheduled_start_timestring date-time

The next time the task 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 task run was executed multiple times, the time of each run will be summed.

estimated_run_timenumber

A real-time estimate of total run time.

estimated_start_time_deltanumber

The difference between actual and expected start time.

Example response

{
  "name": "my-task-run",
  "tags": [
    "tag-1",
    "tag-2"
  ],
  "state": {
    "message": "Run started"
  }
}

Changes

Changed in 2 of the 50 revisions of this API.16151

May 31, 2024bc1bced1d6c91See the full diff
- ○
  added the new optional request property id
  new-optional-request-property
Apr 3, 202493ae2b3f2efd1615See the full diff
- ▲
  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 dynamic_key became required
  request-property-became-required
- ▲
  the request property state/allOf[subschema #1: StateCreate]/type became required
  request-property-became-required
- ▲
  the request property task_key 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 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 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

Full history