prefect.client.orchestration

Functions

get_client ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_client(httpx_settings: Optional[dict[str, Any]] = None, sync_client: bool = False) -> Union['SyncPrefectClient', 'PrefectClient']

Retrieve a HTTP client for communicating with the Prefect REST API.

The client must be context managed; for example:

async with get_client() as client:
    await client.hello()

To return a synchronous client, pass sync_client=True:

with get_client(sync_client=True) as client:
    client.hello()

Classes

PrefectClient ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

An asynchronous client for interacting with the Prefect REST API.

Args:

• api: the REST API URL or FastAPI application to connect to
• api_key: An optional API key for authentication.
• api_version: The API version this client is compatible with.
• httpx_settings: An optional dictionary of settings to pass to the underlying httpx.AsyncClient

Examples:

Say hello to a Prefect REST API

```python
async with get_client() as client:
    response = await client.hello()

print(response.json())
👋
```

Methods:

api_healthcheck ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L491" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

api_healthcheck(self) -> Optional[Exception]

Attempts to connect to the API and returns the encountered exception if not successful.

If successful, returns None.

api_url ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L483" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

api_url(self) -> httpx.URL

Get the base URL for the API.

api_version ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1078" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

api_version(self) -> str

apply_slas_for_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_experimental/sla/client.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

apply_slas_for_deployment(self, deployment_id: 'UUID', slas: 'list[SlaTypes]') -> 'UUID'

Applies service level agreements for a deployment. Performs matching by SLA name. If a SLA with the same name already exists, it will be updated. If a SLA with the same name does not exist, it will be created. Existing SLAs that are not in the list will be deleted. Args: deployment_id: The ID of the deployment to update SLAs for slas: List of SLAs to associate with the deployment Raises: httpx.RequestError: if the SLAs were not updated for any reason Returns: SlaMergeResponse: The response from the backend, containing the names of the created, updated, and deleted SLAs

client_version ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1082" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

client_version(self) -> str

count_flow_runs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L821" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

count_flow_runs(self) -> int

Returns the count of flow runs matching all criteria for flow runs.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues

Returns:

• count of flow runs

create_artifact ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_artifact(self, artifact: 'ArtifactCreate') -> 'Artifact'

create_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_automation(self, automation: 'AutomationCore') -> 'UUID'

Creates an automation in Prefect Cloud.

create_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_block_document(self, block_document: 'BlockDocument | BlockDocumentCreate', include_secrets: bool = True) -> 'BlockDocument'

Create a block document in the Prefect API. This data is used to configure a corresponding Block.

Args:

• include_secrets: whether to include secret values on the stored Block, corresponding to Pydantic's SecretStr and SecretBytes fields. Note Blocks may not work as expected if this is set to False.

create_block_schema ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_block_schema(self, block_schema: 'BlockSchemaCreate') -> 'BlockSchema'

Create a block schema in the Prefect API.

create_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_block_type(self, block_type: 'BlockTypeCreate') -> 'BlockType'

Create a block type in the Prefect API.

create_concurrency_limit ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L485" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_concurrency_limit(self, tag: str, concurrency_limit: int) -> 'UUID'

Create a tag concurrency limit in the Prefect API. These limits govern concurrently running tasks.

Args:

• tag: a tag the concurrency limit is applied to
• concurrency_limit: the maximum number of concurrent task runs for a given tag

Raises:

• httpx.RequestError: if the concurrency limit was not created for any reason

Returns:

• the ID of the concurrency limit in the backend

create_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L756" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_deployment(self, flow_id: UUID, name: str, version: str | None = None, version_info: 'VersionInfo | None' = None, schedules: list['DeploymentScheduleCreate'] | None = None, concurrency_limit: int | None = None, concurrency_options: 'ConcurrencyOptions | None' = None, parameters: dict[str, Any] | None = None, description: str | None = None, work_queue_name: str | None = None, work_pool_name: str | None = None, tags: list[str] | None = None, storage_document_id: UUID | None = None, path: str | None = None, entrypoint: str | None = None, infrastructure_document_id: UUID | None = None, parameter_openapi_schema: dict[str, Any] | None = None, paused: bool | None = None, pull_steps: list[dict[str, Any]] | None = None, enforce_parameter_schema: bool | None = None, job_variables: dict[str, Any] | None = None, branch: str | None = None, base: UUID | None = None, root: UUID | None = None) -> UUID

Create a deployment.

Args:

• flow_id: the flow ID to create a deployment for
• name: the name of the deployment
• version: an optional version string for the deployment
• tags: an optional list of tags to apply to the deployment
• storage_document_id: an reference to the storage block document used for the deployed flow
• infrastructure_document_id: an reference to the infrastructure block document to use for this deployment
• job_variables: A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example env.CONFIG_KEY=config_value or namespace='prefect'. This argument was previously named infra_overrides. Both arguments are supported for backwards compatibility.

Raises:

• RequestError: if the deployment was not created for any reason

Returns:

• the ID of the deployment in the backend

create_deployment_branch ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1446" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_deployment_branch(self, deployment_id: UUID, branch: str, options: 'DeploymentBranchingOptions | None' = None, overrides: 'DeploymentUpdate | None' = None) -> UUID

create_deployment_schedules ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_deployment_schedules(self, deployment_id: UUID, schedules: list[tuple['SCHEDULE_TYPES', bool]] | list['DeploymentScheduleCreate'], max_scheduled_runs: int | None = None, parameters: dict[str, Any] | None = None, slug: str | None = None) -> list['DeploymentSchedule']

Create deployment schedules.

Args:

• deployment_id: the deployment ID
• schedules: a list of tuples containing the schedule to create and whether or not it should be active, or a list of DeploymentScheduleCreate objects.
• max_scheduled_runs: The maximum number of scheduled runs for the schedule. Only used when schedules is a list of tuples.
• parameters: Parameter overrides for the schedule. Only used when schedules is a list of tuples.
• slug: A unique identifier for the schedule. Only used when schedules is a list of tuples.

Raises:

• RequestError: if the schedules were not created for any reason

Returns:

• the list of schedules created in the backend

create_flow ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow(self, flow: 'FlowObject[Any, Any]') -> 'UUID'

Create a flow in the Prefect API.

Args:

• flow: a Flow object

Raises:

• httpx.RequestError: if a flow was not created for any reason

Returns:

• the ID of the flow in the backend

create_flow_from_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_from_name(self, flow_name: str) -> 'UUID'

Create a flow in the Prefect API.

Args:

• flow_name: the name of the new flow

Raises:

• httpx.RequestError: if a flow was not created for any reason

Returns:

• the ID of the flow in the backend

create_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_run(self, flow: 'FlowObject[Any, R]', name: str | None = None, parameters: dict[str, Any] | None = None, context: dict[str, Any] | None = None, tags: 'Iterable[str] | None' = None, parent_task_run_id: 'UUID | None' = None, state: 'State[R] | None' = None, work_pool_name: str | None = None, work_queue_name: str | None = None, job_variables: dict[str, Any] | None = None) -> 'FlowRun'

Create a flow run for a flow.

Args:

• flow: The flow model to create the flow run for
• name: An optional name for the flow run
• parameters: Parameter overrides for this flow run.
• context: Optional run context data
• tags: a list of tags to apply to this flow run
• parent_task_run_id: if a subflow run is being created, the placeholder task run identifier in the parent flow
• state: The initial state for the run. If not provided, defaults to Pending.
• work_pool_name: The name of the work pool to run the flow run in.
• work_queue_name: The name of the work queue to place the flow run in.
• job_variables: The job variables to use when setting up flow run infrastructure.

Raises:

• httpx.RequestError: if the Prefect API does not successfully create a run for any reason

Returns:

• The flow run model

create_flow_run_from_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_run_from_deployment(self, deployment_id: UUID) -> 'FlowRun'

Create a flow run for a deployment.

Args:

• deployment_id: The deployment ID to create the flow run from
• parameters: Parameter overrides for this flow run. Merged with the deployment defaults
• context: Optional run context data
• state: The initial state for the run. If not provided, defaults to Scheduled for now. Should always be a Scheduled type.
• name: An optional name for the flow run. If not provided, the server will generate a name.
• tags: An optional iterable of tags to apply to the flow run; these tags are merged with the deployment's tags.
• idempotency_key: Optional idempotency key for creation of the flow run. If the key matches the key of an existing flow run, the existing run will be returned instead of creating a new one.
• parent_task_run_id: if a subflow run is being created, the placeholder task run identifier in the parent flow
• work_queue_name: An optional work queue name to add this run to. If not provided, will default to the deployment's set work queue. If one is provided that does not exist, a new work queue will be created within the deployment's work pool.
• job_variables: Optional variables that will be supplied to the flow run job.

Raises:

• RequestError: if the Prefect API does not successfully create a run for any reason

Returns:

• The flow run model

create_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L948" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_run_input(self, flow_run_id: 'UUID', key: str, value: str, sender: str | None = None) -> None

Creates a flow run input.

Args:

• flow_run_id: The flow run id.
• key: The input key.
• value: The input value.
• sender: The sender of the input.

create_global_concurrency_limit ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L823" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_global_concurrency_limit(self, concurrency_limit: 'GlobalConcurrencyLimitCreate') -> 'UUID'

create_logs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_logs/client.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_logs(self, logs: Iterable[Union['LogCreate', dict[str, Any]]]) -> None

Create logs for a flow or task run

Args:

• logs: An iterable of LogCreate objects or already json-compatible dicts

