Read Deployments

Query for deployments.

Headers

x-prefect-api-version

string

Body

application/json

deployments

object

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

Show child attributes

deployments.concurrency_limit

object | null

deprecated

DEPRECATED: Prefer Deployment.concurrency_limit_id over Deployment.concurrency_limit. If provided, will be ignored for backwards-compatibility. Will be removed after December 2024.

Show child attributes

deployments.concurrency_limit.ge_

integer | null

Only include deployments with a concurrency limit greater than or equal to this value

deployments.concurrency_limit.is_null_

boolean | null

If true, only include deployments without a concurrency limit

deployments.concurrency_limit.le_

integer | null

Only include deployments with a concurrency limit less than or equal to this value

deployments.flow_or_deployment_name

object | null

Filter criteria for Deployment.name or Flow.name

Show child attributes

deployments.flow_or_deployment_name.like_

string | null

A case-insensitive partial match on deployment or flow names. For example, passing 'example' might match deployments or flows with 'example' in their names.

deployments.id

object | null

Filter criteria for Deployment.id

Show child attributes

deployments.id.any_

string[] | null

A list of deployment ids to include

deployments.name

object | null

Filter criteria for Deployment.name

Show child attributes

deployments.name.any_

string[] | null

A list of deployment names to include

deployments.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

deployments.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

deployments.paused

object | null

Filter criteria for Deployment.paused

Show child attributes

deployments.paused.eq_

boolean | null

Only returns where deployment is/is not paused

deployments.tags

object | null

Filter criteria for Deployment.tags

Show child attributes

deployments.tags.all_

string[] | null

A list of tags. Deployments will be returned only if their tags are a superset of the list

deployments.tags.any_

string[] | null

A list of tags to include

deployments.tags.is_null_

boolean | null

If true, only include deployments without tags

deployments.tags.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

deployments.work_queue_name

object | null

Filter criteria for Deployment.work_queue_name

Show child attributes

deployments.work_queue_name.any_

string[] | null

A list of work queue names to include

flow_runs

object

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

Show child attributes

flow_runs.deployment_id

object | null

Filter criteria for FlowRun.deployment_id

Show child attributes

flow_runs.deployment_id.any_

string[] | null

A list of flow run deployment ids to include

flow_runs.deployment_id.is_null_

boolean | null

If true, only include flow runs without deployment ids

flow_runs.deployment_id.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.end_time

object | null

Filter criteria for FlowRun.end_time

Show child attributes

flow_runs.end_time.after_

string | null

Only include flow runs ending at or after this time

flow_runs.end_time.before_

string | null

Only include flow runs ending at or before this time

flow_runs.end_time.is_null_

boolean | null

If true, only return flow runs without an end time

flow_runs.expected_start_time

object | null

Filter criteria for FlowRun.expected_start_time

Show child attributes

flow_runs.expected_start_time.after_

string | null

Only include flow runs scheduled to start at or after this time

flow_runs.expected_start_time.before_

string | null

Only include flow runs scheduled to start at or before this time

flow_runs.flow_version

object | null

Filter criteria for FlowRun.flow_version

Show child attributes

flow_runs.flow_version.any_

string[] | null

A list of flow run flow_versions to include

flow_runs.id

object | null

Filter criteria for FlowRun.id

Show child attributes

flow_runs.id.any_

string[] | null

A list of flow run ids to include

flow_runs.id.not_any_

string[] | null

A list of flow run ids to exclude

flow_runs.idempotency_key

object | null

Filter criteria for FlowRun.idempotency_key

Show child attributes

flow_runs.idempotency_key.any_

string[] | null

A list of flow run idempotency keys to include

flow_runs.idempotency_key.not_any_

string[] | null

A list of flow run idempotency keys to exclude

flow_runs.name

object | null

Filter criteria for FlowRun.name

Show child attributes

flow_runs.name.any_

string[] | null

A list of flow run names to include

flow_runs.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

flow_runs.next_scheduled_start_time

object | null

Filter criteria for FlowRun.next_scheduled_start_time

Show child attributes

flow_runs.next_scheduled_start_time.after_

string | null

Only include flow runs with a next_scheduled_start_time at or after this time

flow_runs.next_scheduled_start_time.before_

string | null

Only include flow runs with a next_scheduled_start_time or before this time

flow_runs.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.parent_flow_run_id

object | null

Filter criteria for subflows of the given flow runs

Show child attributes

flow_runs.parent_flow_run_id.any_

string[] | null

A list of parent flow run ids to include

flow_runs.parent_flow_run_id.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.parent_task_run_id

object | null

Filter criteria for FlowRun.parent_task_run_id

Show child attributes

flow_runs.parent_task_run_id.any_

string[] | null

A list of flow run parent_task_run_ids to include

flow_runs.parent_task_run_id.is_null_

boolean | null

If true, only include flow runs without parent_task_run_id

flow_runs.parent_task_run_id.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.start_time

object | null

Filter criteria for FlowRun.start_time

Show child attributes

flow_runs.start_time.after_

string | null

Only include flow runs starting at or after this time

