---
title: "Read Deployments"
method: POST
path: "/api/deployments/filter"
tags: ["Deployments"]
---

# Read Deployments

`POST /api/deployments/filter`

Query for deployments.

## Headers

- `x-prefect-api-version` string

## Request body

- BodyReadDeploymentsDeploymentsFilterPost
  - `offset` integer
  - `flows` FlowFilter — Filter for flows. Only flows matching all criteria will be returned.
    - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
    - `id` FlowFilterId — Filter by `Flow.id`.
      - `any_` string[] — A list of flow ids to include
    - `deployment` FlowFilterDeployment — Filter by flows by deployment
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `is_null_` boolean — If true, only include flows without deployments
    - `name` FlowFilterName — Filter by `Flow.name`.
      - `any_` string[] — A list of flow names to include
      - `like_` string — A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.
    - `tags` FlowFilterTags — Filter by `Flow.tags`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `all_` string[] — A list of tags. Flows will be returned only if their tags are a superset of the list
      - `is_null_` boolean — If true, only include flows without tags
  - `flow_runs` FlowRunFilter — Filter flow runs. Only flow runs matching all criteria will be returned
    - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
    - `id` FlowRunFilterId — Filter by `FlowRun.id`.
      - `any_` string[] — A list of flow run ids to include
      - `not_any_` string[] — A list of flow run ids to exclude
    - `name` FlowRunFilterName — Filter by `FlowRun.name`.
      - `any_` string[] — A list of flow run names to include
      - `like_` string — A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.
    - `tags` FlowRunFilterTags — Filter by `FlowRun.tags`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `all_` string[] — A list of tags. Flow runs will be returned only if their tags are a superset of the list
      - `is_null_` boolean — If true, only include flow runs without tags
    - `deployment_id` FlowRunFilterDeploymentId — Filter by `FlowRun.deployment_id`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `any_` string[] — A list of flow run deployment ids to include
      - `is_null_` boolean — If true, only include flow runs without deployment ids
    - `work_queue_name` FlowRunFilterWorkQueueName — Filter by `FlowRun.work_queue_name`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `any_` string[] — A list of work queue names to include
      - `is_null_` boolean — If true, only include flow runs without work queue names
    - `state` FlowRunFilterState — Filter by `FlowRun.state_type` and `FlowRun.state_name`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `type` FlowRunFilterStateType — Filter by `FlowRun.state_type`.
        - `any_` StateType[] — A list of flow run state types to include
      - `name` FlowRunFilterStateName — Filter by `FlowRun.state_name`.
        - `any_` string[] — A list of flow run state names to include
    - `flow_version` FlowRunFilterFlowVersion — Filter by `FlowRun.flow_version`.
      - `any_` string[] — A list of flow run flow_versions to include
    - `start_time` FlowRunFilterStartTime — Filter by `FlowRun.start_time`.
      - `before_` string, date-time — Only include flow runs starting at or before this time
      - `after_` string, date-time — Only include flow runs starting at or after this time
      - `is_null_` boolean — If true, only return flow runs without a start time
    - `expected_start_time` FlowRunFilterExpectedStartTime — Filter by `FlowRun.expected_start_time`.
      - `before_` string, date-time — Only include flow runs scheduled to start at or before this time
      - `after_` string, date-time — Only include flow runs scheduled to start at or after this time
    - `next_scheduled_start_time` FlowRunFilterNextScheduledStartTime — Filter by `FlowRun.next_scheduled_start_time`.
      - `before_` string, date-time — Only include flow runs with a next_scheduled_start_time or before this time
      - `after_` string, date-time — Only include flow runs with a next_scheduled_start_time at or after this time
    - `parent_flow_run_id` FlowRunFilterParentFlowRunId — Filter for subflows of a given flow run
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `any_` string[] — A list of parent flow run ids to include
    - `parent_task_run_id` FlowRunFilterParentTaskRunId — Filter by `FlowRun.parent_task_run_id`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `any_` string[] — A list of flow run parent_task_run_ids to include
      - `is_null_` boolean — If true, only include flow runs without parent_task_run_id
    - `idempotency_key` FlowRunFilterIdempotencyKey — Filter by FlowRun.idempotency_key.
      - `any_` string[] — A list of flow run idempotency keys to include
      - `not_any_` string[] — A list of flow run idempotency keys to exclude
  - `task_runs` TaskRunFilter — Filter task runs. Only task runs matching all criteria will be returned
    - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
    - `id` TaskRunFilterId — Filter by `TaskRun.id`.
      - `any_` string[] — A list of task run ids to include
    - `name` TaskRunFilterName — Filter by `TaskRun.name`.
      - `any_` string[] — A list of task run names to include
      - `like_` string — A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.
    - `tags` TaskRunFilterTags — Filter by `TaskRun.tags`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `all_` string[] — A list of tags. Task runs will be returned only if their tags are a superset of the list
      - `is_null_` boolean — If true, only include task runs without tags
    - `state` TaskRunFilterState — Filter by `TaskRun.type` and `TaskRun.name`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `type` TaskRunFilterStateType — Filter by `TaskRun.state_type`.
        - `any_` StateType[] — A list of task run state types to include
      - `name` TaskRunFilterStateName — Filter by `TaskRun.state_name`.
        - `any_` string[] — A list of task run state names to include
    - `start_time` TaskRunFilterStartTime — Filter by `TaskRun.start_time`.
      - `before_` string, date-time — Only include task runs starting at or before this time
      - `after_` string, date-time — Only include task runs starting at or after this time
      - `is_null_` boolean — If true, only return task runs without a start time
    - `subflow_runs` TaskRunFilterSubFlowRuns — Filter by `TaskRun.subflow_run`.
      - `exists_` boolean — If true, only include task runs that are subflow run parents; if false, exclude parent task runs
    - `flow_run_id` TaskRunFilterFlowRunId — Filter by `TaskRun.flow_run_id`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `any_` string[] — A list of task run flow run ids to include
      - `is_null_` boolean — Filter for task runs with None as their flow run id
  - `deployments` DeploymentFilter — Filter for deployments. Only deployments matching all criteria will be returned.
    - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
    - `id` DeploymentFilterId — Filter by `Deployment.id`.
      - `any_` string[] — A list of deployment ids to include
    - `name` DeploymentFilterName — Filter by `Deployment.name`.
      - `any_` string[] — A list of deployment names to include
      - `like_` string — A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.
    - `paused` DeploymentFilterPaused — Filter by `Deployment.paused`.
      - `eq_` boolean — Only returns where deployment is/is not paused
    - `is_schedule_active` DeploymentFilterIsScheduleActive — Legacy filter to filter by `Deployment.is_schedule_active` which is always the opposite of `Deployment.paused`.
      - `eq_` boolean — Only returns where deployment schedule is/is not active
    - `tags` DeploymentFilterTags — Filter by `Deployment.tags`.
      - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
      - `all_` string[] — A list of tags. Deployments will be returned only if their tags are a superset of the list
      - `is_null_` boolean — If true, only include deployments without tags
    - `work_queue_name` DeploymentFilterWorkQueueName — Filter by `Deployment.work_queue_name`.
      - `any_` string[] — A list of work queue names to include
  - `work_pools` WorkPoolFilter — Filter work pools. Only work pools matching all criteria will be returned
    - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
    - `id` WorkPoolFilterId — Filter by `WorkPool.id`.
      - `any_` string[] — A list of work pool ids to include
    - `name` WorkPoolFilterName — Filter by `WorkPool.name`.
      - `any_` string[] — A list of work pool names to include
    - `type` WorkPoolFilterType — Filter by `WorkPool.type`.
      - `any_` string[] — A list of work pool types to include
  - `work_pool_queues` WorkQueueFilter — Filter work queues. Only work queues matching all criteria will be returned
    - `operator` 'and_' | 'or_' — Operators for combining filter criteria.
    - `id` WorkQueueFilterId — Filter by `WorkQueue.id`.
      - `any_` string[] — A list of work queue ids to include
    - `name` WorkQueueFilterName — Filter by `WorkQueue.name`.
      - `any_` string[] — A list of work queue names to include
      - `startswith_` string[] — A list of case-insensitive starts-with matches. For example, passing 'marvin' will match 'marvin', and 'Marvin-robot', but not 'sad-marvin'.
  - `sort` 'CREATED_DESC' | 'UPDATED_DESC' | 'NAME_ASC' | 'NAME_DESC' — Defines deployment sorting options.
  - `limit` integer — Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.