create_task_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L822" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_task_run(self, task: 'TaskObject[P, R]', flow_run_id: Optional[UUID], dynamic_key: str, id: Optional[UUID] = None, name: Optional[str] = None, extra_tags: Optional[Iterable[str]] = None, state: Optional[prefect.states.State[R]] = None, task_inputs: Optional[dict[str, list[Union[TaskRunResult, FlowRunResult, Parameter, Constant]]]] = None) -> TaskRun

Create a task run

Args:

• task: The Task to run
• flow_run_id: The flow run id with which to associate the task run
• dynamic_key: A key unique to this particular run of a Task within the flow
• id: An optional ID for the task run. If not provided, one will be generated server-side.
• name: An optional name for the task run
• extra_tags: an optional list of extra tags to apply to the task run in addition to task.tags
• state: The initial state for the run. If not provided, defaults to Pending for now. Should always be a Scheduled type.
• task_inputs: the set of inputs passed to the task

Returns:

• The created task run.

create_variable ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_variable(self, variable: 'VariableCreate') -> 'Variable'

Creates a variable with the provided configuration.

create_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L504" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_work_pool(self, work_pool: 'WorkPoolCreate', overwrite: bool = False) -> 'WorkPool'

Creates a work pool with the provided configuration.

Args:

• work_pool: Desired configuration for the new work pool.

Returns:

• Information about the newly created work pool.

create_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L510" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_work_queue(self, name: str, description: Optional[str] = None, is_paused: Optional[bool] = None, concurrency_limit: Optional[int] = None, priority: Optional[int] = None, work_pool_name: Optional[str] = None) -> WorkQueue

Create a work queue.

Args:

• name: a unique name for the work queue
• description: An optional description for the work queue.
• is_paused: Whether or not the work queue is paused.
• concurrency_limit: An optional concurrency limit for the work queue.
• priority: The queue's priority. Lower values are higher priority (1 is the highest).
• work_pool_name: The name of the work pool to use for this queue.

Raises:

• prefect.exceptions.ObjectAlreadyExists: If request returns 409
• httpx.RequestError: If request fails

Returns:

• The created work queue

decrement_v1_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L673" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

decrement_v1_concurrency_slots(self, names: list[str], task_run_id: 'UUID', occupancy_seconds: float) -> 'Response'

Decrement concurrency limit slots for the specified limits.

Args:

• names: A list of limit names to decrement.
• task_run_id: The task run ID that incremented the limits.
• occupancy_seconds: The duration in seconds that the limits were held.

Returns:

• "Response": The HTTP response from the server.

delete_artifact ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_artifact(self, artifact_id: 'UUID') -> None

delete_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L304" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_automation(self, automation_id: 'UUID') -> None

delete_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_block_document(self, block_document_id: 'UUID') -> None

Delete a block document.

delete_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_block_type(self, block_type_id: 'UUID') -> None

Delete a block type.

delete_concurrency_limit_by_tag ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L623" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_concurrency_limit_by_tag(self, tag: str) -> None

Delete the concurrency limit set on a specific tag.

Args:

• tag: a tag the concurrency limit is applied to

Raises:

• ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

delete_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_deployment(self, deployment_id: UUID) -> None

Delete deployment by id.

Args:

• deployment_id: The deployment id of interest.

Raises: ObjectNotFound: If request returns 404 RequestError: If requests fails

delete_deployment_schedule ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_deployment_schedule(self, deployment_id: UUID, schedule_id: UUID) -> None

Delete a deployment schedule.

Args:

• deployment_id: the deployment ID
• schedule_id: the ID of the deployment schedule to delete.

Raises:

• RequestError: if the schedules were not deleted for any reason

delete_flow ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_flow(self, flow_id: 'UUID') -> None

Delete a flow by UUID.

Args:

• flow_id: ID of the flow to be deleted

Raises: prefect.exceptions.ObjectNotFound: If request returns 404 httpx.RequestError: If requests fail

delete_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L684" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_flow_run(self, flow_run_id: 'UUID') -> None

Delete a flow run by UUID.

Args:

• flow_run_id: The flow run UUID of interest.

Raises: ObjectNotFound: If request returns 404 httpx.RequestError: If requests fails

delete_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L1008" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_flow_run_input(self, flow_run_id: 'UUID', key: str) -> None

Deletes a flow run input.

Args:

• flow_run_id: The flow run id.
• key: The input key.

delete_global_concurrency_limit_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L859" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_global_concurrency_limit_by_name(self, name: str) -> 'Response'

delete_resource_owned_automations ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_resource_owned_automations(self, resource_id: str) -> None

delete_task_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L960" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_task_run(self, task_run_id: UUID) -> None

Delete a task run by id.

Args:

• task_run_id: the task run ID of interest

Raises: prefect.exceptions.ObjectNotFound: If request returns 404 httpx.RequestError: If requests fails

delete_variable_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_variable_by_name(self, name: str) -> None

Deletes a variable by name.

delete_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L581" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_work_pool(self, work_pool_name: str) -> None

Deletes a work pool.

Args:

• work_pool_name: Name of the work pool to delete.

delete_work_queue_by_id ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L791" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_work_queue_by_id(self, id: UUID) -> None

Delete a work queue by its ID.

Args:

• id: the id of the work queue to delete

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If requests fails

filter_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L974" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

filter_flow_run_input(self, flow_run_id: 'UUID', key_prefix: str, limit: int, exclude_keys: 'set[str]') -> 'list[FlowRunInput]'

find_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

find_automation(self, id_or_name: 'str | UUID') -> 'Automation | None'

get_most_recent_block_schema_for_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_most_recent_block_schema_for_block_type(self, block_type_id: 'UUID') -> 'BlockSchema | None'

Fetches the most recent block schema for a specified block type ID.

Args:

• block_type_id: The ID of the block type.

Raises:

• httpx.RequestError: If the request fails for any reason.

Returns:

• The most recent block schema or None.

get_runs_in_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L625" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_runs_in_work_queue(self, id: UUID, limit: int = 10, scheduled_before: Optional[datetime.datetime] = None) -> list[FlowRun]

Read flow runs off a work queue.

Args:

• id: the id of the work queue to read from
• limit: a limit on the number of runs to return
• scheduled_before: a timestamp; only runs scheduled before this time will be returned. Defaults to now.

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• List[FlowRun]: a list of FlowRun objects read from the queue

get_scheduled_flow_runs_for_deployments ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_scheduled_flow_runs_for_deployments(self, deployment_ids: list[UUID], scheduled_before: 'datetime.datetime | None' = None, limit: int | None = None) -> list['FlowRun']

get_scheduled_flow_runs_for_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L603" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_scheduled_flow_runs_for_work_pool(self, work_pool_name: str, work_queue_names: list[str] | None = None, scheduled_before: datetime | None = None) -> list['WorkerFlowRunResponse']

Retrieves scheduled flow runs for the provided set of work pool queues.

Args:

• work_pool_name: The name of the work pool that the work pool queues are associated with.
• work_queue_names: The names of the work pool queues from which to get scheduled flow runs.
• scheduled_before: Datetime used to filter returned flow runs. Flow runs scheduled for after the given datetime string will not be returned.

Returns:

• A list of worker flow run responses containing information about the
• retrieved flow runs.

hello ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L504" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

hello(self) -> httpx.Response

Send a GET request to /hello for testing purposes.

increment_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L703" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment_concurrency_slots(self, names: list[str], slots: int, mode: Literal['concurrency', 'rate_limit']) -> 'Response'

Increment concurrency slots for the specified limits.

Args:

• names: A list of limit names for which to occupy slots.
• slots: The number of concurrency slots to occupy.
• mode: The mode of the concurrency limits.

increment_concurrency_slots_with_lease ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L727" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment_concurrency_slots_with_lease(self, names: list[str], slots: int, mode: Literal['concurrency', 'rate_limit'], lease_duration: float, holder: 'ConcurrencyLeaseHolder | None' = None) -> 'Response'

Increment concurrency slots for the specified limits with a lease.

Args:

• names: A list of limit names for which to occupy slots.
• slots: The number of concurrency slots to occupy.
• mode: The mode of the concurrency limits.
• lease_duration: The duration of the lease in seconds.
• holder: Optional holder information for tracking who holds the slots.

increment_v1_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L650" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment_v1_concurrency_slots(self, names: list[str], task_run_id: 'UUID') -> 'Response'

Increment concurrency limit slots for the specified limits.

Args:

• names: A list of limit names for which to increment limits.
• task_run_id: The task run ID incrementing the limits.

loop ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1086" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

loop(self) -> asyncio.AbstractEventLoop | None

match_work_queues ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L755" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

match_work_queues(self, prefixes: list[str], work_pool_name: Optional[str] = None) -> list[WorkQueue]

Query the Prefect API for work queues with names with a specific prefix.

Args:

• prefixes: a list of strings used to match work queue name prefixes
• work_pool_name: an optional work pool name to scope the query to

Returns:

• a list of WorkQueue model representations of the work queues

pause_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

pause_automation(self, automation_id: 'UUID') -> None

pause_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L920" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

pause_deployment(self, deployment_id: Union[UUID, str]) -> None

Pause a deployment by ID.

Args:

• deployment_id: The deployment ID of interest (can be a UUID or a string).

Raises:

• ObjectNotFound: If request returns 404
• RequestError: If request fails

raise_for_api_version_mismatch ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

raise_for_api_version_mismatch(self) -> None

raise_for_api_version_mismatch_once ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1089" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

raise_for_api_version_mismatch_once(self) -> None

Run API version compatibility check once per process/API/client version.

read_artifacts ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_artifacts(self, **kwargs: Unpack['ArtifactReadParams']) -> list['Artifact']

read_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_automation(self, automation_id: 'UUID | str') -> 'Automation | None'