flow_runs.start_time.before_

string | null

Only include flow runs starting at or before this time

flow_runs.start_time.is_null_

boolean | null

If true, only return flow runs without a start time

flow_runs.state

object | null

Filter criteria for FlowRun.state

Show child attributes

flow_runs.state.name

object | null

Filter criteria for FlowRun.state_name

Show child attributes

flow_runs.state.name.any_

string[] | null

A list of flow run state names to include

flow_runs.state.name.not_any_

string[] | null

A list of flow run state names to exclude

flow_runs.state.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.state.type

object | null

Filter criteria for FlowRun.state_type

Show child attributes

flow_runs.state.type.any_

enum<string>[] | null

A list of flow run state types to include

Available options:

SCHEDULED,

PENDING,

RUNNING,

COMPLETED,

FAILED,

CANCELLED,

CRASHED,

PAUSED,

CANCELLING

flow_runs.state.type.not_any_

enum<string>[] | null

A list of flow run state types to exclude

Available options:

SCHEDULED,

PENDING,

RUNNING,

COMPLETED,

FAILED,

CANCELLED,

CRASHED,

PAUSED,

CANCELLING

flow_runs.tags

object | null

Filter criteria for FlowRun.tags

Show child attributes

flow_runs.tags.all_

string[] | null

A list of tags. Flow runs will be returned only if their tags are a superset of the list

flow_runs.tags.any_

string[] | null

A list of tags to include

flow_runs.tags.is_null_

boolean | null

If true, only include flow runs without tags

flow_runs.tags.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.work_queue_name

object | null