## Response `200`

Successful Response

- DeploymentResponse[]
  - `id` string, uuid
  - `created` string, date-time
  - `updated` string, date-time
  - `infra_overrides` object — Deprecated field. Use `job_variables` instead.
  - `name` string, required — The name of the deployment.
  - `version` string — An optional version for the deployment.
  - `description` string — A description for the deployment.
  - `flow_id` string, uuid, required — The flow id associated with the deployment.
  - `schedule` union — A schedule for the deployment.
    - IntervalSchedule — A schedule formed by adding `interval` increments to an `anchor_date`. If no `anchor_date` is supplied, the current UTC time is used. If a timezone-naive datetime is provided for `anchor_date`, it is assumed to be in the schedule's timezone (or UTC). Even if supplied with an IANA timezone, anchor dates are always stored as UTC offsets, so a `timezone` can be provided to determine localization behaviors like DST boundary handling. If none is provided it will be inferred from the anchor date. NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals. For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that *appear* to both be scheduled for 1am local time, even though they are an hour apart in UTC time. For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant. This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone. Args: interval (datetime.timedelta): an interval to schedule on. anchor_date (DateTimeTZ, optional): an anchor date to schedule increments against; if not provided, the current timestamp will be used. timezone (str, optional): a valid timezone string.
      - `interval` number, required
      - `anchor_date` string, date-time
      - `timezone` string
    - CronSchedule — Cron schedule NOTE: If the timezone is a DST-observing one, then the schedule will adjust itself appropriately. Cron's rules for DST are based on schedule times, not intervals. This means that an hourly cron schedule will fire on every new schedule hour, not every elapsed hour; for example, when clocks are set back this will result in a two-hour pause as the schedule will fire *the first time* 1am is reached and *the first time* 2am is reached, 120 minutes later. Longer schedules, such as one that fires at 9am every morning, will automatically adjust for DST. Args: cron (str): a valid cron string timezone (str): a valid timezone string in IANA tzdata format (for example, America/New_York). day_or (bool, optional): Control how croniter handles `day` and `day_of_week` entries. Defaults to True, matching cron which connects those values using OR. If the switch is set to False, the values are connected using AND. This behaves like fcron and enables you to e.g. define a job that executes each 2nd friday of a month by setting the days of month and the weekday.
      - `cron` string, required
      - `timezone` string
      - `day_or` boolean — Control croniter behavior for handling day and day_of_week entries.
    - RRuleSchedule — RRule schedule, based on the iCalendar standard ([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as implemented in `dateutils.rrule`. RRules are appropriate for any kind of calendar-date manipulation, including irregular intervals, repetition, exclusions, week day or day-of-month adjustments, and more. Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to to the initial timezone provided. A 9am daily schedule with a daylight saving time-aware start date will maintain a local 9am time through DST boundaries; a 9am daily schedule with a UTC start date will maintain a 9am UTC time. Args: rrule (str): a valid RRule string timezone (str, optional): a valid timezone string
      - `rrule` string, required
      - `timezone` string
  - `is_schedule_active` boolean — Whether or not the deployment schedule is active.
  - `paused` boolean — Whether or not the deployment is paused.
  - `schedules` DeploymentSchedule[] — A list of schedules for the deployment.
    - `id` string, uuid
    - `created` string, date-time
    - `updated` string, date-time
    - `deployment_id` string, uuid — The deployment id associated with this schedule.
    - `schedule` union, required — The schedule for the deployment.
      - IntervalSchedule — A schedule formed by adding `interval` increments to an `anchor_date`. If no `anchor_date` is supplied, the current UTC time is used. If a timezone-naive datetime is provided for `anchor_date`, it is assumed to be in the schedule's timezone (or UTC). Even if supplied with an IANA timezone, anchor dates are always stored as UTC offsets, so a `timezone` can be provided to determine localization behaviors like DST boundary handling. If none is provided it will be inferred from the anchor date. NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals. For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that *appear* to both be scheduled for 1am local time, even though they are an hour apart in UTC time. For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant. This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone. Args: interval (datetime.timedelta): an interval to schedule on. anchor_date (DateTimeTZ, optional): an anchor date to schedule increments against; if not provided, the current timestamp will be used. timezone (str, optional): a valid timezone string.
        - `interval` number, required
        - `anchor_date` string, date-time
        - `timezone` string
      - CronSchedule — Cron schedule NOTE: If the timezone is a DST-observing one, then the schedule will adjust itself appropriately. Cron's rules for DST are based on schedule times, not intervals. This means that an hourly cron schedule will fire on every new schedule hour, not every elapsed hour; for example, when clocks are set back this will result in a two-hour pause as the schedule will fire *the first time* 1am is reached and *the first time* 2am is reached, 120 minutes later. Longer schedules, such as one that fires at 9am every morning, will automatically adjust for DST. Args: cron (str): a valid cron string timezone (str): a valid timezone string in IANA tzdata format (for example, America/New_York). day_or (bool, optional): Control how croniter handles `day` and `day_of_week` entries. Defaults to True, matching cron which connects those values using OR. If the switch is set to False, the values are connected using AND. This behaves like fcron and enables you to e.g. define a job that executes each 2nd friday of a month by setting the days of month and the weekday.
        - `cron` string, required
        - `timezone` string
        - `day_or` boolean — Control croniter behavior for handling day and day_of_week entries.
      - RRuleSchedule — RRule schedule, based on the iCalendar standard ([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as implemented in `dateutils.rrule`. RRules are appropriate for any kind of calendar-date manipulation, including irregular intervals, repetition, exclusions, week day or day-of-month adjustments, and more. Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to to the initial timezone provided. A 9am daily schedule with a daylight saving time-aware start date will maintain a local 9am time through DST boundaries; a 9am daily schedule with a UTC start date will maintain a 9am UTC time. Args: rrule (str): a valid RRule string timezone (str, optional): a valid timezone string
        - `rrule` string, required
        - `timezone` string
    - `active` boolean — Whether or not the schedule is active.
    - `max_active_runs` integer — The maximum number of active runs for the schedule.
    - `max_scheduled_runs` integer — The maximum number of scheduled runs for the schedule.
    - `catchup` boolean — Whether or not a worker should catch up on Late runs for the schedule.
  - `job_variables` object — Overrides to apply to the base infrastructure block at runtime.
  - `parameters` object — Parameters for flow runs scheduled by the deployment.
  - `tags` string[] — A list of tags for the deployment
  - `work_queue_name` string — The work queue for the deployment. If no work queue is set, work will not be scheduled.
  - `last_polled` string, date-time — The last time the deployment was polled for status updates.
  - `parameter_openapi_schema` object — The parameter schema of the flow, including defaults.
  - `path` string — The path to the working directory for the workflow, relative to remote storage or an absolute path.
  - `pull_steps` object[] — Pull steps for cloning and running this deployment.
  - `entrypoint` string — The path to the entrypoint for the workflow, relative to the `path`.
  - `manifest_path` string — The path to the flow's manifest file, relative to the chosen storage.
  - `storage_document_id` string, uuid — The block document defining storage used for this flow.
  - `infrastructure_document_id` string, uuid — The block document defining infrastructure to use for flow runs.
  - `created_by` CreatedBy
    - `id` string, uuid — The id of the creator of the object.
    - `type` string — The type of the creator of the object.
    - `display_value` string — The display value for the creator.
  - `updated_by` UpdatedBy
    - `id` string, uuid — The id of the updater of the object.
    - `type` string — The type of the updater of the object.
    - `display_value` string — The display value for the updater.
  - `work_pool_name` string — The name of the deployment's work pool.
  - `status` 'READY' | 'NOT_READY' — Enumeration of deployment statuses.
  - `enforce_parameter_schema` boolean — Whether or not the deployment should enforce the parameter schema.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/prefecthq/apis/untitled-api.md) · [All operations](https://skmtc.dev/prefecthq/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/prefecthq/untitled-api/revisions/a7958ce57e96/schema)