Prefect Work Queues API
Interact with a Workspace's Work Queues.
Interact with a Workspace's Work Queues.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/prefect-work-queues-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Prefect Cloud Account Billing Work Queues API
description: Prefect Cloud REST API documentation.
version: 0.8.4
tags:
- name: Work Queues
description: Interact with a Workspace's Work Queues.
externalDocs:
description: Configure dynamic infrastructure with work pools
url: https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues
paths:
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/:
post:
tags:
- Work Queues
summary: Create Work Queue
description: 'Creates a new work queue for the default agent work pool.
If a work queue with the same name already exists, an error
will be raised.
Required workspace scopes: `see_work_queues`'
operationId: create_work_queue_api_accounts__account_id__workspaces__workspace_id__work_queues__post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueueCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueueResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/{id}:
patch:
tags:
- Work Queues
summary: Update Work Queue
description: 'Updates an existing work queue.
Required workspace scopes: `write_work_queues`'
operationId: update_work_queue_api_accounts__account_id__workspaces__workspace_id__work_queues__id__patch
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The work queue id
title: Id
description: The work queue id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueueUpdate'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Work Queues
summary: Read Work Queue
description: 'Get a work queue by id.
Required workspace scopes: `see_work_queues`'
operationId: read_work_queue_api_accounts__account_id__workspaces__workspace_id__work_queues__id__get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The work queue id
title: Id
description: The work queue id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueueResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Work Queues
summary: Delete Work Queue
description: 'Delete a work queue by id.
Required workspace scopes: `manage_work_queues`'
operationId: delete_work_queue_api_accounts__account_id__workspaces__workspace_id__work_queues__id__delete
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The work queue id
title: Id
description: The work queue id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/name/{name}:
get:
tags:
- Work Queues
summary: Read Work Queue By Name
description: 'Get a work queue by id.
Required workspace scopes: `see_work_queues`'
operationId: read_work_queue_by_name_api_accounts__account_id__workspaces__workspace_id__work_queues_name__name__get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: name
in: path
required: true
schema:
type: string
description: The work queue name
title: Name
description: The work queue name
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueueResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/{id}/get_runs:
post:
tags:
- Work Queues
summary: Read Work Queue Runs
description: 'Get flow runs from the work queue.
Required workspace scopes: `see_work_queues`'
operationId: read_work_queue_runs_api_accounts__account_id__workspaces__workspace_id__work_queues__id__get_runs_post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The work queue id
title: Id
description: The work queue id
- name: x-prefect-ui
in: header
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: A header to indicate this request came from the Prefect UI.
default: false
title: X-Prefect-Ui
description: A header to indicate this request came from the Prefect UI.
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_read_work_queue_runs_api_accounts__account_id__workspaces__workspace_id__work_queues__id__get_runs_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlowRunResponse'
title: Response Read Work Queue Runs Api Accounts Account Id Workspaces Workspace Id Work Queues Id Get Runs Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/filter:
post:
tags:
- Work Queues
summary: Read Work Queues
description: 'Query for work queues.
Required workspace scopes: `see_work_queues`'
operationId: read_work_queues_api_accounts__account_id__workspaces__workspace_id__work_queues_filter_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_read_work_queues_api_accounts__account_id__workspaces__workspace_id__work_queues_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WorkQueueResponse'
title: Response Read Work Queues Api Accounts Account Id Workspaces Workspace Id Work Queues Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/paginate:
post:
tags:
- Work Queues
summary: Paginate Work Queues
description: 'Pagination query for work queues.
Required workspace scopes: `see_work_queues`'
operationId: paginate_work_queues_api_accounts__account_id__workspaces__workspace_id__work_queues_paginate_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_paginate_work_queues_api_accounts__account_id__workspaces__workspace_id__work_queues_paginate_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueuePaginatedResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/{id}/status:
get:
tags:
- Work Queues
summary: Read Work Queue Status
description: 'Get the status of a work queue.
Required workspace scopes: `see_work_queues`'
operationId: read_work_queue_status_api_accounts__account_id__workspaces__workspace_id__work_queues__id__status_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The work queue id
title: Id
description: The work queue id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueueStatusDetail'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_queues/{id}/concurrency_status:
post:
tags:
- Work Queues
summary: Read Work Queue Concurrency Status
description: 'Get the concurrency status of a work queue, including flow run details
for each slot holder.
Required workspace scopes: `see_work_queues`'
operationId: read_work_queue_concurrency_status_api_accounts__account_id__workspaces__workspace_id__work_queues__id__concurrency_status_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The work queue id
title: Id
description: The work queue id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_read_work_queue_concurrency_status_api_accounts__account_id__workspaces__workspace_id__work_queues__id__concurrency_status_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkQueueConcurrencyStatusPage'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
WorkQueueCreate:
properties:
name:
type: string
maxLength: 5000
pattern: ^[^/%&><]+$
title: Name
description: The name of the work queue.
description:
anyOf:
- type: string
maxLength: 5000
- type: 'null'
title: Description
description: An optional description for the work queue.
default: ''
is_paused:
type: boolean
title: Is Paused
description: Whether or not the work queue is paused.
default: false
concurrency_limit:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: Concurrency Limit
description: The work queue's concurrency limit.
priority:
anyOf:
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Priority
description: The queue's priority. Lower values are higher priority (1 is the highest).
filter:
anyOf:
- $ref: '#/components/schemas/QueueFilter'
- type: 'null'
description: 'DEPRECATED: Filter criteria for the work queue.'
deprecated: true
additionalProperties: false
type: object
required:
- name
title: WorkQueueCreate
description: Data used by the Prefect REST API to create a work queue.
CreatedBy:
properties:
id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Id
description: The id of the creator of the object.
type:
anyOf:
- type: string
- type: 'null'
title: Type
description: The type of the creator of the object.
display_value:
anyOf:
- type: string
- type: 'null'
title: Display Value
description: The display value for the creator.
type: object
title: CreatedBy
? Body_read_work_queue_concurrency_status_api_accounts__account_id__workspaces__workspace_id__work_queues__id__concurrency_status_post
: properties:
page:
type: integer
minimum: 1.0
title: Page
default: 1
limit:
type: integer
title: Limit
description: Defaults to PREFECT_ORION_API_DEFAULT_LIMIT if not provided.
type: object
title: Body_read_work_queue_concurrency_status_api_accounts__account_id__workspaces__workspace_id__work_queues__id__concurrency_status_post
WorkQueueResponse:
properties:
id:
type: string
format: uuid
title: Id
created:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created
updated:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated
name:
type: string
pattern: ^[^/%&><]+$
title: Name
description: The name of the work queue.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: An optional description for the work queue.
default: ''
is_paused:
type: boolean
title: Is Paused
description: Whether or not the work queue is paused.
default: false
concurrency_limit:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: Concurrency Limit
description: An optional concurrency limit for the work queue.
priority:
type: integer
exclusiveMinimum: 0.0
title: Priority
description: The queue's priority. Lower values are higher priority (1 is the highest).
default: 1
work_pool_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Work Pool Id
description: The work pool with which the queue is associated.
filter:
anyOf:
- $ref: '#/components/schemas/QueueFilter'
- type: 'null'
description: 'DEPRECATED: Filter criteria for the work queue.'
deprecated: true
last_polled:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Polled
description: The last time an agent polled this queue for work.
status:
anyOf:
- $ref: '#/components/schemas/WorkQueueStatus'
- type: 'null'
description: The work queue's current status.
work_pool:
anyOf:
- $ref: '#/components/schemas/WorkPool'
- type: 'null'
description: The work pool with which the queue is associated.
created_by:
anyOf:
- $ref: '#/components/schemas/CreatedBy'
- type: 'null'
description: Information about the creator of this work queue.
updated_by:
anyOf:
- $ref: '#/components/schemas/UpdatedBy'
- type: 'null'
description: Information about the updater of this work queue.
active_slots:
anyOf:
- type: integer
- type: 'null'
title: Active Slots
description: The number of active concurrency slots for the work queue.
work_pool_name:
anyOf:
- type: string
- type: 'null'
title: Work Pool Name
description: The name of the work pool the work pool resides within.
type: object
required:
- name
title: WorkQueueResponse
WorkQueuePaginatedResponse:
properties:
results:
items:
$ref: '#/components/schemas/WorkQueueResponse'
type: array
title: Results
count:
type: integer
title: Count
limit:
type: integer
title: Limit
pages:
type: integer
title: Pages
page:
type: integer
title: Page
type: object
required:
- results
- count
- limit
- pages
- page
title: WorkQueuePaginatedResponse
Body_read_work_queue_runs_api_accounts__account_id__workspaces__workspace_id__work_queues__id__get_runs_post:
properties:
scheduled_before:
type: string
format: date-time
title: Scheduled Before
description: Only flow runs scheduled to start before this time will be returned.
limit:
type: integer
title: Limit
description: Defaults to PREFECT_ORION_API_DEFAULT_LIMIT if not provided.
type: object
title: Body_read_work_queue_runs_api_accounts__account_id__workspaces__workspace_id__work_queues__id__get_runs_post
StateType:
type: string
enum:
- SCHEDULED
- PENDING
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
- CRASHED
- PAUSED
- CANCELLING
title: StateType
description: Enumeration of state types.
WorkPoolStorageConfiguration:
properties:
bundle_upload_step:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Bundle Upload Step
description: The step to use for uploading bundles to storage.
bundle_execution_step:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Bundle Execution Step
description: The step to use for executing bundles.
default_result_storage_block_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Default Result Storage Block Id
description: The block document ID of the default result storage block.
type: object
title: WorkPoolStorageConfiguration
description: A representation of a work pool's storage configuration
WorkPool:
properties:
id:
type: string
format: uuid
title: Id
created:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created
updated:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated
name:
type: string
pattern: ^[^/%&><]+$
title: Name
description: The name of the work pool.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: A description of the work pool.
type:
type: string
title: Type
description: The work pool type.
base_job_template:
additionalProperties: true
type: object
title: Base Job Template
description: The work pool's base job template.
is_paused:
type: boolean
title: Is Paused
description: Pausing the work pool stops the delivery of all work.
default: false
concurrency_limit:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: Concurrency Limit
description: A concurrency limit for the work pool.
is_push_pool:
type: boolean
title: Is Push Pool
description: Whether or not the work pool is a push pool. Push pools are not polled by workers to deliver work.
default: false
is_mex_pool:
type: boolean
title: Is Mex Pool
description: Whether or not the work pool is a managed pool. Managed pools execute work within Prefect Cloud.
default: false
status:
anyOf:
- $ref: '#/components/schemas/WorkPoolStatus'
- type: 'null'
description: The current status of the work pool.
default_queue_id:
type: string
format: uuid
title: Default Queue Id
description: The id of the pool's default queue.
storage_configuration:
$ref: '#/components/schemas/WorkPoolStorageConfiguration'
description: The storage configuration for the work pool.
last_polled:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Polled
description: The last time a worker polled this work pool for work.
created_by:
anyOf:
- $ref: '#/components/schemas/CreatedBy'
- type: 'null'
description: Information about the creator of this work pool.
updated_by:
anyOf:
- $ref: '#/components/schemas/UpdatedBy'
- type: 'null'
description: Information about the updater of this work pool.
type: object
required:
- name
- type
- default_queue_id
title: WorkPool
description: An ORM representation of a work pool
FlowRunSlotSummary:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
state_type:
anyOf:
- $ref: '#/components/schemas/StateType'
- type: 'null'
state_name:
anyOf:
- type: string
- type: 'null'
title: State Name
start_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Start Time
state_timestamp:
anyOf:
- type: string
format: date-time
- type: 'null'
title: State Timestamp
time_in_current_state:
anyOf:
- type: number
- type: 'null'
title: Time In Current State
type: object
required:
- id
- name
- state_type
- state_name
- start_time
- state_timestamp
- time_in_current_state
title: FlowRunSlotSummary
description: Summary of a flow run holding a concurrency slot.
WorkQueueStatusDetail:
properties:
healthy:
type: boolean
title: Healthy
description: Whether or not the work queue is healthy.
late_runs_count:
type: integer
title: Late Runs Count
description: The number of late flow runs in the work queue.
default: 0
last_polled:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Polled
description: The last time an agent polled this queue for work.
health_check_policy:
$ref: '#/components/schemas/WorkQueueHealthPolicy'
description: The policy used to determine whether or not the work queue is healthy.
type: object
required:
- healthy
- health_check_policy
title: WorkQueueStatusDetail
StateDetails:
properties:
flow_run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Flow Run Id
task_run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Task Run Id
child_flow_run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Child Flow Run Id
scheduled_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Scheduled Time
cache_key:
anyOf:
- type: string
- type: 'null'
title: Cache Key
cache_expiration:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Cache Expiration
deferred:
anyOf:
- type: boolean
- type: 'null'
title: Deferred
untrackable_result:
type: boolean
title: Untrackable Result
default: false
pause_timeout:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Pause Timeout
pause_reschedule:
type: boolean
title: Pause Reschedule
default: false
pause_key:
anyOf:
- type: string
- type: 'null'
title: Pause Key
run_input_keyset:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Run Input Keyset
refresh_cache:
anyOf:
- type: boolean
- type: 'null'
title: Refresh Cache
retriable:
anyOf:
- type: boolean
- type: 'null'
title: Retriable
transition_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Transition Id
task_parameters_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Task Parameters Id
traceparent:
anyOf:
- type: string
- type: 'null'
title: Traceparent
deployment_concurrency_lease_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Deployment Concurrency Lease Id
type: object
title: StateDetails
WorkQueueFilterName:
properties:
any_:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Any
description: A list of work queue names to include
examples:
- - wq-1
- wq-2
startswith_:
anyOf:
- items:
type: string
type: array
- type:
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prefect/refs/heads/main/openapi/prefect-work-queues-api-openapi.yml