read_automations ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_automations(self) -> list['Automation']

read_automations_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L252" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_automations_by_name(self, name: str) -> list['Automation']

Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.

Args:

• name: the name of the automation to query

Returns:

• a list of Automation model representations of the automations

read_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_document(self, block_document_id: 'UUID', include_secrets: bool = True) -> 'BlockDocument'

Read the block document with the specified ID.

Args:

• block_document_id: the block document id
• include_secrets: whether to include secret values on the Block, corresponding to Pydantic's SecretStr and SecretBytes fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is False.

Raises:

• httpx.RequestError: if the block document was not found for any reason

Returns:

• A block document or None.

read_block_document_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_document_by_name(self, name: str, block_type_slug: str, include_secrets: bool = True) -> 'BlockDocument'

Read the block document with the specified name that corresponds to a specific block type name.

Args:

• name: The block document name.
• block_type_slug: The block type slug.
• include_secrets: whether to include secret values on the Block, corresponding to Pydantic's SecretStr and SecretBytes fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is False.

Raises:

• httpx.RequestError: if the block document was not found for any reason

Returns:

• A block document or None.

read_block_documents ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_documents(self, block_schema_type: str | None = None, offset: int | None = None, limit: int | None = None, include_secrets: bool = True) -> 'list[BlockDocument]'

Read block documents

Args:

• block_schema_type: an optional block schema type
• offset: an offset
• limit: the number of blocks to return
• include_secrets: whether to include secret values on the Block, corresponding to Pydantic's SecretStr and SecretBytes fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is False.

Returns:

• A list of block documents

read_block_documents_by_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_documents_by_type(self, block_type_slug: str, offset: int | None = None, limit: int | None = None, include_secrets: bool = True) -> 'list[BlockDocument]'

Retrieve block documents by block type slug.

Args:

• block_type_slug: The block type slug.
• offset: an offset
• limit: the number of blocks to return
• include_secrets: whether to include secret values

Returns:

• A list of block documents

read_block_schema_by_checksum ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_schema_by_checksum(self, checksum: str, version: str | None = None) -> 'BlockSchema'

Look up a block schema checksum

read_block_schemas ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_schemas(self) -> 'list[BlockSchema]'

Read all block schemas Raises: httpx.RequestError: if a valid block schema was not found

Returns:

• A BlockSchema.

read_block_type_by_slug ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_type_by_slug(self, slug: str) -> 'BlockType'

Read a block type by its slug.

read_block_types ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L326" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_types(self) -> 'list[BlockType]'

Read all block types Raises: httpx.RequestError: if the block types were not found

Returns:

• List of BlockTypes.

read_concurrency_limit_by_tag ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_concurrency_limit_by_tag(self, tag: str) -> 'ConcurrencyLimit'

Read the concurrency limit set on a specific tag.

Args:

• tag: a tag the concurrency limit is applied to

Raises:

• ObjectNotFound: If request returns 404
• httpx.RequestError: if the concurrency limit was not created for any reason

Returns:

• the concurrency limit set on a specific tag

read_concurrency_limits ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L561" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_concurrency_limits(self, limit: int, offset: int) -> list['ConcurrencyLimit']

Lists concurrency limits set on task run tags.

Args:

• limit: the maximum number of concurrency limits returned
• offset: the concurrency limit query offset

Returns:

• a list of concurrency limits

read_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1015" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployment(self, deployment_id: Union[UUID, str]) -> 'DeploymentResponse'

Query the Prefect API for a deployment by id.

Args:

• deployment_id: the deployment ID of interest

Returns:

• a Deployment model representation of the deployment

read_deployment_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1050" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployment_by_name(self, name: str) -> 'DeploymentResponse'

Query the Prefect API for a deployment by name.

Args:

• name: A deployed flow's name: <FLOW_NAME>/<DEPLOYMENT_NAME>

Raises:

• ObjectNotFound: If request returns 404
• RequestError: If request fails

Returns:

• a Deployment model representation of the deployment

read_deployment_schedules ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployment_schedules(self, deployment_id: UUID) -> list['DeploymentSchedule']

Query the Prefect API for a deployment's schedules.

Args:

• deployment_id: the deployment ID

Returns:

• a list of DeploymentSchedule model representations of the deployment schedules

read_deployments ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1091" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployments(self) -> list['DeploymentResponse']

Query the Prefect API for deployments. Only deployments matching all the provided criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues
• limit: maximum number of deployments to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the deployment query.

Returns:

• a list of Deployment model representations of the deployments

read_events ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_events/client.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_events(self, filter: 'EventFilter | None' = None, limit: int = 100) -> EventPage

query historical events from the API.

Args:

• filter: optional filter criteria to narrow down events
• limit: maximum number of events to return per page (default 100)

Returns:

• EventPage containing events, total count, and next page link

read_events_page ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_events/client.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_events_page(self, next_page_url: str) -> EventPage

retrieve the next page of events using a next_page URL.

Args:

• next_page_url: the next_page URL from a previous EventPage response

Returns:

• EventPage containing the next page of events

read_flow ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow(self, flow_id: 'UUID') -> 'Flow'

Query the Prefect API for a flow by id.

Args:

• flow_id: the flow ID of interest

Returns:

• a Flow model representation of the flow

read_flow_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_by_name(self, flow_name: str) -> 'Flow'

Query the Prefect API for a flow by name.

Args:

• flow_name: the name of a flow

Returns:

• a fully hydrated Flow model

read_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L707" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_run(self, flow_run_id: 'UUID') -> 'FlowRun'

Query the Prefect API for a flow run by id.

Args:

• flow_run_id: the flow run ID of interest

Returns:

• a Flow Run model representation of the flow run

read_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L992" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_run_input(self, flow_run_id: 'UUID', key: str) -> str

Reads a flow run input.

Args:

• flow_run_id: The flow run id.
• key: The input key.

read_flow_run_states ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L919" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_run_states(self, flow_run_id: 'UUID') -> 'list[State]'

Query for the states of a flow run

Args:

• flow_run_id: the id of the flow run

Returns:

• a list of State model representations of the flow run states

read_flow_runs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L759" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_runs(self) -> 'list[FlowRun]'

Query the Prefect API for flow runs. Only flow runs matching all criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues
• sort: sort criteria for the flow runs
• limit: maximum number of flow runs to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the flow run query.

Returns:

• a list of Flow Run model representations of the flow runs

read_flows ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L266" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flows(self) -> list['Flow']

Query the Prefect API for flows. Only flows matching all criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues
• sort: sort criteria for the flows
• limit: maximum number of flows to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the flow query.

Returns:

• a list of Flow model representations of the flows

read_global_concurrency_limit_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L873" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_global_concurrency_limit_by_name(self, name: str) -> 'GlobalConcurrencyLimitResponse'

read_global_concurrency_limits ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L929" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_global_concurrency_limits(self, limit: int = 10, offset: int = 0) -> list['GlobalConcurrencyLimitResponse']

read_latest_artifacts ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_latest_artifacts(self, **kwargs: Unpack['ArtifactCollectionReadParams']) -> list['ArtifactCollection']

read_logs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_logs/client.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_logs(self, log_filter: 'LogFilter | None' = None, limit: int | None = None, offset: int | None = None, sort: 'LogSort | None' = None) -> list[Log]

Read flow and task run logs.

read_resource_related_automations ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_resource_related_automations(self, resource_id: str) -> list['Automation']

read_task_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L892" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_task_run(self, task_run_id: UUID) -> TaskRun

Query the Prefect API for a task run by id.

Args:

• task_run_id: the task run ID of interest

Returns:

• a Task Run model representation of the task run

read_task_run_states ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1007" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_task_run_states(self, task_run_id: UUID) -> list[prefect.states.State]

Query for the states of a task run

Args:

• task_run_id: the id of the task run

Returns:

• a list of State model representations of the task run states

read_task_runs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L911" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_task_runs(self) -> list[TaskRun]

Query the Prefect API for task runs. Only task runs matching all criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• sort: sort criteria for the task runs
• limit: maximum number of task runs to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the task run query.

Returns:

• a list of Task Run model representations of the task runs

read_variable_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_variable_by_name(self, name: str) -> 'Variable | None'

Reads a variable by name. Returns None if no variable is found.

read_variables ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_variables(self, limit: int | None = None) -> list['Variable']

Reads all variables.

read_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_pool(self, work_pool_name: str) -> 'WorkPool'

Reads information for a given work pool

Args:

• work_pool_name: The name of the work pool to for which to get information.

Returns:

• Information about the requested work pool.

read_work_pool_concurrency_status ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L647" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_pool_concurrency_status(self, work_pool_name: str, page: int = 1, limit: int | None = None, flow_run_limit: int = 10) -> 'WorkPoolConcurrencyStatus'

Reads concurrency status for a work pool.

Args:

• work_pool_name: The name of the work pool.
• page: Page number (1-indexed).
• limit: Max queues per page (server default if None).
• flow_run_limit: Max flow runs per queue (0-200).

Returns:

• Paginated concurrency status with per-queue breakdown.

read_work_pools ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L475" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_pools(self, limit: int | None = None, offset: int = 0, work_pool_filter: 'WorkPoolFilter | None' = None) -> list['WorkPool']

Reads work pools.

Args:

• limit: Limit for the work pool query.
• offset: Offset for the work pool query.
• work_pool_filter: Criteria by which to filter work pools.

Returns:

• A list of work pools.

read_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L665" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue(self, id: UUID) -> WorkQueue

Read a work queue.

Args:

• id: the id of the work queue to load

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• an instantiated WorkQueue object

