Read Work Queue Runs

Get flow runs from the work queue.

Headers

x-prefect-ui

boolean | null

default:

false

A header to indicate this request came from the Prefect UI.

x-prefect-api-version

string

Path Parameters

id

string

required

The work queue id

Body

application/json

agent_id

string | null

An optional unique identifier for the agent making this query. If provided, the Prefect REST API will track the last time this agent polled the work queue.

limit

integer

Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.

scheduled_before

string

Only flow runs scheduled to start before this time will be returned.

Response

200 - application/json

created

string | null

required

flow_id

string

required

The id of the flow being run.

id

string

required

updated

string | null

required

auto_scheduled

boolean

default:

false

Whether or not the flow run was automatically scheduled.

context

object

Additional context for the flow run.

created_by

object | null

Optional information about the creator of this flow run.

Show child attributes

created_by.display_value

string | null

The display value for the creator.

created_by.id

string | null

The id of the creator of the object.

created_by.type

string | null

The type of the creator of the object.

deployment_id

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

empirical_policy

object

Defines of how a flow run should retry.

Show child attributes

empirical_policy.max_retries

integer

default:

0

deprecated

The maximum number of retries. Field is not used. Please use retries instead.

empirical_policy.pause_keys

string[] | null

Tracks pauses this run has observed.

empirical_policy.resuming

boolean | null

default:

false

Indicates if this run is resuming from a pause.

empirical_policy.retries

integer | null

The number of retries.

empirical_policy.retry_delay

integer | null

The delay time between retries, in seconds.

empirical_policy.retry_delay_seconds

number

default:

0

deprecated

The delay between retries. Field is not used. Please use retry_delay instead.

empirical_policy.retry_type

enum<string> | null

The type of retry this run is undergoing.

Available options:

in_process,

reschedule

end_time

string | null

The actual end time.

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.

expected_start_time

string | null

The flow run's expected start time.

flow_version

string | null

The version of the flow executed in this 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.

infrastructure_document_id

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

job_variables

object | null

Variables used as overrides in the base job template

labels

object

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

Show child attributes

labels.{key}

name

string

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

next_scheduled_start_time

string | null

The next time the flow run is scheduled to start.

parameters

object

Parameters for the flow run.

parent_task_run_id

string | null

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

run_count

integer

default:

0

The number of times the flow run was executed.

start_time

string | null

The actual start time.

state

object | null

The current state of the flow run.

Show child attributes

state.id

string

required

state.type

enum<string>

required

Enumeration of state types.

Available options:

SCHEDULED,

PENDING,

RUNNING,

COMPLETED,

FAILED,

CANCELLED,

CRASHED,

PAUSED,

CANCELLING

state.data

any | null

Data associated with the state, e.g. a result. Content must be storable as JSON.

state.message

string | null

state.name

string | null

state.state_details

object

Show child attributes

state.state_details.cache_expiration

string | null

state.state_details.cache_key

string | null

state.state_details.child_flow_run_id

string | null

state.state_details.deferred

boolean | null

default:

false

state.state_details.flow_run_id

string | null

state.state_details.pause_key

string | null

state.state_details.pause_reschedule

boolean

default:

false

state.state_details.pause_timeout

string | null

state.state_details.refresh_cache

boolean | null

state.state_details.retriable

boolean | null

state.state_details.run_input_keyset

object | null

Show child attributes

state.state_details.run_input_keyset.{key}

string

state.state_details.scheduled_time

string | null

state.state_details.task_parameters_id

string | null

state.state_details.task_run_id

string | null

state.state_details.traceparent

string | null

state.state_details.transition_id

string | null

state.state_details.untrackable_result

boolean

default:

false

state.timestamp

string

state_id

string | null

The id of the flow run's current state.

state_name

string | null

The name of the current flow run 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

tags

string[]

A list of tags on the flow run

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.

work_pool_id

string | null

The id of the flow run's work pool.

work_pool_name

string | null

The name of the flow run's work pool.

work_queue_id

string | null

The id of the run's work pool queue.

work_queue_name

string | null

The work queue that handled this flow run.