​

prefect.client.orchestration

​

Functions

​

get_client

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

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

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

​

Classes

​

PrefectClient

• 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

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

print(response.json())
👋

​

api_healthcheck

api_healthcheck(self) -> Optional[Exception]

​

api_url

api_url(self) -> httpx.URL

​

api_version

api_version(self) -> str

​

apply_slas_for_deployment

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

​

client_version

client_version(self) -> str

​

create_artifact

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

​

create_automation

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

​

create_block_document

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

• 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

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

​

create_block_type

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

​

create_concurrency_limit

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

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

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

• the ID of the concurrency limit in the backend

​

create_deployment

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

• 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.

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

• the ID of the deployment in the backend

​

create_deployment_branch

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

​

create_deployment_schedules

create_deployment_schedules(self, deployment_id: UUID, schedules: list[tuple['SCHEDULE_TYPES', bool]]) -> list['DeploymentSchedule']

• deployment_id: the deployment ID
• schedules: a list of tuples containing the schedule to create and whether or not it should be active.

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

• the list of schedules created in the backend

​

create_flow

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

• flow: a Flow object

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

• the ID of the flow in the backend

​

create_flow_from_name

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

• flow_name: the name of the new flow

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

• the ID of the flow in the backend

​

create_flow_run

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'

• 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.

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

• The flow run model

​

create_flow_run_from_deployment

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

• 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.

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

• The flow run model

​

create_flow_run_input

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

• 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

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

​

create_logs

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

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

​

create_task_run

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

• 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

• The created task run.

​

create_variable

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

​

create_work_pool

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

• work_pool: Desired configuration for the new work pool.

• Information about the newly created work pool.

​

create_work_queue

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

• 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.

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

• The created work queue

​

decrement_v1_concurrency_slots

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

• 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.

• “Response”: The HTTP response from the server.

​

delete_artifact

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

​

delete_automation

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

​

delete_block_document

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

​

delete_block_type

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

​

delete_concurrency_limit_by_tag

delete_concurrency_limit_by_tag(self, tag: str) -> None

• tag: a tag the concurrency limit is applied to

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

​

delete_deployment

delete_deployment(self, deployment_id: UUID) -> None

• deployment_id: The deployment id of interest.

​

delete_deployment_schedule

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

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

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

​

delete_flow

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

• flow_id: ID of the flow to be deleted

​

delete_flow_run

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

• flow_run_id: The flow run UUID of interest.

​

delete_flow_run_input

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

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

​

delete_global_concurrency_limit_by_name

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

​

delete_resource_owned_automations

delete_resource_owned_automations(self, resource_id: str) -> None

​

delete_task_run

delete_task_run(self, task_run_id: UUID) -> None

• task_run_id: the task run ID of interest

​

delete_variable_by_name

delete_variable_by_name(self, name: str) -> None

​

delete_work_pool

delete_work_pool(self, work_pool_name: str) -> None

• work_pool_name: Name of the work pool to delete.

​

delete_work_queue_by_id

delete_work_queue_by_id(self, id: UUID) -> None

• id: the id of the work queue to delete

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

​

filter_flow_run_input

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

​

find_automation

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

​

get_most_recent_block_schema_for_block_type

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

• block_type_id: The ID of the block type.

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

• The most recent block schema or None.

​

get_runs_in_work_queue

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

• 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.

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

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

​

get_scheduled_flow_runs_for_deployments

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

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']

• 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.

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

​

hello

hello(self) -> httpx.Response

​

increment_concurrency_slots

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

• 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

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

• 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.

​

increment_v1_concurrency_slots

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

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

​

loop

loop(self) -> asyncio.AbstractEventLoop | None

​

match_work_queues

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

• 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

• a list of WorkQueue model representations of the work queues

​

pause_automation

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

​

pause_deployment

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

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

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

​

raise_for_api_version_mismatch

raise_for_api_version_mismatch(self) -> None

​

read_artifacts

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

​

read_automation

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

​

read_automations

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

​

read_automations_by_name

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

• name: the name of the automation to query

• a list of Automation model representations of the automations

​

read_block_document

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

• 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.

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

• A block document or None.

​

read_block_document_by_name

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

• 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.

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

• A block document or None.

​

read_block_documents

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

• 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.

• A list of block documents

​

read_block_documents_by_type

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

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

• A list of block documents

​

read_block_schema_by_checksum

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

​

read_block_schemas

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

• A BlockSchema.

​

read_block_type_by_slug

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

​

read_block_types

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

• List of BlockTypes.

​

read_concurrency_limit_by_tag

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

• tag: a tag the concurrency limit is applied to

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

• the concurrency limit set on a specific tag

​

read_concurrency_limits

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

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

• a list of concurrency limits

​

read_deployment

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

• deployment_id: the deployment ID of interest

• a Deployment model representation of the deployment

​

read_deployment_by_name

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

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

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

• a Deployment model representation of the deployment

​

read_deployment_schedules

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

• deployment_id: the deployment ID

• a list of DeploymentSchedule model representations of the deployment schedules

​

read_deployments

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

• 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: a limit for the deployment query
• offset: an offset for the deployment query

• a list of Deployment model representations of the deployments