Filter criteria for `FlowRun.work_queue_name

Show child attributes

flow_runs.work_queue_name.any_

string[] | null

A list of work queue names to include

flow_runs.work_queue_name.is_null_

boolean | null

If true, only include flow runs without work queue names

flow_runs.work_queue_name.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flows

object

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

Show child attributes

flows.deployment

object | null

Filter criteria for Flow deployments

Show child attributes

flows.deployment.is_null_

boolean | null

If true, only include flows without deployments

flows.deployment.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flows.id

object | null

Filter criteria for Flow.id

Show child attributes

flows.id.any_

string[] | null

A list of flow ids to include

flows.name

object | null

Filter criteria for Flow.name

Show child attributes

flows.name.any_

string[] | null

A list of flow names to include

flows.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

flows.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flows.tags

object | null

Filter criteria for Flow.tags

Show child attributes

flows.tags.all_

string[] | null

A list of tags. Flows will be returned only if their tags are a superset of the list

flows.tags.is_null_

boolean | null

If true, only include flows without tags

flows.tags.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

limit

integer

Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.

offset

integer

default:

0

Required range: x > 0

sort

enum<string>

Defines deployment sorting options.

Available options:

CREATED_DESC,

UPDATED_DESC,

NAME_ASC,

NAME_DESC

task_runs

object

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

Show child attributes

task_runs.expected_start_time

object | null

Filter criteria for TaskRun.expected_start_time

Show child attributes

task_runs.expected_start_time.after_

string | null

Only include task runs expected to start at or after this time

task_runs.expected_start_time.before_

string | null

Only include task runs expected to start at or before this time

task_runs.flow_run_id

object | null

Filter criteria for TaskRun.flow_run_id

Show child attributes

task_runs.flow_run_id.any_

string[] | null

A list of task run flow run ids to include

task_runs.flow_run_id.is_null_

boolean | null

default:

false

Filter for task runs with None as their flow run id

task_runs.flow_run_id.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

task_runs.id

object | null

Filter criteria for TaskRun.id

Show child attributes

task_runs.id.any_

string[] | null

A list of task run ids to include

task_runs.name

object | null

Filter criteria for TaskRun.name

Show child attributes

task_runs.name.any_

string[] | null

A list of task run names to include

task_runs.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

task_runs.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

task_runs.start_time

object | null

Filter criteria for TaskRun.start_time

Show child attributes

task_runs.start_time.after_

string | null

Only include task runs starting at or after this time

task_runs.start_time.before_

string | null

Only include task runs starting at or before this time

task_runs.start_time.is_null_

boolean | null

If true, only return task runs without a start time

task_runs.state

object | null

Filter criteria for TaskRun.state

Show child attributes

task_runs.state.name

object | null

Filter criteria for TaskRun.state_name

Show child attributes

task_runs.state.name.any_

string[] | null

A list of task run state names to include

task_runs.state.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

task_runs.state.type

object | null

Filter criteria for TaskRun.state_type

Show child attributes

task_runs.state.type.any_

enum<string>[] | null

A list of task run state types to include

Available options:

SCHEDULED,

PENDING,

RUNNING,

COMPLETED,

FAILED,

CANCELLED,

CRASHED,

PAUSED,

CANCELLING

task_runs.subflow_runs

object | null

Filter criteria for TaskRun.subflow_run

Show child attributes

task_runs.subflow_runs.exists_

boolean | null

If true, only include task runs that are subflow run parents; if false, exclude parent task runs

task_runs.tags

object | null

Filter criteria for TaskRun.tags

Show child attributes

task_runs.tags.all_

string[] | null

A list of tags. Task runs will be returned only if their tags are a superset of the list

task_runs.tags.is_null_

boolean | null

If true, only include task runs without tags

task_runs.tags.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

work_pool_queues

object

Filter work queues. Only work queues matching all criteria will be returned

Show child attributes

work_pool_queues.id

object | null

Filter criteria for WorkQueue.id

Show child attributes

work_pool_queues.id.any_

string[] | null

A list of work queue ids to include

work_pool_queues.name

object | null

Filter criteria for WorkQueue.name

Show child attributes

work_pool_queues.name.any_

string[] | null

A list of work queue names to include

work_pool_queues.name.startswith_

string[] | null

A list of case-insensitive starts-with matches. For example, passing 'marvin' will match 'marvin', and 'Marvin-robot', but not 'sad-marvin'.

work_pool_queues.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

work_pools

object

Filter work pools. Only work pools matching all criteria will be returned

Show child attributes

work_pools.id

object | null

Filter criteria for WorkPool.id

Show child attributes

work_pools.id.any_

string[] | null

A list of work pool ids to include

work_pools.name

object | null

Filter criteria for WorkPool.name

Show child attributes

work_pools.name.any_

string[] | null

A list of work pool names to include

work_pools.operator

enum<string>

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

work_pools.type

object | null

Filter criteria for WorkPool.type

Show child attributes

work_pools.type.any_

string[] | null

A list of work pool types to include

Response

200 - application/json

created

string | null

required

flow_id

string

required

The flow id associated with the deployment.

id

string

required

name

string

required

The name of the deployment.

updated

string | null

required

concurrency_limit

integer | null

deprecated

DEPRECATED: Prefer global_concurrency_limit. Will always be None for backwards compatibility. Will be removed after December 2024.

concurrency_options

object | null

The concurrency options for the deployment.

Show child attributes

concurrency_options.collision_strategy

enum<string>

required

Enumeration of concurrency collision strategies.

Available options:

ENQUEUE,

CANCEL_NEW

created_by

object | null

Optional information about the creator of this deployment.

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.

description

string | null

A description for the deployment.

enforce_parameter_schema

boolean

default:

true

Whether or not the deployment should enforce the parameter schema.

entrypoint

string | null

The path to the entrypoint for the workflow, relative to the path.

global_concurrency_limit

object | null

The global concurrency limit object for enforcing the maximum number of flow runs that can be active at once.

Show child attributes

global_concurrency_limit.active_slots

integer

required

The number of active slots.

global_concurrency_limit.created

string | null

required

global_concurrency_limit.id

string

required

global_concurrency_limit.limit

integer

required

The concurrency limit.

global_concurrency_limit.name

string

required

The name of the global concurrency limit.

global_concurrency_limit.updated

string | null

required

global_concurrency_limit.active

boolean

default:

true

Whether the global concurrency limit is active.

global_concurrency_limit.slot_decay_per_second

number

default:

2

The decay rate for active slots when used as a rate limit.

infrastructure_document_id

string | null

The block document defining infrastructure to use for flow runs.

job_variables

object

Overrides to apply to the base infrastructure block at runtime.

labels

object

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

Show child attributes

labels.{key}

last_polled

string | null

The last time the deployment was polled for status updates.

parameter_openapi_schema

object | null

The parameter schema of the flow, including defaults.

parameters

object

Parameters for flow runs scheduled by the deployment.

path

string | null

The path to the working directory for the workflow, relative to remote storage or an absolute path.

paused

boolean

default:

false

Whether or not the deployment is paused.

pull_steps

object[] | null

Pull steps for cloning and running this deployment.

schedules

object[]

A list of schedules for the deployment.

Show child attributes

schedules.created

string | null

required

schedules.id

string

required

schedules.schedule

object

required

The schedule for the deployment.

• Schedule
• Schedule
• Schedule

Show child attributes

schedules.schedule.interval

number

required

schedules.schedule.anchor_date

string

schedules.schedule.timezone

string | null

schedules.updated

string | null

required

schedules.active

boolean

default:

true

Whether or not the schedule is active.

schedules.deployment_id

string | null

The deployment id associated with this schedule.

schedules.max_scheduled_runs

integer | null

The maximum number of scheduled runs for the schedule.

Required range: x > 0

schedules.parameters

object

A dictionary of parameter value overrides.

status

enum<string> | null

default:

NOT_READY

Whether the deployment is ready to run flows.

Available options:

READY,

NOT_READY

storage_document_id

string | null

The block document defining storage used for this flow.

tags

string[]

A list of tags for the deployment

updated_by

object | null

Optional information about the updater of this deployment.

Show child attributes

updated_by.display_value

string | null

The display value for the updater.

updated_by.id

string | null

The id of the updater of the object.

updated_by.type

string | null

The type of the updater of the object.

version

string | null

An optional version for the deployment.

work_pool_name

string | null

The name of the deployment's work pool.

work_queue_name

string | null

The work queue for the deployment. If no work queue is set, work will not be scheduled.