PRprefecthq
Task Runs

Create Task Run

Changed on

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/

Request

  • The document declares no server URL.
  • Auth
    none declared

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.

state_type'SCHEDULED' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'CRASHED' | 'PAUSED' | 'CANCELLING'

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

  • bc1bced1d6c9Revision changes
    • info

      added the new optional request property

  • 93ae2b3f2efdRevision changes
    • breaking

      added to the // request property allOf list

    • breaking

      added to the // request property allOf list

    • breaking

      the request property became required

    • breaking

      the request property // became required

    • breaking

      the request property became required

    • breaking

      removed the enum value CANCELLED of the request property //

    • breaking

      removed the enum value CANCELLING of the request property //

    • breaking

      removed the enum value COMPLETED of the request property //

    • breaking

      removed the enum value CRASHED of the request property //

    • breaking

      removed the enum value FAILED of the request property //

    • breaking

      removed the enum value PAUSED of the request property //

    • breaking

      removed the enum value PENDING of the request property //

    • breaking

      removed the enum value RUNNING of the request property //

    • breaking

      removed the enum value SCHEDULED of the request property //

    • breaking

      the // request property type changed from object to no type

    • breaking

      the // request property type changed from string to no type

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///