read_work_queue_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L564" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue_by_name(self, name: str, work_pool_name: Optional[str] = None) -> WorkQueue

Read a work queue by name.

Args:

• name: a unique name for the work queue
• work_pool_name: the name of the work pool the queue belongs to.

Raises:

• prefect.exceptions.ObjectNotFound: if no work queue is found
• httpx.HTTPStatusError: other status errors

Returns:

• a work queue API object

read_work_queue_concurrency_status ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L717" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue_concurrency_status(self, id: UUID, page: int = 1, limit: Optional[int] = None) -> 'WorkQueueConcurrencyStatus'

Read concurrency status for a work queue.

Args:

• id: the id of the work queue
• page: Page number (1-indexed).
• limit: Max flow runs per page (server default if None).

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• Paginated WorkQueueConcurrencyStatus with flow run summaries

read_work_queue_status ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L691" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue_status(self, id: UUID) -> WorkQueueStatusDetail

Read a work queue status.

Args:

• id: the id of the work queue to load

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• an instantiated WorkQueueStatus object

read_work_queues ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1026" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queues(self, work_pool_name: Optional[str] = None, work_queue_filter: Optional[WorkQueueFilter] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> list[WorkQueue]

Retrieves queues for a work pool.

Args:

• work_pool_name: Name of the work pool for which to get queues.
• work_queue_filter: Criteria by which to filter queues.
• limit: maximum number of work queues to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the work queue query.

Returns:

• List of queues for the specified work pool.

read_worker_metadata ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1072" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_worker_metadata(self) -> dict[str, Any]

Reads worker metadata stored in Prefect collection registry.

read_workers_for_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L413" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_workers_for_work_pool(self, work_pool_name: str, worker_filter: 'WorkerFilter | None' = None, offset: int | None = None, limit: int | None = None) -> list['Worker']

Reads workers for a given work pool.

Args:

• work_pool_name: The name of the work pool for which to get member workers.
• worker_filter: Criteria by which to filter workers.
• limit: Limit for the worker query.
• offset: Limit for the worker query.

release_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L779" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

release_concurrency_slots(self, names: list[str], slots: int, occupancy_seconds: float) -> 'Response'

Release concurrency slots for the specified limits.

Args:

• names: A list of limit names for which to release slots.
• slots: The number of concurrency slots to release.
• occupancy_seconds: The duration in seconds that the slots were occupied.

Returns:

• "Response": The HTTP response from the server.

release_concurrency_slots_with_lease ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L805" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

release_concurrency_slots_with_lease(self, lease_id: 'UUID') -> 'Response'

Release concurrency slots for the specified lease.

Args:

• lease_id: The ID of the lease corresponding to the concurrency limits to release.

renew_concurrency_lease ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L760" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

renew_concurrency_lease(self, lease_id: 'UUID', lease_duration: float) -> 'Response'

Renew a concurrency lease.

Args:

• lease_id: The ID of the lease to renew.
• lease_duration: The new lease duration in seconds.

reset_concurrency_limit_by_tag ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L587" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

reset_concurrency_limit_by_tag(self, tag: str, slot_override: list['UUID | str'] | None = None) -> None

Resets the concurrency limit slots set on a specific tag.

Args:

• tag: a tag the concurrency limit is applied to
• slot_override: a list of task run IDs that are currently using a concurrency slot, please check that any task run IDs included in slot_override are currently running, otherwise those concurrency slots will never be released.

Raises:

• ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

resume_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L295" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resume_automation(self, automation_id: 'UUID') -> None

resume_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L945" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resume_deployment(self, deployment_id: Union[UUID, str]) -> None

Resume (unpause) a deployment by ID.

Args:

• deployment_id: The deployment ID of interest (can be a UUID or a string).

Raises:

• ObjectNotFound: If request returns 404
• RequestError: If request fails

resume_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L730" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resume_flow_run(self, flow_run_id: 'UUID', run_input: dict[str, Any] | None = None) -> 'OrchestrationResult[Any]'

Resumes a paused flow run.

Args:

• flow_run_id: the flow run ID of interest
• run_input: the input to resume the flow run with

Returns:

• an OrchestrationResult model representation of state orchestration output

send_worker_heartbeat ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

send_worker_heartbeat(self, work_pool_name: str, worker_name: str, heartbeat_interval_seconds: float | None = None, get_worker_id: bool = False, worker_metadata: 'WorkerMetadata | None' = None) -> 'UUID | None'

Sends a worker heartbeat for a given work pool.

Args:

• work_pool_name: The name of the work pool to heartbeat against.
• worker_name: The name of the worker sending the heartbeat.
• return_id: Whether to return the worker ID. Note: will return None if the connected server does not support returning worker IDs, even if return_id is True.
• worker_metadata: Metadata about the worker to send to the server.

set_deployment_paused_state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L906" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_deployment_paused_state(self, deployment_id: UUID, paused: bool) -> None

DEPRECATED: Use pause_deployment or resume_deployment instead.

Set the paused state of a deployment.

Args:

• deployment_id: the deployment ID to update
• paused: whether the deployment should be paused

set_flow_run_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L937" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_flow_run_name(self, flow_run_id: 'UUID', name: str) -> httpx.Response

set_flow_run_state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L869" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_flow_run_state(self, flow_run_id: 'UUID | str', state: 'State[T]', force: bool = False) -> 'OrchestrationResult[T]'

Set the state of a flow run.

Args:

• flow_run_id: the id of the flow run
• state: the state to set
• force: if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state

Returns:

• an OrchestrationResult model representation of state orchestration output

set_task_run_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L815" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_task_run_name(self, task_run_id: UUID, name: str) -> httpx.Response

set_task_run_state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L978" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_task_run_state(self, task_run_id: UUID, state: prefect.states.State[T], force: bool = False) -> OrchestrationResult[T]

Set the state of a task run.

Args:

• task_run_id: the id of the task run
• state: the state to set
• force: if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state

Returns:

• an OrchestrationResult model representation of state orchestration output

update_artifact ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_artifact(self, artifact_id: 'UUID', artifact: 'ArtifactUpdate') -> None

update_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_automation(self, automation_id: 'UUID', automation: 'AutomationCore') -> None

Updates an automation in Prefect Cloud.

update_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_block_document(self, block_document_id: 'UUID', block_document: 'BlockDocumentUpdate') -> None

Update a block document in the Prefect API.

update_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_block_type(self, block_type_id: 'UUID', block_type: 'BlockTypeUpdate') -> None

Update a block document in the Prefect API.

update_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L970" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_deployment(self, deployment_id: UUID, deployment: 'DeploymentUpdate') -> None

update_deployment_schedule ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1266" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_deployment_schedule(self, deployment_id: UUID, schedule_id: UUID, active: bool | None = None, schedule: 'SCHEDULE_TYPES | None' = None, max_scheduled_runs: int | None = None, parameters: dict[str, Any] | None = None, slug: str | None = None) -> None

Update a deployment schedule by ID.

Args:

• deployment_id: the deployment ID
• schedule_id: the deployment schedule ID of interest
• active: whether or not the schedule should be active
• schedule: the cron, rrule, or interval schedule this deployment schedule should use
• max_scheduled_runs: The maximum number of scheduled runs for the schedule.
• parameters: Parameter overrides for the schedule.
• slug: A unique identifier for the schedule.

update_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L628" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_flow_run(self, flow_run_id: 'UUID', flow_version: str | None = None, parameters: dict[str, Any] | None = None, name: str | None = None, tags: 'Iterable[str] | None' = None, empirical_policy: 'FlowRunPolicy | None' = None, infrastructure_pid: str | None = None, job_variables: dict[str, Any] | None = None) -> httpx.Response

Update a flow run's details.

Args:

• flow_run_id: The identifier for the flow run to update.
• flow_version: A new version string for the flow run.
• parameters: A dictionary of parameter values for the flow run. This will not be merged with any existing parameters.
• name: A new name for the flow run.
• empirical_policy: A new flow run orchestration policy. This will not be merged with any existing policy.
• tags: An iterable of new tags for the flow run. These will not be merged with any existing tags.
• infrastructure_pid: The id of flow run as returned by an infrastructure block.

Returns:

• an httpx.Response object from the PATCH request

update_flow_run_labels ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L1023" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_flow_run_labels(self, flow_run_id: 'UUID', labels: 'KeyValueLabelsField') -> None

Updates the labels of a flow run.

update_global_concurrency_limit ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L842" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_global_concurrency_limit(self, name: str, concurrency_limit: 'GlobalConcurrencyLimitUpdate') -> 'Response'

update_variable ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_variable(self, variable: 'VariableUpdate') -> None

Updates a variable with the provided configuration.

Args:

• variable: Desired configuration for the updated variable.

Returns: Information about the updated variable.

update_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L556" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_work_pool(self, work_pool_name: str, work_pool: 'WorkPoolUpdate') -> None

Updates a work pool.

Args:

• work_pool_name: Name of the work pool to update.
• work_pool: Fields to update in the work pool.

update_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L599" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_work_queue(self, id: UUID, **kwargs: Any) -> None

Update properties of a work queue.

Args:

• id: the ID of the work queue to update
• **kwargs: the fields to update

Raises:

• ValueError: if no kwargs are provided
• prefect.exceptions.ObjectNotFound: if request returns 404
• httpx.RequestError: if the request fails

upsert_global_concurrency_limit_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L891" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

upsert_global_concurrency_limit_by_name(self, name: str, limit: int, slot_decay_per_second: float | None = None) -> None

Creates a global concurrency limit with the given name and limit if one does not already exist.

If one does already exist matching the name then update it's limit and/or slot_decay_per_second if they are different.

