POST
/
api
/
task_runs
/
filter
[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created": "2023-11-07T05:31:56Z",
    "updated": "2023-11-07T05:31:56Z",
    "name": "my-task-run",
    "flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "task_key": "<string>",
    "dynamic_key": "<string>",
    "cache_key": "<string>",
    "cache_expiration": "2023-11-07T05:31:56Z",
    "task_version": "<string>",
    "empirical_policy": {
      "max_retries": 0,
      "retry_delay_seconds": 0,
      "retries": 123,
      "retry_delay": 123,
      "retry_jitter_factor": 123
    },
    "tags": [
      "tag-1",
      "tag-2"
    ],
    "state_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "task_inputs": {},
    "state_type": "SCHEDULED",
    "state_name": "<string>",
    "run_count": 0,
    "flow_run_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,
    "state": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "SCHEDULED",
      "name": "<string>",
      "timestamp": "2023-11-07T05:31:56Z",
      "message": "Run started",
      "data": "<any>",
      "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": true,
        "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"
      }
    }
  }
]

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
object

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

​
flow_runs
object

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

​
task_runs
object

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

​
deployments
object

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

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

​
id
string<uuid>
​
created
string<date-time> | null
​
updated
string<date-time> | null
​
name
string
Examples:

"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
object

Defines of how a task run should retry.

​
tags
string[]

A list of tags for the task run.

Examples:
["tag-1", "tag-2"]
​
state_id
string<uuid> | null

The id of the current task run state.

​
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. Enumeration of state types.

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
object | null

The current task run state. Represents the state of a run.