​

read_flow

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

• flow_id: the flow ID of interest

• a Flow model representation of the flow

​

read_flow_by_name

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

• flow_name: the name of a flow

• a fully hydrated Flow model

​

read_flow_run

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

• flow_run_id: the flow run ID of interest

• a Flow Run model representation of the flow run

​

read_flow_run_input

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

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

​

read_flow_run_states

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

• flow_run_id: the id of the flow run

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

​

read_flow_runs

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

• 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: limit for the flow run query
• offset: offset for the flow run query

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

​

read_flows

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

• 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: limit for the flow query
• offset: offset for the flow query

• a list of Flow model representations of the flows

​

read_global_concurrency_limit_by_name

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

​

read_global_concurrency_limits

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

​

read_latest_artifacts

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

​

read_logs

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

​

read_resource_related_automations

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

​

read_task_run

read_task_run(self, task_run_id: UUID) -> TaskRun

• task_run_id: the task run ID of interest

• a Task Run model representation of the task run

​

read_task_run_states

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

• task_run_id: the id of the task run

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

​

read_task_runs

read_task_runs(self) -> list[TaskRun]

• 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: a limit for the task run query
• offset: an offset for the task run query

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

​

read_variable_by_name

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

​

read_variables

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

​

read_work_pool

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

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

• Information about the requested work pool.

​

read_work_pools

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

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

• A list of work pools.

​

read_work_queue

read_work_queue(self, id: UUID) -> WorkQueue

• id: the id of the work queue to load

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

• an instantiated WorkQueue object

​

read_work_queue_by_name

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

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

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

• a work queue API object

​

read_work_queue_status

read_work_queue_status(self, id: UUID) -> WorkQueueStatusDetail

• id: the id of the work queue to load

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

• an instantiated WorkQueueStatus object

​

read_work_queues

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]

• work_pool_name: Name of the work pool for which to get queues.
• work_queue_filter: Criteria by which to filter queues.
• limit: Limit for the queue query.
• offset: Limit for the queue query.

• List of queues for the specified work pool.

​

read_worker_metadata

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

​

read_workers_for_work_pool

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']

• 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

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

• 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.

• “Response”: The HTTP response from the server.

​

release_concurrency_slots_with_lease

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

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

​

renew_concurrency_lease

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

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

​

reset_concurrency_limit_by_tag

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

• 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.

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

​

resume_automation

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

​

resume_deployment

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

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

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

​

resume_flow_run

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

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

• an OrchestrationResult model representation of state orchestration output

​

send_worker_heartbeat

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'

• 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

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

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

​

set_flow_run_name

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

​

set_flow_run_state

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

• 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

• an OrchestrationResult model representation of state orchestration output

​

set_task_run_name

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

​

set_task_run_state

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

• 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

• an OrchestrationResult model representation of state orchestration output

​

update_artifact

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

​

update_automation

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

​

update_block_document

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

​

update_block_type

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

​

update_deployment

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

​

update_deployment_schedule

update_deployment_schedule(self, deployment_id: UUID, schedule_id: UUID, active: bool | None = None, schedule: 'SCHEDULE_TYPES | None' = None) -> None

• 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

​

update_flow_run

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

• 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.

• an httpx.Response object from the PATCH request

​

update_flow_run_labels

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

​

update_global_concurrency_limit

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

​

update_variable

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

• variable: Desired configuration for the updated variable.

​

update_work_pool

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

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

​

update_work_queue

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

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

• 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

upsert_global_concurrency_limit_by_name(self, name: str, limit: int) -> None

​

SyncPrefectClient

• 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

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

print(response.json())
👋

​

api_healthcheck

api_healthcheck(self) -> Optional[Exception]

​

api_url

api_url(self) -> httpx.URL

​

api_version

api_version(self) -> str

​

apply_slas_for_deployment

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

​

client_version

client_version(self) -> str

​

create_artifact

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

​

create_automation

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

​

create_block_document

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

• 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

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

​

create_block_type

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

​

create_concurrency_limit

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

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

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

• the ID of the concurrency limit in the backend

​

create_deployment

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

• 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.

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

• the ID of the deployment in the backend

​

create_deployment_branch

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

​

create_deployment_schedules

create_deployment_schedules(self, deployment_id: UUID, schedules: list[tuple['SCHEDULE_TYPES', bool]]) -> list['DeploymentSchedule']

• deployment_id: the deployment ID
• schedules: a list of tuples containing the schedule to create and whether or not it should be active.

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

• the list of schedules created in the backend

​

create_flow

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

• flow: a Flow object

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

• the ID of the flow in the backend

​

create_flow_from_name

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

• flow_name: the name of the new flow

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

• the ID of the flow in the backend

​

create_flow_run

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'

• 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.

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

• The flow run model

​

create_flow_run_from_deployment

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

• 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.

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

• The flow run model

​

create_flow_run_input

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

• 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

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

​

create_logs

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

​

create_task_run

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

• 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

• The created task run.

​

create_variable

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

• variable: Desired configuration for the new variable.

​

create_work_pool

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

• work_pool: Desired configuration for the new work pool.

• Information about the newly created work pool.

​

decrement_v1_concurrency_slots