Note: This is not done atomically.

SyncPrefectClient ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A synchronous client for interacting with the Prefect REST API.

Args:

• api: the REST API URL or FastAPI application to connect to
• api_key: An optional API key for authentication.
• api_version: The API version this client is compatible with.
• httpx_settings: An optional dictionary of settings to pass to the underlying httpx.Client

Examples:

Say hello to a Prefect REST API

```python
with get_client(sync_client=True) as client:
    response = client.hello()

print(response.json())
👋
```

Methods:

api_healthcheck ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

api_healthcheck(self) -> Optional[Exception]

Attempts to connect to the API and returns the encountered exception if not successful.

If successful, returns None.

api_url ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

api_url(self) -> httpx.URL

Get the base URL for the API.

api_version ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1450" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

api_version(self) -> str

apply_slas_for_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_experimental/sla/client.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

apply_slas_for_deployment(self, deployment_id: 'UUID', slas: 'list[SlaTypes]') -> 'SlaMergeResponse'

Applies service level agreements for a deployment. Performs matching by SLA name. If a SLA with the same name already exists, it will be updated. If a SLA with the same name does not exist, it will be created. Existing SLAs that are not in the list will be deleted. Args: deployment_id: The ID of the deployment to update SLAs for slas: List of SLAs to associate with the deployment Raises: httpx.RequestError: if the SLAs were not updated for any reason Returns: SlaMergeResponse: The response from the backend, containing the names of the created, updated, and deleted SLAs

client_version ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1454" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

client_version(self) -> str

count_flow_runs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

count_flow_runs(self) -> int

Returns the count of flow runs matching all criteria for flow runs.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues

Returns:

• count of flow runs

create_artifact ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_artifact(self, artifact: 'ArtifactCreate') -> 'Artifact'

create_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_automation(self, automation: 'AutomationCore') -> 'UUID'

Creates an automation in Prefect Cloud.

create_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_block_document(self, block_document: 'BlockDocument | BlockDocumentCreate', include_secrets: bool = True) -> 'BlockDocument'

Create a block document in the Prefect API. This data is used to configure a corresponding Block.

Args:

• include_secrets: whether to include secret values on the stored Block, corresponding to Pydantic's SecretStr and SecretBytes fields. Note Blocks may not work as expected if this is set to False.

create_block_schema ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_block_schema(self, block_schema: 'BlockSchemaCreate') -> 'BlockSchema'

Create a block schema in the Prefect API.

create_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_block_type(self, block_type: 'BlockTypeCreate') -> 'BlockType'

Create a block type in the Prefect API.

create_concurrency_limit ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_concurrency_limit(self, tag: str, concurrency_limit: int) -> 'UUID'

Create a tag concurrency limit in the Prefect API. These limits govern concurrently running tasks.

Args:

• tag: a tag the concurrency limit is applied to
• concurrency_limit: the maximum number of concurrent task runs for a given tag

Raises:

• httpx.RequestError: if the concurrency limit was not created for any reason

Returns:

• the ID of the concurrency limit in the backend

create_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_deployment(self, flow_id: UUID, name: str, version: str | None = None, version_info: 'VersionInfo | None' = None, schedules: list['DeploymentScheduleCreate'] | None = None, concurrency_limit: int | None = None, concurrency_options: 'ConcurrencyOptions | None' = None, parameters: dict[str, Any] | None = None, description: str | None = None, work_queue_name: str | None = None, work_pool_name: str | None = None, tags: list[str] | None = None, storage_document_id: UUID | None = None, path: str | None = None, entrypoint: str | None = None, infrastructure_document_id: UUID | None = None, parameter_openapi_schema: dict[str, Any] | None = None, paused: bool | None = None, pull_steps: list[dict[str, Any]] | None = None, enforce_parameter_schema: bool | None = None, job_variables: dict[str, Any] | None = None, branch: str | None = None, base: UUID | None = None, root: UUID | None = None) -> UUID

Create a deployment.

Args:

• flow_id: the flow ID to create a deployment for
• name: the name of the deployment
• version: an optional version string for the deployment
• tags: an optional list of tags to apply to the deployment
• storage_document_id: an reference to the storage block document used for the deployed flow
• infrastructure_document_id: an reference to the infrastructure block document to use for this deployment
• job_variables: A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example env.CONFIG_KEY=config_value or namespace='prefect'. This argument was previously named infra_overrides. Both arguments are supported for backwards compatibility.

Raises:

• RequestError: if the deployment was not created for any reason

Returns:

• the ID of the deployment in the backend

create_deployment_branch ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L732" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_deployment_branch(self, deployment_id: UUID, branch: str, options: 'DeploymentBranchingOptions | None' = None, overrides: 'DeploymentUpdate | None' = None) -> UUID

create_deployment_schedules ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L463" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_deployment_schedules(self, deployment_id: UUID, schedules: list[tuple['SCHEDULE_TYPES', bool]] | list['DeploymentScheduleCreate'], max_scheduled_runs: int | None = None, parameters: dict[str, Any] | None = None, slug: str | None = None) -> list['DeploymentSchedule']

Create deployment schedules.

Args:

• deployment_id: the deployment ID
• schedules: a list of tuples containing the schedule to create and whether or not it should be active, or a list of DeploymentScheduleCreate objects.
• max_scheduled_runs: The maximum number of scheduled runs for the schedule. Only used when schedules is a list of tuples.
• parameters: Parameter overrides for the schedule. Only used when schedules is a list of tuples.
• slug: A unique identifier for the schedule. Only used when schedules is a list of tuples.

Raises:

• RequestError: if the schedules were not created for any reason

Returns:

• the list of schedules created in the backend

create_flow ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow(self, flow: 'FlowObject[Any, Any]') -> 'UUID'

Create a flow in the Prefect API.

Args:

• flow: a Flow object

Raises:

• httpx.RequestError: if a flow was not created for any reason

Returns:

• the ID of the flow in the backend

create_flow_from_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_from_name(self, flow_name: str) -> 'UUID'

Create a flow in the Prefect API.

Args:

• flow_name: the name of the new flow

Raises:

• httpx.RequestError: if a flow was not created for any reason

Returns:

• the ID of the flow in the backend

create_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_run(self, flow: 'FlowObject[Any, R]', name: str | None = None, parameters: dict[str, Any] | None = None, context: dict[str, Any] | None = None, tags: 'Iterable[str] | None' = None, parent_task_run_id: 'UUID | None' = None, state: 'State[R] | None' = None, work_pool_name: str | None = None, work_queue_name: str | None = None, job_variables: dict[str, Any] | None = None) -> 'FlowRun'

Create a flow run for a flow.

Args:

• flow: The flow model to create the flow run for
• name: An optional name for the flow run
• parameters: Parameter overrides for this flow run.
• context: Optional run context data
• tags: a list of tags to apply to this flow run
• parent_task_run_id: if a subflow run is being created, the placeholder task run identifier in the parent flow
• state: The initial state for the run. If not provided, defaults to Pending.
• work_pool_name: The name of the work pool to run the flow run in.
• work_queue_name: The name of the work queue to place the flow run in.
• job_variables: The job variables to use when setting up flow run infrastructure.

Raises:

• httpx.RequestError: if the Prefect API does not successfully create a run for any reason

Returns:

• The flow run model

create_flow_run_from_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L653" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_run_from_deployment(self, deployment_id: UUID) -> 'FlowRun'

Create a flow run for a deployment.

Args:

• deployment_id: The deployment ID to create the flow run from
• parameters: Parameter overrides for this flow run. Merged with the deployment defaults
• context: Optional run context data
• state: The initial state for the run. If not provided, defaults to Scheduled for now. Should always be a Scheduled type.
• name: An optional name for the flow run. If not provided, the server will generate a name.
• tags: An optional iterable of tags to apply to the flow run; these tags are merged with the deployment's tags.
• idempotency_key: Optional idempotency key for creation of the flow run. If the key matches the key of an existing flow run, the existing run will be returned instead of creating a new one.
• parent_task_run_id: if a subflow run is being created, the placeholder task run identifier in the parent flow
• work_queue_name: An optional work queue name to add this run to. If not provided, will default to the deployment's set work queue. If one is provided that does not exist, a new work queue will be created within the deployment's work pool.
• job_variables: Optional variables that will be supplied to the flow run job.

Raises:

• RequestError: if the Prefect API does not successfully create a run for any reason

Returns:

• The flow run model

create_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L448" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_flow_run_input(self, flow_run_id: 'UUID', key: str, value: str, sender: str | None = None) -> None

Creates a flow run input.

Args:

• flow_run_id: The flow run id.
• key: The input key.
• value: The input value.
• sender: The sender of the input.

create_global_concurrency_limit ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_global_concurrency_limit(self, concurrency_limit: 'GlobalConcurrencyLimitCreate') -> 'UUID'

create_logs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_logs/client.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_logs(self, logs: Iterable[Union['LogCreate', dict[str, Any]]]) -> None

Create logs for a flow or task run

create_task_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_task_run(self, task: 'TaskObject[P, R]', flow_run_id: Optional[UUID], dynamic_key: str, id: Optional[UUID] = None, name: Optional[str] = None, extra_tags: Optional[Iterable[str]] = None, state: Optional[prefect.states.State[R]] = None, task_inputs: Optional[dict[str, list[Union[TaskRunResult, FlowRunResult, Parameter, Constant]]]] = None) -> TaskRun

Create a task run

Args:

• task: The Task to run
• flow_run_id: The flow run id with which to associate the task run
• dynamic_key: A key unique to this particular run of a Task within the flow
• id: An optional ID for the task run. If not provided, one will be generated server-side.
• name: An optional name for the task run
• extra_tags: an optional list of extra tags to apply to the task run in addition to task.tags
• state: The initial state for the run. If not provided, defaults to Pending for now. Should always be a Scheduled type.
• task_inputs: the set of inputs passed to the task

Returns:

• The created task run.

create_variable ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_variable(self, variable: 'VariableCreate') -> 'Variable'

Creates an variable with the provided configuration.

Args:

• variable: Desired configuration for the new variable.

Returns: Information about the newly created variable.

create_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_work_pool(self, work_pool: 'WorkPoolCreate', overwrite: bool = False) -> 'WorkPool'

Creates a work pool with the provided configuration.

Args:

• work_pool: Desired configuration for the new work pool.

Returns:

• Information about the newly created work pool.

create_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1717" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_work_queue(self, name: str, description: Optional[str] = None, is_paused: Optional[bool] = None, concurrency_limit: Optional[int] = None, priority: Optional[int] = None, work_pool_name: Optional[str] = None) -> WorkQueue

Create a work queue.

Args:

• name: a unique name for the work queue
• description: An optional description for the work queue.
• is_paused: Whether or not the work queue is paused.
• concurrency_limit: An optional concurrency limit for the work queue.
• priority: The queue's priority. Lower values are higher priority (1 is the highest).
• work_pool_name: The name of the work pool to use for this queue.

Raises:

• prefect.exceptions.ObjectAlreadyExists: If request returns 409
• httpx.RequestError: If request fails

Returns:

• The created work queue

decrement_v1_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

decrement_v1_concurrency_slots(self, names: list[str], task_run_id: 'UUID', occupancy_seconds: float) -> 'Response'

Decrement concurrency limit slots for the specified limits.

Args:

• names: A list of limit names to decrement.
• task_run_id: The task run ID that incremented the limits.
• occupancy_seconds: The duration in seconds that the limits were held.

Returns:

• "Response": The HTTP response from the server.

delete_artifact ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_artifact(self, artifact_id: 'UUID') -> None

delete_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_automation(self, automation_id: 'UUID') -> None

delete_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_block_document(self, block_document_id: 'UUID') -> None

Delete a block document.

delete_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_block_type(self, block_type_id: 'UUID') -> None

Delete a block type.

delete_concurrency_limit_by_tag ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_concurrency_limit_by_tag(self, tag: str) -> None

Delete the concurrency limit set on a specific tag.

Args:

• tag: a tag the concurrency limit is applied to

Raises:

• ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

delete_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_deployment(self, deployment_id: UUID) -> None

Delete deployment by id.

Args:

• deployment_id: The deployment id of interest.

Raises: ObjectNotFound: If request returns 404 RequestError: If requests fails

delete_deployment_schedule ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L604" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_deployment_schedule(self, deployment_id: UUID, schedule_id: UUID) -> None

Delete a deployment schedule.

Args:

• deployment_id: the deployment ID
• schedule_id: the ID of the deployment schedule to delete.

Raises:

• RequestError: if the schedules were not deleted for any reason

delete_flow ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_flow(self, flow_id: 'UUID') -> None

Delete a flow by UUID.

Args:

• flow_id: ID of the flow to be deleted

Raises: prefect.exceptions.ObjectNotFound: If request returns 404 httpx.RequestError: If requests fail

delete_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_flow_run(self, flow_run_id: 'UUID') -> None

Delete a flow run by UUID.

Args:

• flow_run_id: The flow run UUID of interest.

Raises: ObjectNotFound: If request returns 404 httpx.RequestError: If requests fails

delete_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_flow_run_input(self, flow_run_id: 'UUID', key: str) -> None

Deletes a flow run input.

Args:

• flow_run_id: The flow run id.
• key: The input key.

delete_global_concurrency_limit_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_global_concurrency_limit_by_name(self, name: str) -> 'Response'

delete_resource_owned_automations ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_resource_owned_automations(self, resource_id: str) -> None

delete_task_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1699" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_task_run(self, task_run_id: UUID) -> None

Delete a task run by id.

Args:

• task_run_id: the task run ID of interest

Raises: prefect.exceptions.ObjectNotFound: If request returns 404 httpx.RequestError: If requests fails

delete_variable_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_variable_by_name(self, name: str) -> None

Deletes a variable by name.

delete_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L256" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_work_pool(self, work_pool_name: str) -> None

Deletes a work pool.

Args:

• work_pool_name: Name of the work pool to delete.

delete_work_queue_by_id ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1998" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

delete_work_queue_by_id(self, id: UUID) -> None

Delete a work queue by its ID.

Args:

• id: the id of the work queue to delete

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If requests fails

filter_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L473" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

filter_flow_run_input(self, flow_run_id: 'UUID', key_prefix: str, limit: int, exclude_keys: 'set[str]') -> 'list[FlowRunInput]'

find_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

find_automation(self, id_or_name: 'str | UUID') -> 'Automation | None'

get_most_recent_block_schema_for_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_most_recent_block_schema_for_block_type(self, block_type_id: 'UUID') -> 'BlockSchema | None'

Fetches the most recent block schema for a specified block type ID.

Args:

• block_type_id: The ID of the block type.

Raises:

• httpx.RequestError: If the request fails for any reason.

Returns:

• The most recent block schema or None.

get_runs_in_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1832" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_runs_in_work_queue(self, id: UUID, limit: int = 10, scheduled_before: Optional[datetime.datetime] = None) -> list[FlowRun]

Read flow runs off a work queue.

Args:

• id: the id of the work queue to read from
• limit: a limit on the number of runs to return
• scheduled_before: a timestamp; only runs scheduled before this time will be returned. Defaults to now.

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• List[FlowRun]: a list of FlowRun objects read from the queue

get_scheduled_flow_runs_for_deployments ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L631" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_scheduled_flow_runs_for_deployments(self, deployment_ids: list[UUID], scheduled_before: 'datetime.datetime | None' = None, limit: int | None = None) -> list['FlowRunResponse']

get_scheduled_flow_runs_for_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_scheduled_flow_runs_for_work_pool(self, work_pool_name: str, work_queue_names: list[str] | None = None, scheduled_before: datetime | None = None) -> list['WorkerFlowRunResponse']

Retrieves scheduled flow runs for the provided set of work pool queues.

Args:

• work_pool_name: The name of the work pool that the work pool queues are associated with.
• work_queue_names: The names of the work pool queues from which to get scheduled flow runs.
• scheduled_before: Datetime used to filter returned flow runs. Flow runs scheduled for after the given datetime string will not be returned.

Returns:

• A list of worker flow run responses containing information about the
• retrieved flow runs.

hello ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1444" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

hello(self) -> httpx.Response

Send a GET request to /hello for testing purposes.

increment_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L242" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment_concurrency_slots(self, names: list[str], slots: int, mode: str) -> 'Response'

Increment concurrency slots for the specified limits.

Args:

• names: A list of limit names for which to occupy slots.
• slots: The number of concurrency slots to occupy.
• mode: The mode of the concurrency limits.

increment_concurrency_slots_with_lease ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L266" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment_concurrency_slots_with_lease(self, names: list[str], slots: int, mode: Literal['concurrency', 'rate_limit'], lease_duration: float, holder: 'ConcurrencyLeaseHolder | None' = None) -> 'Response'

Increment concurrency slots for the specified limits with a lease.

Args:

• names: A list of limit names for which to occupy slots.
• slots: The number of concurrency slots to occupy.
• mode: The mode of the concurrency limits.
• lease_duration: The duration of the lease in seconds.
• holder: Optional holder information for tracking who holds the slots.

increment_v1_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment_v1_concurrency_slots(self, names: list[str], task_run_id: 'UUID') -> 'Response'

Increment concurrency limit slots for the specified limits.

Args:

• names: A list of limit names for which to increment limits.
• task_run_id: The task run ID incrementing the limits.

match_work_queues ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1962" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

match_work_queues(self, prefixes: list[str], work_pool_name: Optional[str] = None) -> list[WorkQueue]

Query the Prefect API for work queues with names with a specific prefix.

Args:

• prefixes: a list of strings used to match work queue name prefixes
• work_pool_name: an optional work pool name to scope the query to

Returns:

• a list of WorkQueue model representations of the work queues

pause_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

pause_automation(self, automation_id: 'UUID') -> None

pause_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

pause_deployment(self, deployment_id: Union[UUID, str]) -> None

Pause a deployment by ID.

Args:

• deployment_id: The deployment ID of interest (can be a UUID or a string).

Raises:

• ObjectNotFound: If request returns 404
• RequestError: If request fails

raise_for_api_version_mismatch ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1470" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

raise_for_api_version_mismatch(self) -> None

raise_for_api_version_mismatch_once ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1457" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

raise_for_api_version_mismatch_once(self) -> None

Run API version compatibility check once per process/API/client version.

read_artifacts ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_artifacts(self, **kwargs: Unpack['ArtifactReadParams']) -> list['Artifact']

read_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_automation(self, automation_id: 'UUID | str') -> 'Automation | None'

read_automations ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_automations(self) -> list['Automation']

read_automations_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_automations_by_name(self, name: str) -> list['Automation']

Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.

Args:

• name: the name of the automation to query

Returns:

• a list of Automation model representations of the automations

read_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_document(self, block_document_id: 'UUID', include_secrets: bool = True) -> 'BlockDocument'

Read the block document with the specified ID.

Args:

• block_document_id: the block document id
• include_secrets: whether to include secret values on the Block, corresponding to Pydantic's SecretStr and SecretBytes fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is False.

Raises:

• httpx.RequestError: if the block document was not found for any reason

