Skip to main content
POST
Read Task Runs

Headers

x-prefect-api-version
string

Body

application/json
sort
enum<string>
default:ID_DESC

Defines task run sorting options.

Available options:
ID_DESC,
EXPECTED_START_TIME_ASC,
EXPECTED_START_TIME_DESC,
NAME_ASC,
NAME_DESC,
NEXT_SCHEDULED_START_TIME_ASC,
END_TIME_DESC
offset
integer
default:0
Required range: x >= 0
flows
FlowFilter · object | null

Filter for flows. Only flows matching all criteria will be returned.

flow_runs
FlowRunFilter · object | null

Filter flow runs. Only flow runs matching all criteria will be returned

task_runs
TaskRunFilter · object | null

Filter task runs. Only task runs matching all criteria will be returned

deployments
DeploymentFilter · object | null

Filter for deployments. Only deployments matching all criteria will be returned.

limit
integer

Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.

Response

Successful Response

id
string<uuid>
required
created
string<date-time> | null
required
updated
string<date-time> | null
required
task_key
string
required

A unique identifier for the task being run.

dynamic_key
string
required

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

name
string
Example:

"my-task-run"

flow_run_id
string<uuid> | null

The flow run id of the task run.

cache_key
string | null

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_expiration
string<date-time> | null

Specifies when the cached state should expire.

task_version
string | null

The version of the task being run.

empirical_policy
TaskRunPolicy · object

Defines of how a task run should retry.

tags
string[]

A list of tags for the task run.

Example:
labels
Labels · object | null

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

Example:
state_id
string<uuid> | null

The id of the current task run state.

task_inputs
Task Inputs · object

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

state_type
enum<string> | null

The type of the current task run state.

Available options:
SCHEDULED,
PENDING,
RUNNING,
COMPLETED,
FAILED,
CANCELLED,
CRASHED,
PAUSED,
CANCELLING
state_name
string | null

The name of the current task run state.

run_count
integer
default:0

The number of times the task run has been executed.

flow_run_run_count
integer
default:0

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

expected_start_time
string<date-time> | null

The task run's expected start time.

next_scheduled_start_time
string<date-time> | null

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

estimated_run_time
number
default:0

A real-time estimate of total run time.

estimated_start_time_delta
number
default:0

The difference between actual and expected start time.

state
State · object | null

The current task run state.