Prefect Work Pools API
The Work Pools API from Prefect — 20 operation(s) for work pools.
OpenAPI Specification
openapi: 3.1.0
info:
title: Prefect Cloud Account Billing Work Pools API
description: Prefect Cloud REST API documentation.
version: 0.8.4
tags:
- name: Work Pools
paths:
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/configuration/preview:
post:
tags:
- Work Pools
summary: Preview Work Pool Configuration
operationId: preview_work_pool_configuration_api_accounts__account_id__workspaces__workspace_id__work_pools_configuration_preview_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: 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/Body_preview_work_pool_configuration_api_accounts__account_id__workspaces__workspace_id__work_pools_configuration_preview_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/:
post:
tags:
- Work Pools
summary: Create Work Pool
description: 'Creates a new work pool. If a work pool with the same
name already exists, an error will be raised.
Required workspace scopes: `write_work_pools`'
operationId: create_work_pool_api_accounts__account_id__workspaces__workspace_id__work_pools__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: 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/WorkPoolCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkPoolResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/{name}:
get:
tags:
- Work Pools
summary: Read Work Pool
description: 'Read a work pool by name
Required workspace scopes: `see_work_pools`'
operationId: read_work_pool_api_accounts__account_id__workspaces__workspace_id__work_pools__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 pool name
title: Name
description: The work pool 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/WorkPoolResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Work Pools
summary: Update Work Pool
description: 'Update a work pool
Required workspace scopes: `write_work_pools`'
operationId: update_work_pool_api_accounts__account_id__workspaces__workspace_id__work_pools__name__patch
parameters:
- name: name
in: path
required: true
schema:
type: string
description: The work pool name
title: Name
description: The work pool name
- 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/WorkPoolUpdate'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Work Pools
summary: Delete Work Pool
description: 'Delete a work pool
Required workspace scopes: `manage_work_pools`'
operationId: delete_work_pool_api_accounts__account_id__workspaces__workspace_id__work_pools__name__delete
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 pool name
title: Name
description: The work pool 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:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/filter:
post:
tags:
- Work Pools
summary: Read Work Pools
description: 'Read multiple work pools
Required workspace scopes: `see_work_pools`'
operationId: read_work_pools_api_accounts__account_id__workspaces__workspace_id__work_pools_filter_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: 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_pools_api_accounts__account_id__workspaces__workspace_id__work_pools_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WorkPoolResponse'
title: Response Read Work Pools Api Accounts Account Id Workspaces Workspace Id Work Pools Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/paginate:
post:
tags:
- Work Pools
summary: Paginate Work Pools
description: 'Paginated query for work pools.
Required workspace scopes: `see_work_pools`'
operationId: paginate_work_pools_api_accounts__account_id__workspaces__workspace_id__work_pools_paginate_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: 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_pools_api_accounts__account_id__workspaces__workspace_id__work_pools_paginate_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkPoolPaginationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/count:
post:
tags:
- Work Pools
summary: Count Work Pools
description: 'Count work pools
Required workspace scopes: `see_work_pools`'
operationId: count_work_pools_api_accounts__account_id__workspaces__workspace_id__work_pools_count_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: 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_count_work_pools_api_accounts__account_id__workspaces__workspace_id__work_pools_count_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: integer
title: Response Count Work Pools Api Accounts Account Id Workspaces Workspace Id Work Pools Count Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/{name}/get_scheduled_flow_runs:
post:
tags:
- Work Pools
summary: Get Scheduled Flow Runs
description: 'Load scheduled runs for a worker
Required workspace scopes: `see_work_queues`'
operationId: get_scheduled_flow_runs_api_accounts__account_id__workspaces__workspace_id__work_pools__name__get_scheduled_flow_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: name
in: path
required: true
schema:
type: string
description: The work pool name
title: Name
description: The work pool name
- 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_get_scheduled_flow_runs_api_accounts__account_id__workspaces__workspace_id__work_pools__name__get_scheduled_flow_runs_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WorkerFlowRunResponse'
title: Response Get Scheduled Flow Runs Api Accounts Account Id Workspaces Workspace Id Work Pools Name Get Scheduled Flow Runs Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/{name}/access:
get:
tags:
- Work Pools
summary: Read Work Pool Access
description: 'Read access controls for a work_pool.
Required workspace scopes: `see_work_pools`'
operationId: read_work_pool_access_api_accounts__account_id__workspaces__workspace_id__work_pools__name__access_get
parameters:
- name: name
in: path
required: true
schema:
type: string
description: The work pool name
title: Name
description: The work pool name
- 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: 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/WorkPoolAccessControl'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Work Pools
summary: Set Work Pool Access
description: 'Set access controls for a work_pool.
The given access controls will replace any existing access controls.
Required workspace scopes: `manage_work_pools`'
operationId: set_work_pool_access_api_accounts__account_id__workspaces__workspace_id__work_pools__name__access_put
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 pool name
title: Name
description: The work pool 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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_set_work_pool_access_api_accounts__account_id__workspaces__workspace_id__work_pools__name__access_put'
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_pools/my-access:
post:
tags:
- Work Pools
summary: Read Actors Work Pool Access
description: 'Read access controls for a set of work pools and return the resolved
access levels for the current actor.
Required workspace scopes: `see_work_pools`'
operationId: read_actors_work_pool_access_api_accounts__account_id__workspaces__workspace_id__work_pools_my_access_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: 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_actors_work_pool_access_api_accounts__account_id__workspaces__workspace_id__work_pools_my_access_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
type: string
title: Response Read Actors Work Pool Access Api Accounts Account Id Workspaces Workspace Id Work Pools My Access Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/{work_pool_name}/queues:
post:
tags:
- Work Pools
summary: Create Work Queue
description: 'Creates a new work pool queue. If a work pool queue with the same
name already exists, an error will be raised.
Required workspace scopes: `write_work_queues`'
operationId: create_work_queue_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__queues_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool 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
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_pools/{work_pool_name}/queues/{name}:
get:
tags:
- Work Pools
summary: Read Work Queue
description: 'Read a work pool queue
Required workspace scopes: `see_work_queues`'
operationId: read_work_queue_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__queues__name__get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool name
- name: name
in: path
required: true
schema:
type: string
description: The work pool queue name
title: Name
description: The work pool 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'
patch:
tags:
- Work Pools
summary: Update Work Queue
description: 'Update a work pool queue
Required workspace scopes: `write_work_queues`'
operationId: update_work_queue_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__queues__name__patch
parameters:
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool name
- name: name
in: path
required: true
schema:
type: string
description: The work pool queue name
title: Name
description: The work pool queue name
- 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'
delete:
tags:
- Work Pools
summary: Delete Work Queue
description: 'Delete a work pool queue
Required workspace scopes: `manage_work_queues`'
operationId: delete_work_queue_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__queues__name__delete
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool name
- name: name
in: path
required: true
schema:
type: string
description: The work pool queue name
title: Name
description: The work pool 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:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/{work_pool_name}/queues/filter:
post:
tags:
- Work Pools
summary: Read Work Queues
description: 'Read all work pool queues
Required workspace scopes: `see_work_queues`'
operationId: read_work_queues_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__queues_filter_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool 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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_read_work_queues_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__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 Pools Work Pool Name Queues Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/work_pools/{work_pool_name}/queues/paginate:
post:
tags:
- Work Pools
summary: Paginate Work Queues
description: 'Pagination query for work pool queues
Required workspace scopes: `see_work_queues`'
operationId: paginate_work_queues_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__queues_paginate_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool 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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_paginate_work_queues_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__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_pools/{work_pool_name}/workers/heartbeat:
post:
tags:
- Work Pools
summary: Worker Heartbeat
description: '
Required workspace scopes: `write_workers`'
operationId: worker_heartbeat_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__workers_heartbeat_post
parameters:
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool name
- 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: 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/Body_worker_heartbeat_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__workers_heartbeat_post'
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_pools/{work_pool_name}/workers/filter:
post:
tags:
- Work Pools
summary: Read Workers
description: 'Read all worker processes
Required workspace scopes: `see_workers`'
operationId: read_workers_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__workers_filter_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: work_pool_name
in: path
required: true
schema:
type: string
description: The work pool name
title: Work Pool Name
description: The work pool 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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_read_workers_api_accounts__account_id__workspaces__workspace_id__work_pools__work_pool_name__workers_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Worker'
title: Response Read Workers Api Accounts Account Id Workspaces Workspace Id Work Pools Work Pool Name Workers Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
# --- truncated at 32 KB (132 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prefect/refs/heads/main/openapi/prefect-work-pools-api-openapi.yml