OpenAPI Specification
openapi: 3.1.0
info:
title: Prefect Cloud Account Billing Flow Runs API
description: Prefect Cloud REST API documentation.
version: 0.8.4
tags:
- name: Flow Runs
description: Interact with a Workspace's Flow Runs.
externalDocs:
description: Write and run flows
url: https://docs.prefect.io/v3/develop/write-flows
paths:
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/:
post:
tags:
- Flow Runs
summary: Create Flow Run
description: 'Create a flow run. If a flow run with the same flow_id and
idempotency key already exists, the existing flow run will be returned.
If no state is provided, the flow run will be created in a PENDING state.
Required workspace scopes: `run_flows`'
operationId: create_flow_run_api_accounts__account_id__workspaces__workspace_id__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: 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/FlowRunCreate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FlowRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/filter:
post:
tags:
- Flow Runs
summary: Read Flow Runs
description: 'Query for flow runs.
Required workspace scopes: `see_flows`'
operationId: read_flow_runs_api_accounts__account_id__workspaces__workspace_id__flow_runs_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_flow_runs_api_accounts__account_id__workspaces__workspace_id__flow_runs_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlowRunResponse'
title: Response Read Flow Runs Api Accounts Account Id Workspaces Workspace Id Flow Runs Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/filter-minimal:
post:
tags:
- Flow Runs
summary: Read Flow Runs Minimal
description: 'A flow runs filter that excludes full state data -- and possibly other
data in the future -- for improved performance.
Note that the state name, state type, and state ID are all still available.
Required workspace scopes: `see_flows`'
operationId: read_flow_runs_minimal_api_accounts__account_id__workspaces__workspace_id__flow_runs_filter_minimal_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_flow_runs_minimal_api_accounts__account_id__workspaces__workspace_id__flow_runs_filter_minimal_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MinimalFlowRun'
title: Response Read Flow Runs Minimal Api Accounts Account Id Workspaces Workspace Id Flow Runs Filter Minimal Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}:
patch:
tags:
- Flow Runs
summary: Update Flow Run
description: 'Updates a flow run.
Required workspace scopes: `run_flows`'
operationId: update_flow_run_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__patch
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 flow run id
title: Id
description: The flow run 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/FlowRunUpdate'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Flow Runs
summary: Read Flow Run
description: 'Get a flow run by id.
Required workspace scopes: `see_flows`'
operationId: read_flow_run_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__get
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The flow run id
title: Id
description: The flow run 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FlowRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Flow Runs
summary: Delete Flow Run
description: 'Delete a flow run by id.
Required workspace scopes: `manage_flows`'
operationId: delete_flow_run_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__delete
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The flow run id
title: Id
description: The flow run 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
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/count:
post:
tags:
- Flow Runs
summary: Count Flow Runs
description: 'Query for flow runs.
Required workspace scopes: `see_flows`'
operationId: count_flow_runs_api_accounts__account_id__workspaces__workspace_id__flow_runs_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_flow_runs_api_accounts__account_id__workspaces__workspace_id__flow_runs_count_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: integer
title: Response Count Flow Runs Api Accounts Account Id Workspaces Workspace Id Flow Runs Count Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/lateness:
post:
tags:
- Flow Runs
summary: Average Flow Run Lateness
description: 'Query for average flow-run lateness in seconds.
Required workspace scopes: `see_flows`'
operationId: average_flow_run_lateness_api_accounts__account_id__workspaces__workspace_id__flow_runs_lateness_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_average_flow_run_lateness_api_accounts__account_id__workspaces__workspace_id__flow_runs_lateness_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- type: number
- type: 'null'
title: Response Average Flow Run Lateness Api Accounts Account Id Workspaces Workspace Id Flow Runs Lateness Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/history:
post:
tags:
- Flow Runs
summary: Flow Run History
description: 'Query for flow run history data across a given range and interval.
Required workspace scopes: `see_flows`'
operationId: flow_run_history_api_accounts__account_id__workspaces__workspace_id__flow_runs_history_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_flow_run_history_api_accounts__account_id__workspaces__workspace_id__flow_runs_history_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HistoryResponse'
title: Response Flow Run History Api Accounts Account Id Workspaces Workspace Id Flow Runs History Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}/graph:
get:
tags:
- Flow Runs
summary: Read Flow Run Graph V1
description: 'Get a task run dependency map for a given flow run.
Required workspace scopes: `see_flows`'
operationId: read_flow_run_graph_v1_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__graph_get
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The flow run id
title: Id
description: The flow run id
- 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:
type: array
items:
$ref: '#/components/schemas/DependencyResult'
title: Response Read Flow Run Graph V1 Api Accounts Account Id Workspaces Workspace Id Flow Runs Id Graph Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}/graph-v2:
get:
tags:
- Flow Runs
summary: Read Flow Run Graph V2
description: 'Get a graph of the tasks and subflow runs for the given flow run
Required workspace scopes: `see_flows`'
operationId: read_flow_run_graph_v2_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__graph_v2_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 flow run id
title: Id
description: The flow run id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: since
in: query
required: false
schema:
type: string
format: date-time
description: Only include runs that start or end after this time.
default: '0001-01-01T00:00:00'
title: Since
description: Only include runs that start or end after this time.
- 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/Graph'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}/artifacts:
get:
tags:
- Flow Runs
summary: Get Flow Run Artifacts
description: 'Get all artifacts created within a flow run, including artifacts from
task runs and subflow runs (recursively).
Required workspace scopes: `see_flows`'
operationId: get_flow_run_artifacts_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__artifacts_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 flow run id
title: Id
description: The flow run id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: depth
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
description: Optional depth limit for recursion (0 = flow run only)
title: Depth
description: Optional depth limit for recursion (0 = flow run only)
- name: since
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only return artifacts created on or after this timestamp
title: Since
description: Only return artifacts created on or after this timestamp
- name: until
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only return artifacts created on or before this timestamp
title: Until
description: Only return artifacts created on or before this timestamp
- name: sort
in: query
required: false
schema:
enum:
- asc
- desc
type: string
description: Sort order by creation time (asc or desc)
default: desc
title: Sort
description: Sort order by creation time (asc or desc)
- 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:
type: array
items:
$ref: '#/components/schemas/Artifact'
title: Response Get Flow Run Artifacts Api Accounts Account Id Workspaces Workspace Id Flow Runs Id Artifacts Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}/resume:
post:
tags:
- Flow Runs
summary: Resume Flow Run
description: 'Resume a paused flow run.
Required workspace scopes: `run_flows`'
operationId: resume_flow_run_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__resume_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 flow run id
title: Id
description: The flow run 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_resume_flow_run_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__resume_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationResult'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/bulk_delete:
post:
tags:
- Flow Runs
summary: Bulk Delete Flow Runs
description: 'Bulk delete flow runs using a filter.
This endpoint soft-deletes flow runs matching the provided filter criteria.
For small numbers of flow runs (5 or fewer), cleanup is performed synchronously.
For larger batches, cleanup is queued as a background job.
Required workspace scopes: `manage_flows`'
operationId: bulk_delete_flow_runs_api_accounts__account_id__workspaces__workspace_id__flow_runs_bulk_delete_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/Body_bulk_delete_flow_runs_api_accounts__account_id__workspaces__workspace_id__flow_runs_bulk_delete_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkDeleteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/bulk_set_state:
post:
tags:
- Flow Runs
summary: Bulk Set Flow Run State
description: 'Bulk set state on flow runs matching a filter.
This endpoint attempts to set the specified state on all flow runs
matching the filter criteria. Each flow run is processed through
orchestration rules (unless force=True), so individual transitions
may be accepted, rejected, aborted, or waited.
The response body contains detailed per-run results indicating
the outcome for each flow run.
Required workspace scopes: `run_flows`'
operationId: bulk_set_flow_run_state_api_accounts__account_id__workspaces__workspace_id__flow_runs_bulk_set_state_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_bulk_set_flow_run_state_api_accounts__account_id__workspaces__workspace_id__flow_runs_bulk_set_state_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FlowRunBulkSetStateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}/set_state:
post:
tags:
- Flow Runs
summary: Set Flow Run State
description: 'Set a flow run state, invoking any orchestration rules.
Required workspace scopes: `run_flows`'
operationId: set_flow_run_state_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__set_state_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 flow run id
title: Id
description: The flow run 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_flow_run_state_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__set_state_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationResult'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}/input:
post:
tags:
- Flow Runs
summary: Create Flow Run Input
description: 'Create a key/value input for a flow run.
Required workspace scopes: `run_flows`'
operationId: create_flow_run_input_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__input_post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The flow run id
title: Id
description: The flow run 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_create_flow_run_input_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__input_post'
responses:
'201':
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}/flow_runs/{id}/input/filter:
post:
tags:
- Flow Runs
summary: Filter Flow Run Input
description: 'Filter flow run inputs by key prefix
Required workspace scopes: `see_flows`'
operationId: filter_flow_run_input_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__input_filter_post
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The flow run id
title: Id
description: The flow run id
- 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_filter_flow_run_input_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__input_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlowRunInput'
title: Response Filter Flow Run Input Api Accounts Account Id Workspaces Workspace Id Flow Runs Id Input Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/flow_runs/{id}/input/{key}:
get:
tags:
- Flow Runs
summary: Read Flow Run Input
description: 'Create a value from a flow run input
Required workspace scopes: `see_flows`'
operationId: read_flow_run_input_api_accounts__account_id__workspaces__workspace_id__flow_runs__id__input__key__get
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The flow run id
title: Id
description: The flow run id
- name: key
in: path
required: true
schema:
type: string
description: The input key
title: Key
description: The input key
- name: account_id
# --- truncated at 32 KB (185 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prefect/refs/heads/main/openapi/prefect-flow-runs-api-openapi.yml