Returns:

• A block document or None.

read_block_document_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_document_by_name(self, name: str, block_type_slug: str, include_secrets: bool = True) -> 'BlockDocument'

Read the block document with the specified name that corresponds to a specific block type name.

Args:

• name: The block document name.
• block_type_slug: The block type slug.
• include_secrets: whether to include secret values on the Block, corresponding to Pydantic's SecretStr and SecretBytes fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is False.

Raises:

• httpx.RequestError: if the block document was not found for any reason

Returns:

• A block document or None.

read_block_documents ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_documents(self, block_schema_type: str | None = None, offset: int | None = None, limit: int | None = None, include_secrets: bool = True) -> 'list[BlockDocument]'

Read block documents

Args:

• block_schema_type: an optional block schema type
• offset: an offset
• limit: the number of blocks to return
• include_secrets: whether to include secret values on the Block, corresponding to Pydantic's SecretStr and SecretBytes fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is False.

Returns:

• A list of block documents

read_block_documents_by_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_documents_by_type(self, block_type_slug: str, offset: int | None = None, limit: int | None = None, include_secrets: bool = True) -> 'list[BlockDocument]'

Retrieve block documents by block type slug.

Args:

• block_type_slug: The block type slug.
• offset: an offset
• limit: the number of blocks to return
• include_secrets: whether to include secret values

Returns:

• A list of block documents

read_block_schema_by_checksum ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_schema_by_checksum(self, checksum: str, version: str | None = None) -> 'BlockSchema'

Look up a block schema checksum

read_block_schemas ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_schemas/client.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_schemas(self) -> 'list[BlockSchema]'

Read all block schemas Raises: httpx.RequestError: if a valid block schema was not found

Returns:

• A BlockSchema.

read_block_type_by_slug ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_type_by_slug(self, slug: str) -> 'BlockType'

Read a block type by its slug.

read_block_types ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_block_types(self) -> 'list[BlockType]'

Read all block types Raises: httpx.RequestError: if the block types were not found

Returns:

• List of BlockTypes.

read_concurrency_limit_by_tag ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_concurrency_limit_by_tag(self, tag: str) -> 'ConcurrencyLimit'

Read the concurrency limit set on a specific tag.

Args:

• tag: a tag the concurrency limit is applied to

Raises:

• ObjectNotFound: If request returns 404
• httpx.RequestError: if the concurrency limit was not created for any reason

Returns:

• the concurrency limit set on a specific tag

read_concurrency_limits ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_concurrency_limits(self, limit: int, offset: int) -> list['ConcurrencyLimit']

Lists concurrency limits set on task run tags.

Args:

• limit: the maximum number of concurrency limits returned
• offset: the concurrency limit query offset

Returns:

• a list of concurrency limits

read_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployment(self, deployment_id: Union[UUID, str]) -> 'DeploymentResponse'

Query the Prefect API for a deployment by id.

Args:

• deployment_id: the deployment ID of interest

Returns:

• a Deployment model representation of the deployment

read_deployment_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployment_by_name(self, name: str) -> 'DeploymentResponse'

Query the Prefect API for a deployment by name.

Args:

• name: A deployed flow's name: <FLOW_NAME>/<DEPLOYMENT_NAME>

Raises:

• ObjectNotFound: If request returns 404
• RequestError: If request fails

Returns:

• a Deployment model representation of the deployment

read_deployment_schedules ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployment_schedules(self, deployment_id: UUID) -> list['DeploymentSchedule']

Query the Prefect API for a deployment's schedules.

Args:

• deployment_id: the deployment ID

Returns:

• a list of DeploymentSchedule model representations of the deployment schedules

read_deployments ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L377" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_deployments(self) -> list['DeploymentResponse']

Query the Prefect API for deployments. Only deployments matching all the provided criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues
• limit: maximum number of deployments to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the deployment query.

Returns:

• a list of Deployment model representations of the deployments

read_events ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_events/client.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_events(self, filter: 'EventFilter | None' = None, limit: int = 100) -> EventPage

query historical events from the API.

Args:

• filter: optional filter criteria to narrow down events
• limit: maximum number of events to return per page (default 100)

Returns:

• EventPage containing events, total count, and next page link

read_events_page ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_events/client.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_events_page(self, next_page_url: str) -> EventPage

retrieve the next page of events using a next_page URL.

Args:

• next_page_url: the next_page URL from a previous EventPage response

Returns:

• EventPage containing the next page of events

read_flow ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow(self, flow_id: 'UUID') -> 'Flow'

Query the Prefect API for a flow by id.

Args:

• flow_id: the flow ID of interest

Returns:

• a Flow model representation of the flow

read_flow_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_by_name(self, flow_name: str) -> 'Flow'

Query the Prefect API for a flow by name.

Args:

• flow_name: the name of a flow

Returns:

• a fully hydrated Flow model

read_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_run(self, flow_run_id: 'UUID') -> 'FlowRun'

Query the Prefect API for a flow run by id.

Args:

• flow_run_id: the flow run ID of interest

Returns:

• a Flow Run model representation of the flow run

read_flow_run_input ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L491" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_run_input(self, flow_run_id: 'UUID', key: str) -> str

Reads a flow run input.

Args:

• flow_run_id: The flow run id.
• key: The input key.

read_flow_run_states ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_run_states(self, flow_run_id: 'UUID') -> 'list[State]'

Query for the states of a flow run

Args:

• flow_run_id: the id of the flow run

Returns:

• a list of State model representations of the flow run states

read_flow_runs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flow_runs(self) -> 'list[FlowRun]'

Query the Prefect API for flow runs. Only flow runs matching all criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues
• sort: sort criteria for the flow runs
• limit: maximum number of flow runs to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the flow run query.

Returns:

• a list of Flow Run model representations of the flow runs

read_flows ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_flows(self) -> list['Flow']

Query the Prefect API for flows. Only flows matching all criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• work_pool_filter: filter criteria for work pools
• work_queue_filter: filter criteria for work pool queues
• sort: sort criteria for the flows
• limit: maximum number of flows to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the flow query.

Returns:

• a list of Flow model representations of the flows

read_global_concurrency_limit_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L411" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_global_concurrency_limit_by_name(self, name: str) -> 'GlobalConcurrencyLimitResponse'

read_global_concurrency_limits ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L467" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_global_concurrency_limits(self, limit: int = 10, offset: int = 0) -> list['GlobalConcurrencyLimitResponse']

read_latest_artifacts ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L252" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_latest_artifacts(self, **kwargs: Unpack['ArtifactCollectionReadParams']) -> list['ArtifactCollection']

read_logs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_logs/client.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_logs(self, log_filter: 'LogFilter | None' = None, limit: int | None = None, offset: int | None = None, sort: 'LogSort | None' = None) -> list['Log']

Read flow and task run logs.

read_resource_related_automations ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_resource_related_automations(self, resource_id: str) -> list['Automation']

read_task_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_task_run(self, task_run_id: UUID) -> TaskRun

Query the Prefect API for a task run by id.

Args:

• task_run_id: the task run ID of interest

Returns:

• a Task Run model representation of the task run

read_task_run_states ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_task_run_states(self, task_run_id: UUID) -> list[prefect.states.State]

Query for the states of a task run

Args:

• task_run_id: the id of the task run

Returns:

• a list of State model representations of the task run states

read_task_runs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1604" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_task_runs(self) -> list[TaskRun]

Query the Prefect API for task runs. Only task runs matching all criteria will be returned.

Args:

• flow_filter: filter criteria for flows
• flow_run_filter: filter criteria for flow runs
• task_run_filter: filter criteria for task runs
• deployment_filter: filter criteria for deployments
• sort: sort criteria for the task runs
• limit: maximum number of task runs to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the task run query.

Returns:

• a list of Task Run model representations of the task runs

read_variable_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_variable_by_name(self, name: str) -> 'Variable | None'

Reads a variable by name. Returns None if no variable is found.

read_variables ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_variables(self, limit: int | None = None) -> list['Variable']

Reads all variables.

read_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_pool(self, work_pool_name: str) -> 'WorkPool'

Reads information for a given work pool

Args:

• work_pool_name: The name of the work pool to for which to get information.

Returns:

• Information about the requested work pool.

read_work_pool_concurrency_status ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_pool_concurrency_status(self, work_pool_name: str, page: int = 1, limit: int | None = None, flow_run_limit: int = 10) -> 'WorkPoolConcurrencyStatus'

Reads concurrency status for a work pool.

Args:

• work_pool_name: The name of the work pool.
• page: Page number (1-indexed).
• limit: Max queues per page (server default if None).
• flow_run_limit: Max flow runs per queue (0-200).

Returns:

• Paginated concurrency status with per-queue breakdown.

read_work_pools ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_pools(self, limit: int | None = None, offset: int = 0, work_pool_filter: 'WorkPoolFilter | None' = None) -> list['WorkPool']

Reads work pools.

Args:

• limit: Limit for the work pool query.
• offset: Offset for the work pool query.
• work_pool_filter: Criteria by which to filter work pools.

Returns:

• A list of work pools.

read_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1872" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue(self, id: UUID) -> WorkQueue

Read a work queue.

Args:

• id: the id of the work queue to load

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• an instantiated WorkQueue object

read_work_queue_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1771" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue_by_name(self, name: str, work_pool_name: Optional[str] = None) -> WorkQueue

Read a work queue by name.

Args:

• name: a unique name for the work queue
• work_pool_name: the name of the work pool the queue belongs to.

Raises:

• prefect.exceptions.ObjectNotFound: if no work queue is found
• httpx.HTTPStatusError: other status errors

