OpenAPI Specification
openapi: 3.1.0
info:
title: Prefect Cloud Account Billing Task Runs API
description: Prefect Cloud REST API documentation.
version: 0.8.4
tags:
- name: Task Runs
description: Interact with a Workspace's Task Runs.
externalDocs:
description: Write and run tasks
url: https://docs.prefect.io/v3/develop/write-tasks
paths:
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/filter:
post:
tags:
- Task Runs
summary: Read Task Runs
description: 'Query for task runs.
Required workspace scopes: `see_flows`'
operationId: read_task_runs_api_accounts__account_id__workspaces__workspace_id__task_runs_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_task_runs_api_accounts__account_id__workspaces__workspace_id__task_runs_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TaskRun'
title: Response Read Task Runs Api Accounts Account Id Workspaces Workspace Id Task Runs Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/{id}:
delete:
tags:
- Task Runs
summary: Delete Task Run
description: 'Delete a task run by id.
Required workspace scopes: `manage_flows`'
operationId: delete_task_run_api_accounts__account_id__workspaces__workspace_id__task_runs__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 task run id
title: Id
description: The task 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
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Task Runs
summary: Update Task Run
description: 'Updates a task run.
Required workspace scopes: `run_flows`'
operationId: update_task_run_api_accounts__account_id__workspaces__workspace_id__task_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 task run id
title: Id
description: The task 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/TaskRunUpdate'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Task Runs
summary: Read Task Run
description: 'Get a task run by id.
Required workspace scopes: `see_flows`'
operationId: read_task_run_api_accounts__account_id__workspaces__workspace_id__task_runs__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 task run id
title: Id
description: The task 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskRun'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/:
post:
tags:
- Task Runs
summary: Create Task Run
description: 'Create a task run. If a task run with the same flow_run_id,
task_key, and dynamic_key already exists, the existing task
run will be returned.
If no state is provided, the task run will be created in a PENDING state.
Required workspace scopes: `run_flows`'
operationId: create_task_run_api_accounts__account_id__workspaces__workspace_id__task_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/TaskRunCreate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskRun'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/count:
post:
tags:
- Task Runs
summary: Count Task Runs
description: 'Count task runs.
Required workspace scopes: `see_flows`'
operationId: count_task_runs_api_accounts__account_id__workspaces__workspace_id__task_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_task_runs_api_accounts__account_id__workspaces__workspace_id__task_runs_count_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: integer
title: Response Count Task Runs Api Accounts Account Id Workspaces Workspace Id Task Runs Count Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/history:
post:
tags:
- Task Runs
summary: Task Run History
description: 'Query for task run history data across a given range and interval.
Required workspace scopes: `see_flows`'
operationId: task_run_history_api_accounts__account_id__workspaces__workspace_id__task_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_task_run_history_api_accounts__account_id__workspaces__workspace_id__task_runs_history_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HistoryResponse'
title: Response Task Run History Api Accounts Account Id Workspaces Workspace Id Task Runs History Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/{id}/artifacts:
get:
tags:
- Task Runs
summary: Get Task Run Artifacts
description: 'Get all artifacts created within a task run, including artifacts from
subflow runs spawned by this task (recursively).
Required workspace scopes: `see_flows`'
operationId: get_task_run_artifacts_api_accounts__account_id__workspaces__workspace_id__task_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 task run id
title: Id
description: The task 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 = task run only)
title: Depth
description: Optional depth limit for recursion (0 = task 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 Task Run Artifacts Api Accounts Account Id Workspaces Workspace Id Task Runs Id Artifacts Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/{id}/assets/materializations:
get:
tags:
- Task Runs
summary: Get Task Run Materializations
description: 'Get all asset materializations from a task run, including materializations
from descendant runs.
Returns a historical snapshot of materializations as they occurred, with asset
properties captured at materialization time (not current state).
Required workspace scopes: `see_assets`'
operationId: get_task_run_materializations_api_accounts__account_id__workspaces__workspace_id__task_runs__id__assets_materializations_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 task run id
title: Id
description: The task 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 based on execution hierarchy. depth=0: only the task run. depth=1: task run + its descendants. None: unlimited depth (default).'
title: Depth
description: 'Optional depth limit based on execution hierarchy. depth=0: only the task run. depth=1: task run + its descendants. None: unlimited depth (default).'
- name: since
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only return materializations on or after this timestamp
title: Since
description: Only return materializations on or after this timestamp
- name: until
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only return materializations on or before this timestamp
title: Until
description: Only return materializations on or before this timestamp
- name: sort
in: query
required: false
schema:
enum:
- asc
- desc
type: string
description: Sort order by occurred time (asc or desc)
default: desc
title: Sort
description: Sort order by occurred 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/MaterializationEvent'
title: Response Get Task Run Materializations Api Accounts Account Id Workspaces Workspace Id Task Runs Id Assets Materializations Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/{id}/assets/references:
get:
tags:
- Task Runs
summary: Get Task Run References
description: 'Get all asset references from a task run, including references from
descendant runs.
Returns a historical snapshot of asset references as they occurred, with asset
properties captured at reference time (not current state).
Required workspace scopes: `see_assets`'
operationId: get_task_run_references_api_accounts__account_id__workspaces__workspace_id__task_runs__id__assets_references_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 task run id
title: Id
description: The task 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 based on execution hierarchy. depth=0: only the task run. depth=1: task run + its descendants. None: unlimited depth (default).'
title: Depth
description: 'Optional depth limit based on execution hierarchy. depth=0: only the task run. depth=1: task run + its descendants. None: unlimited depth (default).'
- name: since
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only return references on or after this timestamp
title: Since
description: Only return references on or after this timestamp
- name: until
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Only return references on or before this timestamp
title: Until
description: Only return references on or before this timestamp
- name: sort
in: query
required: false
schema:
enum:
- asc
- desc
type: string
description: Sort order by occurred time (asc or desc)
default: desc
title: Sort
description: Sort order by occurred 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/ReferenceEvent'
title: Response Get Task Run References Api Accounts Account Id Workspaces Workspace Id Task Runs Id Assets References Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/task_runs/{id}/set_state:
post:
tags:
- Task Runs
summary: Set Task Run State
description: 'Set a task run state, invoking any orchestration rules.
Required workspace scopes: `run_flows`'
operationId: set_task_run_state_api_accounts__account_id__workspaces__workspace_id__task_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 task run id
title: Id
description: The task 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_task_run_state_api_accounts__account_id__workspaces__workspace_id__task_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}/task_runs/paginate:
post:
tags:
- Task Runs
summary: Paginate Task Runs
description: 'Pagination query for task runs.
Required workspace scopes: `see_flows`'
operationId: paginate_task_runs_api_accounts__account_id__workspaces__workspace_id__task_runs_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_task_runs_api_accounts__account_id__workspaces__workspace_id__task_runs_paginate_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskRunPaginationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/ui/task_runs/dashboard/counts:
post:
tags:
- Task Runs
summary: Read Dashboard Task Run Counts
description: '
Required workspace scopes: `see_flows`'
operationId: read_dashboard_task_run_counts_api_accounts__account_id__workspaces__workspace_id__ui_task_runs_dashboard_counts_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_read_dashboard_task_run_counts_api_accounts__account_id__workspaces__workspace_id__ui_task_runs_dashboard_counts_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DashboardTaskRunCount'
title: Response Read Dashboard Task Run Counts Api Accounts Account Id Workspaces Workspace Id Ui Task Runs Dashboard Counts Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/ui/task_runs/count:
post:
tags:
- Task Runs
summary: Read Task Run Counts By State
description: '
Required workspace scopes: `see_flows`'
operationId: read_task_run_counts_by_state_api_accounts__account_id__workspaces__workspace_id__ui_task_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_read_task_run_counts_by_state_api_accounts__account_id__workspaces__workspace_id__ui_task_runs_count_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CountByState'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
FlowRunFilterNextScheduledStartTime:
properties:
before_:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Before
description: Only include flow runs with a next_scheduled_start_time or before this time
after_:
anyOf:
- type: string
format: date-time
- type: 'null'
title: After
description: Only include flow runs with a next_scheduled_start_time at or after this time
additionalProperties: false
type: object
title: FlowRunFilterNextScheduledStartTime
description: Filter by `FlowRun.next_scheduled_start_time`.
WorkPoolFilterType:
properties:
any_:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Any
description: A list of work pool types to include
additionalProperties: false
type: object
title: WorkPoolFilterType
description: Filter by `WorkPool.type`.
DeploymentFilterCreatedBy:
properties:
operator:
$ref: '#/components/schemas/prefect_cloud__orion__schemas__filters__Operator'
description: Operator for combining filter criteria. Defaults to 'and_'.
default: and_
id_:
anyOf:
- items:
type: string
format: uuid
type: array
- type: 'null'
title: Id
description: A list of creator IDs to include
type_:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Type
description: A list of creator types to include
is_null_:
anyOf:
- type: boolean
- type: 'null'
title: Is Null
description: If true, only include deployments without a creator
additionalProperties: false
type: object
title: DeploymentFilterCreatedBy
description: Filter by `Deployment.created_by`.
FlowRunFilterParentTaskRunId:
properties:
operator:
$ref: '#/components/schemas/prefect_cloud__orion__schemas__filters__Operator'
description: Operator for combining filter criteria. Defaults to 'and_'.
default: and_
any_:
anyOf:
- items:
type: string
format: uuid
type: array
- type: 'null'
title: Any
description: A list of flow run parent_task_run_ids to include
is_null_:
anyOf:
- type: boolean
- type: 'null'
title: Is Null
description: If true, only include flow runs without parent_task_run_id
additionalProperties: false
type: object
title: FlowRunFilterParentTaskRunId
description: Filter by `FlowRun.parent_task_run_id`.
TaskRun:
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
title: Name
examples:
- my-task-run
flow_run_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Flow Run Id
description: The flow run id of the task run.
task_key:
type: string
title: Task Key
description: A unique identifier for the task being run.
dynamic_key:
type: string
title: Dynamic Key
description: A dynamic key used to differentiate between multiple runs of the same task within the same flow run.
cache_key:
anyOf:
- type: string
- type: 'null'
title: Cache Key
description: An optional cache key. If a COMPLETED state associated with this cache key is found, the cached COMPLETED state will be used instead of executing the task run.
cache_expiration:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Cache Expiration
description: Specifies when the cached state should expire.
task_version:
anyOf:
- type: string
- type: 'null'
title: Task Version
description: The version of the task being run.
empirical_policy:
$ref: '#/components/schemas/TaskRunPolicy'
tags:
items:
type: string
type: array
title: Tags
description: A list of tags for the task run.
examples:
- - tag-1
- tag-2
labels:
anyOf:
- additionalProperties:
anyOf:
- type: boolean
- type: integer
- type: number
- type: string
type: object
- t
# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prefect/refs/heads/main/openapi/prefect-task-runs-api-openapi.yml