Returns:

• a work queue API object

read_work_queue_concurrency_status ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1924" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue_concurrency_status(self, id: UUID, page: int = 1, limit: Optional[int] = None) -> 'WorkQueueConcurrencyStatus'

Read concurrency status for a work queue.

Args:

• id: the id of the work queue
• page: Page number (1-indexed).
• limit: Max flow runs per page (server default if None).

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• Paginated WorkQueueConcurrencyStatus with flow run summaries

read_work_queue_status ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1898" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queue_status(self, id: UUID) -> WorkQueueStatusDetail

Read a work queue status.

Args:

• id: the id of the work queue to load

Raises:

• prefect.exceptions.ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

Returns:

• an instantiated WorkQueueStatus object

read_work_queues ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L2022" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_work_queues(self, work_pool_name: Optional[str] = None, work_queue_filter: Optional[WorkQueueFilter] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> list[WorkQueue]

Retrieves queues for a work pool.

Args:

• work_pool_name: Name of the work pool for which to get queues.
• work_queue_filter: Criteria by which to filter queues.
• limit: maximum number of work queues to return. When None, the server applies PREFECT_API_DEFAULT_LIMIT (200 by default).
• offset: an offset for the work queue query.

Returns:

• List of queues for the specified work pool.

read_worker_metadata ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L2068" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_worker_metadata(self) -> dict[str, Any]

Reads worker metadata stored in Prefect collection registry.

read_workers_for_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

read_workers_for_work_pool(self, work_pool_name: str, worker_filter: 'WorkerFilter | None' = None, offset: int | None = None, limit: int | None = None) -> list['Worker']

Reads workers for a given work pool.

Args:

• work_pool_name: The name of the work pool for which to get member workers.
• worker_filter: Criteria by which to filter workers.
• limit: Limit for the worker query.
• offset: Limit for the worker query.

release_concurrency_slots ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

release_concurrency_slots(self, names: list[str], slots: int, occupancy_seconds: float) -> 'Response'

Release concurrency slots for the specified limits.

Args:

• names: A list of limit names for which to release slots.
• slots: The number of concurrency slots to release.
• occupancy_seconds: The duration in seconds that the slots were occupied.

Returns:

• "Response": The HTTP response from the server.

release_concurrency_slots_with_lease ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L344" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

release_concurrency_slots_with_lease(self, lease_id: 'UUID') -> 'Response'

Release concurrency slots for the specified lease.

Args:

• lease_id: The ID of the lease corresponding to the concurrency limits to release.

renew_concurrency_lease ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L299" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

renew_concurrency_lease(self, lease_id: 'UUID', lease_duration: float) -> 'Response'

Renew a concurrency lease.

Args:

• lease_id: The ID of the lease to renew.
• lease_duration: The new lease duration in seconds.

reset_concurrency_limit_by_tag ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

reset_concurrency_limit_by_tag(self, tag: str, slot_override: list['UUID | str'] | None = None) -> None

Resets the concurrency limit slots set on a specific tag.

Args:

• tag: a tag the concurrency limit is applied to
• slot_override: a list of task run IDs that are currently using a concurrency slot, please check that any task run IDs included in slot_override are currently running, otherwise those concurrency slots will never be released.

Raises:

• ObjectNotFound: If request returns 404
• httpx.RequestError: If request fails

resume_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resume_automation(self, automation_id: 'UUID') -> None

resume_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resume_deployment(self, deployment_id: Union[UUID, str]) -> None

Resume (unpause) a deployment by ID.

Args:

• deployment_id: The deployment ID of interest (can be a UUID or a string).

Raises:

• ObjectNotFound: If request returns 404
• RequestError: If request fails

resume_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resume_flow_run(self, flow_run_id: 'UUID', run_input: dict[str, Any] | None = None) -> 'OrchestrationResult[Any]'

Resumes a paused flow run.

Args:

• flow_run_id: the flow run ID of interest
• run_input: the input to resume the flow run with

Returns:

• an OrchestrationResult model representation of state orchestration output

send_worker_heartbeat ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

send_worker_heartbeat(self, work_pool_name: str, worker_name: str, heartbeat_interval_seconds: float | None = None, get_worker_id: bool = False, worker_metadata: 'WorkerMetadata | None' = None) -> 'UUID | None'

Sends a worker heartbeat for a given work pool.

Args:

• work_pool_name: The name of the work pool to heartbeat against.
• worker_name: The name of the worker sending the heartbeat.
• return_id: Whether to return the worker ID. Note: will return None if the connected server does not support returning worker IDs, even if return_id is True.
• worker_metadata: Metadata about the worker to send to the server.

set_deployment_paused_state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_deployment_paused_state(self, deployment_id: UUID, paused: bool) -> None

DEPRECATED: Use pause_deployment or resume_deployment instead.

Set the paused state of a deployment.

Args:

• deployment_id: the deployment ID to update
• paused: whether the deployment should be paused

set_flow_run_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L437" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_flow_run_name(self, flow_run_id: 'UUID', name: str) -> httpx.Response

set_flow_run_state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_flow_run_state(self, flow_run_id: 'UUID | str', state: 'State[T]', force: bool = False) -> 'OrchestrationResult[T]'

Set the state of a flow run.

Args:

• flow_run_id: the id of the flow run
• state: the state to set
• force: if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state

Returns:

• an OrchestrationResult model representation of state orchestration output

set_task_run_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1500" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_task_run_name(self, task_run_id: UUID, name: str) -> httpx.Response

set_task_run_state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1653" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_task_run_state(self, task_run_id: UUID, state: prefect.states.State[Any], force: bool = False) -> OrchestrationResult[Any]

Set the state of a task run.

Args:

• task_run_id: the id of the task run
• state: the state to set
• force: if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state

Returns:

• an OrchestrationResult model representation of state orchestration output

update_artifact ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_artifact(self, artifact_id: 'UUID', artifact: 'ArtifactUpdate') -> None

update_automation ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_automations/client.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_automation(self, automation_id: 'UUID', automation: 'AutomationCore') -> None

Updates an automation in Prefect Cloud.

update_block_document ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_documents/client.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_block_document(self, block_document_id: 'UUID', block_document: 'BlockDocumentUpdate') -> None

Update a block document in the Prefect API.

update_block_type ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_blocks_types/client.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_block_type(self, block_type_id: 'UUID', block_type: 'BlockTypeUpdate') -> None

Update a block document in the Prefect API.

update_deployment ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_deployment(self, deployment_id: UUID, deployment: 'DeploymentUpdate') -> None

update_deployment_schedule ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_deployment_schedule(self, deployment_id: UUID, schedule_id: UUID, active: bool | None = None, schedule: 'SCHEDULE_TYPES | None' = None, max_scheduled_runs: int | None = None, parameters: dict[str, Any] | None = None, slug: str | None = None) -> None

Update a deployment schedule by ID.

Args:

• deployment_id: the deployment ID
• schedule_id: the deployment schedule ID of interest
• active: whether or not the schedule should be active
• schedule: the cron, rrule, or interval schedule this deployment schedule should use
• max_scheduled_runs: The maximum number of scheduled runs for the schedule.
• parameters: Parameter overrides for the schedule.
• slug: A unique identifier for the schedule.

update_flow_run ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_flow_run(self, flow_run_id: 'UUID', flow_version: str | None = None, parameters: dict[str, Any] | None = None, name: str | None = None, tags: 'Iterable[str] | None' = None, empirical_policy: 'FlowRunPolicy | None' = None, infrastructure_pid: str | None = None, job_variables: dict[str, Any] | None = None) -> httpx.Response

Update a flow run's details.

Args:

• flow_run_id: The identifier for the flow run to update.
• flow_version: A new version string for the flow run.
• parameters: A dictionary of parameter values for the flow run. This will not be merged with any existing parameters.
• name: A new name for the flow run.
• empirical_policy: A new flow run orchestration policy. This will not be merged with any existing policy.
• tags: An iterable of new tags for the flow run. These will not be merged with any existing tags.
• infrastructure_pid: The id of flow run as returned by an infrastructure block.

Returns:

• an httpx.Response object from the PATCH request

update_flow_run_labels ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L522" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_flow_run_labels(self, flow_run_id: 'UUID', labels: 'KeyValueLabelsField') -> None

Updates the labels of a flow run.

update_global_concurrency_limit ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_global_concurrency_limit(self, name: str, concurrency_limit: 'GlobalConcurrencyLimitUpdate') -> 'Response'

update_variable ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_variables/client.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_variable(self, variable: 'VariableUpdate') -> None

Updates a variable with the provided configuration.

Args:

• variable: Desired configuration for the updated variable.

Returns: Information about the updated variable.

update_work_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_work_pool(self, work_pool_name: str, work_pool: 'WorkPoolUpdate') -> None

Updates a work pool.

Args:

• work_pool_name: Name of the work pool to update.
• work_pool: Fields to update in the work pool.

update_work_queue ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1806" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

update_work_queue(self, id: UUID, **kwargs: Any) -> None

Update properties of a work queue.

Args:

• id: the ID of the work queue to update
• **kwargs: the fields to update

Raises:

• ValueError: if no kwargs are provided
• prefect.exceptions.ObjectNotFound: if request returns 404
• httpx.RequestError: if the request fails

upsert_global_concurrency_limit_by_name ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L429" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

upsert_global_concurrency_limit_by_name(self, name: str, limit: int, slot_decay_per_second: float | None = None) -> None

Creates a global concurrency limit with the given name and limit if one does not already exist.

If one does already exist matching the name then update it's limit and/or slot_decay_per_second if they are different.

Note: This is not done atomically.