# Code of conduct
Source: https://docs-3.prefect.io/contribute/code-of-conduct

Learn about the standards we hold ourselves and our community to.

## Our pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making
participation in our project and our community a harassment-free experience for everyone. This is regardless of age, body size,
disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity and orientation.

## Our standards

Examples of behavior that contribute to creating a positive environment include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting

## Our responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior. They are expected to take appropriate and
fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues,
and other contributions that are not aligned to this Code of Conduct. They may ban—temporarily or permanently—any contributor for
other behaviors that they deem inappropriate, threatening, offensive, or harmful.

## Scope

This Code of Conduct applies within all project spaces. It also applies when an individual represents the project or its
community in public spaces. Examples of representing a project or community include using an official project email address,
posting through an official social media account, or acting as an appointed representative at an online or offline event.
Project maintainers may further clarify what "representation of a project" means.

## Enforcement

Report instances of abusive, harassing, or otherwise unacceptable behavior by contacting Chris White at
[chris@prefect.io](mailto:chris@prefect.io). All complaints are reviewed and investigated. Each complaint will receive a
response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain
confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted
separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent
repercussions, as determined by other members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant, version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).
See the [Contributor Covenant FAQ](https://www.contributor-covenant.org/faq) for more information.


# Contribute to integrations
Source: https://docs-3.prefect.io/contribute/contribute-integrations



Prefect welcomes contributions to existing integrations.

<Tip>
  Thinking about making your own integration? Feel free to [create a new discussion](https://github.com/PrefectHQ/prefect/discussions/new?category=ideas) to flesh out your idea with other contributors.
</Tip>

## Contributing to existing integrations

All integrations are hosted in the [Prefect GitHub repository](https://github.com/PrefectHQ/prefect) under `src/integrations`.

To contribute to an existing integration, please follow these steps:

<Steps>
  <Step title="Fork the repository 🍴">
    Fork the [Prefect GitHub repository](https://github.com/PrefectHQ/prefect)
  </Step>

  <Step title="Clone your fork 👯">
    ```bash
    git clone https://github.com/your-username/prefect.git
    ```
  </Step>

  <Step title="Create a new branch 🌲">
    ```bash
    git checkout -b my-new-branch
    ```
  </Step>

  <Step title="Set up your environment 📂">
    Move to the integration directory and install the dependencies:

    ```bash
    cd src/integrations/my-integration
    uv venv --python 3.12
    source .venv/bin/activate
    uv pip install -e ".[dev]"
    ```
  </Step>

  <Step title="Make your changes 👩‍🍳">
    Make the necessary changes to the integration code.
  </Step>

  <Step title="Add tests 🧪">
    If you're adding new functionality, please add tests.

    You can run the tests with:

    ```bash
    pytest tests
    ```
  </Step>

  <Step title="Submit your changes 📨">
    ```bash
    git add .
    git commit -m "My new integration"
    git push origin my-new-branch
    ```
  </Step>

  <Step title="Create a pull request ⏰">
    Submit your pull request upstream through the GitHub interface.
  </Step>
</Steps>


# Develop on Prefect
Source: https://docs-3.prefect.io/contribute/dev-contribute

Learn how to set up Prefect for development, experimentation and code contributions.

## Make a code contribution

We welcome all forms of contributions to Prefect, whether it's small typo fixes in [our documentation](/contribute/docs-contribute), bug fixes or feature enhancements!
If this is your first time making an open source contribution we will be glad to work with you and help you get up to speed.

<Note>
  For small changes such as typo fixes you can simply open a pull request - we typically review small changes like these within the day.
  For larger changes including all bug fixes, we ask that you first open [an issue](https://github.com/PrefectHQ/prefect/issues) or comment on the issue that you are planning to work on.
</Note>

## Fork the repository

All contributions to Prefect need to start on [a fork of the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
Once you have successfully forked [the Prefect repo](https://github.com/PrefectHQ/prefect), clone a local version to your machine:

```bash
git clone https://github.com/GITHUB-USERNAME/prefect.git
cd prefect
```

Create a branch with an informative name:

```
git checkout -b fix-for-issue-NUM
```

After committing your changes to this branch, you can then open a pull request from your fork that we will review with you.

## Install Prefect for development

Once you have cloned your fork of the repo you can install [an editable version](https://setuptools.pypa.io/en/latest/userguide/development_mode.html) of Prefect for quick iteration.

We recommend using `uv` for dependency management when developing. Refer to the [`uv` docs for installation instructions](https://docs.astral.sh/uv/getting-started/installation/).

To set up a virtual environment and install a development version of `prefect`:

<CodeGroup>
  ```bash uv
  uv sync
  ```

  ```bash pip and venv
  python -m venv .venv
  source .venv/bin/activate

  # Installs the package with development dependencies
  pip install -e ".[dev]"
  ```
</CodeGroup>

To verify `prefect` was install correctly:

<CodeGroup>
  ```bash uv
  uv run prefect --version
  ```

  ```bash pip and venv
  prefect --version
  ```
</CodeGroup>

To ensure your changes comply with our linting policies, set up `pre-commit` and `pre-push` hooks to run with every commit:

```bash
uv run pre-commit install
```

To manually run the `pre-commit` hooks against all files:

```bash
uv run pre-commit run --all-files
```

To manually run the pre-push hooks:

```bash
uv run pre-commit run --hook-stage pre-push --all-files
```

<Tip>
  If you're using `uv`, you can run commands with the project's dependencies by prefixing the command with `uv run`.
</Tip>

## Write tests

Prefect relies on unit testing to ensure proposed changes don't negatively impact any functionality.
For all code changes, including bug fixes, we ask that you write at least one corresponding test.
One rule of thumb - especially for bug fixes - is that you should write a test that fails prior to your changes and passes with your changes.
This ensures the test will fail and prevent the bug from resurfacing if other changes are made in the future.
All tests can be found in the `tests/` directory of the repository.

You can run the test suite with `pytest`:

```bash
# run all tests
pytest tests

# run a specific file
pytest tests/test_flows.py

# run all tests that match a pattern
pytest tests/test_tasks.py -k cache_policy
```

## Working with a development UI

If you plan to use the UI during development, you will need to build a development version of the UI first.

Using the Prefect UI in development requires installation of [npm](https://github.com/npm/cli).
We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.
Once installed, run `nvm use` from the root of the Prefect repository to initialize the proper version of `npm` and `node`.

Start a development UI that reloads on code changes:

```bash
prefect dev ui
```

This command is most useful if you are working directly on the UI codebase.

Alternatively, you can build a static UI that will be served when running `prefect server start`:

```bash
prefect dev build-ui
```

## Working with a development server

The Prefect CLI provides several helpful commands to aid development of server-side changes.

You can start all services with hot-reloading on code changes (note that this requires installation of UI dependencies):

```bash
prefect dev start
```

Start a Prefect API that reloads on code changes:

```bash
prefect dev api
```

## Add database migrations

If your code changes necessitate modifications to a database table, first update the SQLAlchemy model in `src/prefect/server/database/orm_models.py`.

For example, to add a new column to the `flow_run` table, add a new column to the `FlowRun` model:

```python
# src/prefect/server/database/orm_models.py

class FlowRun(Run):
    """SQLAlchemy model of a flow run."""
    ...
    new_column: Mapped[Union[str, None]] = mapped_column(sa.String, nullable=True) # <-- add this line
```

Next, generate new migration files.
Generate a new migration file for each database type.

Migrations are generated for whichever database type `PREFECT_API_DATABASE_CONNECTION_URL` is set to.
See [how to set the database connection URL](/v3/api-ref/settings-ref#connection-url) for each database type.

To generate a new migration file, run:

```bash
prefect server database revision --autogenerate -m "<migration name>"
```

Make the migration name brief but descriptive.
For example:

* `add_flow_run_new_column`
* `add_flow_run_new_column_idx`
* `rename_flow_run_old_column_to_new_column`

The `--autogenerate` flag automatically generates a migration file based on the changes to the models.

<Warning>
  **Always inspect the output of `--autogenerate`**

  `--autogenerate` generates a migration file based on the changes to the models.
  However, it is not perfect. Check the file to ensure it only includes the desired changes.
</Warning>

The new migration is in the `src/prefect/server/database/migrations/versions/` directory. Each database type has its
own subdirectory. For example, the SQLite migrations are stored in `src/prefect/server/database/migrations/versions/sqlite/`.

After inspecting the migration file, apply the migration to the database by running:

```bash
prefect server database upgrade -y
```

After successfully creating migrations for all database types, update `MIGRATION-NOTES.md` to
document the changes.


# Contribute to documentation
Source: https://docs-3.prefect.io/contribute/docs-contribute

Learn how to contribute to the Prefect docs.

We use [Mintlify](https://mintlify.com/) to host and build the Prefect documentation.

The main branch of the [prefecthq/prefect](https://github.com/PrefectHQ/prefect) GitHub repository is used to build the Prefect 3.0 docs at [docs.prefect.io](https://docs.prefect.io).

The 2.x docs are hosted at [docs-2.prefect.io](https://docs-2.prefect.io) and built from the 2.x branch of the repository.

## Fork the repository

All contributions to Prefect need to start on [a fork of the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
Once you have successfully forked [the Prefect repo](https://github.com/PrefectHQ/prefect), clone a local version to your machine:

```bash
git clone https://github.com/GITHUB-USERNAME/prefect.git
cd prefect
```

Create a branch with an informative name:

```
git checkout -b fix-for-issue-NUM
```

After committing your changes to this branch, you can then open a pull request from your fork that we will review with you.

## Set up your local environment

We provide a `justfile` with common commands to simplify development. We recommend using [just](https://just.systems/) to run these commands.

<Note>
  **Installing just**

  To install just:

  * **macOS**: `brew install just` or `cargo install just`
  * **Linux**: `cargo install just` or check your package manager
  * **Windows**: `scoop install just` or `cargo install just`

  For more installation options, see the [just documentation](https://github.com/casey/just#installation).
</Note>

### Using just (recommended)

1. Clone this repository.
2. Run `just docs` to start the documentation server.

Your docs should now be available at `http://localhost:3000`.

### Manual setup

If you prefer not to use just, you can set up manually:

1. Clone this repository.
2. Make sure you have a recent version of Node.js installed. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.
3. Run `cd docs` to navigate to the docs directory.
4. Run `nvm use node` to use the correct Node.js version.
5. Run `npm i -g mintlify` to install Mintlify.
6. Run `mintlify dev` to start the development server.

Your docs should now be available at `http://localhost:3000`.

See the [Mintlify documentation](https://mintlify.com/docs/development) for more information on how to install Mintlify, build previews, and use Mintlify's features while writing docs.

<Info>All documentation is written in `.mdx` files, which are Markdown files that can contain JavaScript and React components. </Info>

## Contributing examples

Examples are Python files that demonstrate Prefect concepts and patterns and how they work together with other tools to solve real-world problems. They live in the `examples/` directory and are used to automatically generate documentation pages.

### Example structure

Each example should be a standalone Python file with:

1. **YAML frontmatter** (in Python comments) at the top with metadata:
   ```python
   # ---
   # title: Your Example Title
   # description: Brief description of what this example demonstrates
   # icon: play  # Choose from available icons (play, database, globe, etc.)
   # dependencies: ["prefect", "pandas", "requests"]  # Required packages
   # cmd: ["python", "path/to/your_example.py"]  # How to run it
   # keywords: ["getting_started", "etl", "api"]  # Keywords to help with search and filtering
   # draft: false  # Set to true to hide from docs
   # ---
   ```

2. **Explanatory comments** throughout the code which will be used to generate the body of the documentation page.

3. **Runnable code** that works out of the box with the specified dependencies.

See the [hello world example](https://github.com/PrefectHQ/prefect/blob/main/examples/hello_world.py) as a guide.

### Adding an example

To add an example, follow these steps:

1. Create your Python file in the `examples/` directory
2. Follow the structure above with frontmatter and comments
3. Test that your example runs successfully
4. Run `just generate-examples` to update the documentation pages
5. Review the generated documentation to ensure it renders correctly

Once it all looks good, commit your changes and open a pull request.

## Considerations

Keep in mind the following when writing documentation.

### External references

Prefect resources can be managed in several ways, including through the CLI, UI, Terraform, Helm, and API.

When documenting a resource, consider including external references that describe how to manage the resource in other ways.
Snippets are available to provide these references in a consistent format.

For example, the [Deployment documentation](/v3/deploy) includes a snippet for the Terraform provider:

```javascript
import { TF } from "/snippets/resource-management/terraform.mdx"
import { deployments } from "/snippets/resource-management/vars.mdx"

<TF name="deployments" href={deployments.tf} />
```

For more information on how to use snippets, see the [Mintlify documentation](https://mintlify.com/docs/reusable-snippets).


# Contribute
Source: https://docs-3.prefect.io/contribute/index

Join the community, improve Prefect, and share knowledge

We welcome all forms of engagement, and love to learn from our users.
There are many ways to get involved with the Prefect community:

* Join nearly 30,000 engineers in the [Prefect Slack community](https://prefect.io/slack)
* [Give Prefect a ⭐️ on GitHub](https://github.com/PrefectHQ/prefect)
* Make a contribution to [Prefect's documentation](/contribute/docs-contribute)
* Make a code contribution to [Prefect's open source libraries](/contribute/dev-contribute)
* Support or create a new [Prefect integration](/contribute/contribute-integrations)

## Report an issue

To report a bug, make a feature request, and more, visit our [issues page on GitHub](https://github.com/PrefectHQ/prefect/issues/new/choose).

## Code of conduct

See our [code of conduct](/contribute/code-of-conduct) for becoming a valued contributor.


# Code and development style guide
Source: https://docs-3.prefect.io/contribute/styles-practices



Generally, we follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).
This document covers Prefect-specific styles and practices.

## Imports

This is a brief collection of rules and guidelines for handling imports in this repository.

### Imports in `__init__` files

Leave `__init__` files empty unless exposing an interface. If you must expose objects to present a simpler API,
please follow these rules.

#### Exposing objects from submodules

If importing objects from submodules, the `__init__` file should use a relative import. This is
[required for type checkers](https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md#library-interface)
to understand the exposed interface.

{/* pmd-metadata: notest */}

```python
# Correct
from .flows import flow

```

```python
# Wrong
from prefect.flows import flow

```

#### Exposing submodules

Generally, submodules should *not* be imported in the `__init__` file. You should only expose submodules when the module
is designed to be imported and used as a namespaced object.

For example, we do this for our schema and model modules. This is because it's important to know if you are working with an API
schema or database model—both of which may have similar names.

```python
import prefect.server.schemas as schemas

# The full module is accessible now
schemas.core.FlowRun

```

If exposing a submodule, use a relative import like when you're exposing an object.

{/* pmd-metadata: notest */}

```python
# Correct
from . import flows

```

```python
# Wrong
import prefect.flows

```

#### Importing to run side-effects

Another use case for importing submodules is to perform global side-effects that occur when they are imported.

Often, global side-effects on import are a dangerous pattern. But there are a couple acceptable
use cases for this:

* To register dispatchable types, for example, `prefect.serializers`.
* To extend a CLI app, for example, `prefect.cli`.

### Imports in modules

#### Importing other modules

The `from` syntax is recommended for importing objects from modules. You should not import modules
with the `from` syntax.

```python
# Correct
import prefect.server.schemas  # use with the full name
import prefect.server.schemas as schemas  # use the shorter name

```

```python
# Wrong
from prefect.server import schemas

```

You should not use relative imports unless it's in an `__init__.py` file.

{/* pmd-metadata: notest */}

```python
# Correct
from prefect.utilities.foo import bar
```

{/* pmd-metadata: notest */}

```python
# Wrong
from .utilities.foo import bar

```

You should never use imports that are dependent on file location without explicit indication it is relative. This avoids
confusion about the source of a module.

{/* pmd-metadata: notest */}

```python
# Correct
from . import test

```

#### Resolving circular dependencies

Sometimes, you must defer an import and perform it *within* a function to avoid a circular dependency:

```python
## This function in `settings.py` requires a method from the global `context` but the context
## uses settings
def from_context():
    from prefect.context import get_profile_context

    ...

```

Avoid circular dependencies. They often reveal entanglement in the design.

Place all deferred imports at the top of the function.

If you are just using the imported object for a type signature, use the `TYPE_CHECKING` flag:

```python
# Correct
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from prefect.server.schemas.states import State

def foo(state: "State"):
    pass

```

Usage of the type within the module requires quotes; for example, `"State"`, since it is not available at runtime.

#### Importing optional requirements

We do not have a best practice for this yet. See the `kubernetes`, `docker`, and `distributed` implementations for now.

#### Delaying expensive imports

Sometimes imports are slow, but it's important to keep the `prefect` module import times fast. In these cases, lazily
import the slow module by deferring import to the relevant function body. For modules consumed by many functions,
use the optional requirements pattern instead.

## Command line interface (CLI) output messages

When executing a command that creates an object, the output message should offer:

* A short description of what the command just did.
* A bullet point list, rehashing user inputs, if possible.
* Next steps, like the next command to run, if applicable.
* Other relevant, pre-formatted commands that can be copied and pasted, if applicable.
* A new line before the first line, and after the last line.

Output Example:

```js
$ prefect work-queue create testing

Created work queue with properties:
    name - 'abcde'
    uuid - 940f9828-c820-4148-9526-ea8107082bda
    tags - None
    deployment_ids - None

Start an agent to pick up flows from the created work queue:
    prefect agent start -q 'abcde'

Inspect the created work queue:
    prefect work-queue inspect 'abcde'

```

Additionally:

* Wrap generated arguments in apostrophes (') to ensure validity by using suffixing formats with `!r`.
* Indent example commands, instead of wrapping in backticks (\`).
* Use placeholders if you cannot completely pre-format the example.
* Capitalize placeholder labels and wrap them in less than (\<) and greater than (>) signs.
* Utilize `textwrap.dedent` to remove extraneous spacing for strings with triple quotes (""").

Placeholder Example:

```
Create a work queue with tags:
    prefect work-queue create '<WORK QUEUE NAME>' -t '<OPTIONAL TAG 1>' -t '<OPTIONAL TAG 2>'

```

Dedent Example:

{/* pmd-metadata: notest */}

```python
from textwrap import dedent
...
output_msg = dedent(
    f"""
    Created work queue with properties:
        name - {name!r}
        uuid - {result}
        tags - {tags or None}
        deployment_ids - {deployment_ids or None}

    Start an agent to pick up flows from the created work queue:
        prefect agent start -q {name!r}

    Inspect the created work queue:
        prefect work-queue inspect {name!r}
    """
)

```

## API versioning

### Client and server communication

You can run the Prefect client separately from Prefect server, and communicate entirely through an API.
The Prefect client includes anything that runs task or flow code, (for example, agents and the Python client);
or any consumer of Prefect metadata (for example, the Prefect UI and CLI).

Prefect server stores this metadata and serves it through the REST API.

### API version header

Sometimes, we have to make breaking changes to the API. To check a Prefect client's compatibility
with the API it's making requests to, every API call the client makes includes a three-component `API_VERSION` header with major,
minor, and patch versions.

For example, a request with the `X-PREFECT-API-VERSION=3.2.1` header has a major version of `3`, minor version `2`, and patch
version `1`.

Change this version header by modifying the `API_VERSION` constant in `prefect.server.api.server`.

### Breaking changes to the API

A breaking change means that your code needs to change to use a new version of Prefect. We avoid breaking
changes whenever possible.

When making a breaking change to the API, we consider if the change is *backwards compatible for clients*.
This means that the previous version of the client can still make calls against the updated version of the server code.
This might happen if the changes are purely additive, such as adding a non-critical API route. In these cases, we aim
to bump the patch version.

In almost all other cases, we bump the minor version, which denotes a non-backwards-compatible API change. We have reserved
the major version changes to denote a backwards compatible change that is significant in some way, such as a major release
milestone.

### Version composition

Versions are composed of three parts: MAJOR.MINOR.PATCH. For example, the version 2.5.0 has a major version of 2, a minor version
of 5, and patch version of 0.

Occasionally, we add a suffix to the version such as `rc`, `a`, or `b`. These indicate pre-release versions that users can
opt into for testing and experimentation prior to a generally available release.

Each release will increase one of the version numbers. If we increase a number other than the patch version, the versions to the
right of it reset to zero.

## Prefect's versioning scheme

Prefect increases the major version when significant and widespread changes are made to the core product.

Prefect increases the minor version when:

* Introducing a new concept that changes how to use Prefect
* Changing an existing concept in a way that fundamentally alters its usage
* Removing a deprecated feature

Prefect increases the patch version when:

* Making enhancements to existing features
* Fixing behavior in existing features
* Adding new capabilities to existing concepts
* Updating dependencies

## Deprecation

At times, Prefect will deprecate a feature. A feature is deprecated when it will no longer be maintained. Frequently,
a deprecated feature will have a new and improved alternative. Deprecated features will be retained for at least **3** minor
version increases or **6 months**, whichever is longer. We may retain deprecated features longer than this time period.

Prefect will sometimes include changes to behavior to fix a bug. These changes are not categorized as breaking changes.

## Client compatibility with Prefect

When running a Prefect server, you are in charge of ensuring the version is compatible with those of the clients that are
using the server. Prefect aims to maintain backwards compatibility with old clients for each server release. In contrast,
sometimes you cannot use new clients with an old server. The new client may expect the server to support capabilities that
it does not yet include. For this reason, we recommend that all clients are the same version as the server or older.

For example, you can use a client on 2.1.0 with a server on 2.5.0. You cannot use a client on 2.5.0 with a server on 2.1.0.

## Client compatibility with Cloud

Prefect Cloud targets compatibility with all versions of Prefect clients. If you encounter a compatibility issue, please
[file a bug report](https://github.com/prefectHQ/prefect/issues/new/choose).


# null
Source: https://docs-3.prefect.io/integrations/integrations

Prefect integrations are PyPI packages you can install to help you build integrate your workflows with third parties.

<CardGroup cols={4} className="text-center">
  <Card title="AWS">
    <a href="/integrations/prefect-aws">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aws.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=1f32aedc4d56ba116aedbf8b27299b12" noZoom alt="prefect-aws" data-og-width="500" width="500" data-og-height="500" height="500" data-path="images/integrations/aws.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aws.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=23c9c04c4cc27e1d60a13c412a8634fc 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aws.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=23fa1333b84ce6df88ef92b3c1cfe388 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aws.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=4feb5ac458e8968584671faac77eec99 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aws.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=96e8ee6988b177dd05aee01a3b49bf2f 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aws.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=05f916c02da96658bba7ab8184183f19 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aws.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=0dc9e57371d5199c1a4f46a11f460ce9 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Azure">
    <a href="/integrations/prefect-azure">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/azure.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=2e9ea50ceb7620adeadef35a1d3fb7d0" noZoom alt="prefect-azure" data-og-width="1200" width="1200" data-og-height="1200" height="1200" data-path="images/integrations/azure.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/azure.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ed132c93e4e1970ca90d37cde6d7e637 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/azure.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=2973fe5fe3919b7ea39f7e2dd483fc67 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/azure.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=d92e981f9c4ae05df6ebbc366ca862a6 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/azure.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9960e3d37235d23fe6105f3be05cda5e 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/azure.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=301866ddca9139c88ea2b97fc0f660eb 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/azure.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=08fd6302bc105cf710bcddfd693fa953 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Bitbucket">
    <a href="/integrations/prefect-bitbucket">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/bitbucket.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9816b2b9d29b96592fb567baa8d3d4ad" noZoom alt="prefect-bitbucket" data-og-width="500" width="500" data-og-height="500" height="500" data-path="images/integrations/bitbucket.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/bitbucket.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=78d9f321aaeef7248afddfde8723601f 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/bitbucket.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ed053783d0d01dd75faab4022499e88d 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/bitbucket.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=b9a0b3d33c0a52662e5fdcd9dcf13630 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/bitbucket.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=bb3d3dc695d19381486f02bec02bbe03 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/bitbucket.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=efc4ab9ceef62ef7b739ba4b484c23c0 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/bitbucket.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=d8847c50a855888a413c85ce8f10a002 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Coiled">
    <a href="https://docs.coiled.io/user_guide/prefect.html?utm_source=prefect-docs&utm_medium=integrations">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/coiled.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a2f448cf759f415d37cbf71634a3d0f7" noZoom alt="coiled" data-og-width="150" width="150" data-og-height="150" height="150" data-path="images/integrations/coiled.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/coiled.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=da0f2b3a3836d258f70be3f441cc53c5 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/coiled.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=860e6ee18b3006b3b498cf6485a32ca7 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/coiled.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a431f28f15d2683d155c80deac6d5702 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/coiled.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=1e514cfe4e9fb222f6085d4daa556d72 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/coiled.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a474d91b74ff1f526279df87f0e2b8a8 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/coiled.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=f35294df8dfc344ab1d2abec6a7f66dd 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://www.coiled.io/"> Coiled </a>
  </Card>

  <Card title="Dask">
    <a href="/integrations/prefect-dask">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dask.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=d776940d44aff9b094000a6b9c8e2925" noZoom alt="prefect-dask" data-og-width="256" width="256" data-og-height="256" height="256" data-path="images/integrations/dask.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dask.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9616ce28aec9a2ea1226ea8552333c3c 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dask.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=aa113027df264679da159c576d2ce0cf 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dask.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=0ab413bf4cf8be1299faa82be109f6b7 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dask.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=b28199bb220d25aeeef47d0cefe35c21 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dask.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=eae6f13d7a7fffd3d207b9d07f021b37 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dask.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9972fe70eec9e65a25344c15dae7c33a 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Databricks">
    <a href="/integrations/prefect-databricks">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/databricks.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ecd7dcaccfbff4128ff50d7adabd58e2" noZoom alt="prefect-databricks" data-og-width="250" width="250" data-og-height="250" height="250" data-path="images/integrations/databricks.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/databricks.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=f84b9b323f7c48be31e4f93a004a0a53 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/databricks.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=1d929514e06a56ff42ffcbd3ab660ee1 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/databricks.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ee839a31ffe0adfaf2ca0c1e03e87524 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/databricks.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c62940897cf09b023c7f2770c2dcd1c6 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/databricks.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=20c204bc72c90a7162a50788fbd3a69a 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/databricks.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a273704b24755e37c95d7b69879d03d4 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="dbt">
    <a href="/integrations/prefect-dbt">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dbt.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=8c923cbd49bd904660a7f7c62f013cc2" noZoom alt="prefect-dbt" data-og-width="180" width="180" data-og-height="162" height="162" data-path="images/integrations/dbt.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dbt.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=5218d03d1a6b2d12a4b1269594d29f05 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dbt.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c77b32c91cd192fabda52fc35c9bf97c 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dbt.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=759f9fea752a4a1fb58160d926ff97dd 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dbt.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=30bb13f673d7f4746e991ff637bb3c87 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dbt.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=7f2ddfbaea2f8253036efeeea84397bb 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/dbt.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=6da285633de1b4a66c23e18463f14cc2 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Docker">
    <a href="/integrations/prefect-docker">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/docker.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=105b528c8bfdd7878615cc2f0c4a90e4" noZoom alt="prefect-docker" data-og-width="601" width="601" data-og-height="601" height="601" data-path="images/integrations/docker.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/docker.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=94e061805d73ca3033a2650e1b9eb229 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/docker.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=2e8cb5604080032fa485da0668ba668f 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/docker.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=310dbf436d5bd20bd34d5f044f466129 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/docker.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=b6aef4c7aac2ed1b858dcc89e7c19ac0 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/docker.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=52453de9279b0ad14cbd0e2600191cfc 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/docker.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a67df13dbb0792a32820bfcd0e40189f 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Email">
    <a href="/integrations/prefect-email">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/email.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=fda57db803c36455bcacfd08e36819de" noZoom alt="prefect-email" data-og-width="2048" width="2048" data-og-height="2048" height="2048" data-path="images/integrations/email.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/email.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=2254177d2a4dc7f75d5f016307ba7039 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/email.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=d63c68af5eb176e3a314362028a20a17 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/email.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=e22a8e06d8bc7c698efbf5fdec0f523f 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/email.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=cd94bbd3ef06f0ce18de1faee59720cb 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/email.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=0c830e45da9d5f257029b183d2c6cb54 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/email.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=4cc203d1dac5ed9bd4eab26eb276e141 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Fivetran">
    <a href="https://fivetran.github.io/prefect-fivetran/">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/fivetran.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c750a1ed78b8e116705af3e737b29ae5" noZoom alt="prefect-fivetran" data-og-width="250" width="250" data-og-height="250" height="250" data-path="images/integrations/fivetran.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/fivetran.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ae9f7c4b6782cb16824d8d94706020aa 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/fivetran.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=344abe0eeb76000c9afcea6efdf78373 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/fivetran.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=148542f98b00e02f3309cf933817a8fe 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/fivetran.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=3d880e47ba87b030e35573d4c6847c37 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/fivetran.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=07266c4c05681d85b4432e62075fda72 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/fivetran.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=616997c02279e2e1f574f7e6c51e5ff3 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://www.fivetran.com/"> Fivetran </a>
  </Card>

  <Card title="GCP">
    <a href="/integrations/prefect-gcp">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gcp.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=e8d5776b853ae92fd2c99a7f60013e29" noZoom alt="prefect-gcp" data-og-width="511" width="511" data-og-height="511" height="511" data-path="images/integrations/gcp.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gcp.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9fb8dcef3c764bb4b4b7981ac2b9af1f 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gcp.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=d83481c9b879c7d96a411c3a772a5a1a 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gcp.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c895c1a8094f8d8cc6fad23d82e611fa 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gcp.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=339a9080687e2e16a9c0bc0ad60130b0 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gcp.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=cd9d886b146dbdfe5dd49e42447923f1 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gcp.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=09b9ec4bce7cc6bb44fbc961702b1b22 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="GitHub">
    <a href="/integrations/prefect-github">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/github.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=354f3ddc48b7188884da90e8260c0024" noZoom alt="prefect-github" data-og-width="4096" width="4096" data-og-height="4096" height="4096" data-path="images/integrations/github.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/github.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=dd052a6658d57fc83f5244da9280bc53 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/github.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c270231e8d4e18168a9768e919cf5dd4 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/github.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a6a37537fe0e593c310f5a11cbd63d9f 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/github.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=0314904682c2c737f7cbac46e480faed 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/github.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ac6e03f5a5fa2801596393666472ff77 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/github.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=e935f32527526a65df023a67e081ffb9 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="GitLab">
    <a href="/integrations/prefect-gitlab">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gitlab.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c2b317bf397308d61b75d9ec3a1e4e12" noZoom alt="prefect-gitlab" data-og-width="250" width="250" data-og-height="250" height="250" data-path="images/integrations/gitlab.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gitlab.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=dc78d3184134057c0eed3d1191aa89f3 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gitlab.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=5aeec87dff0fc87364db8c937819f72e 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gitlab.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=798f11cf83b12de6e16b3851a98165f5 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gitlab.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=56420a838519f4264c72466604672aa9 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gitlab.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=0ba7ac0d359b0763061a9e527972b8e0 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/gitlab.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9c244ae45ac68db0b63ef10b0314af45 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Kubernetes">
    <a href="/integrations/prefect-kubernetes">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/kubernetes.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=fe31039a040002e0bb6154f2af1d2624" noZoom alt="prefect-kubernetes" data-og-width="1200" width="1200" data-og-height="1165" height="1165" data-path="images/integrations/kubernetes.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/kubernetes.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=be00773dba9aa7ae1f1e59d5cdd96e59 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/kubernetes.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=607109abf0dc83869e09e52d6d59a984 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/kubernetes.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ec191604a858acfc1cd7d3ad52e50903 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/kubernetes.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=98bca049866513fa8e2a7607070037ab 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/kubernetes.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=0d6dc1c704ae9d64826a79a31827cb40 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/kubernetes.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ee90bee421152f651b12bfc81f5b0105 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Ray">
    <a href="/integrations/prefect-ray">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/ray.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=b62adc72933c62831a0951b9f8afa48e" noZoom alt="prefect-ray" data-og-width="400" width="400" data-og-height="400" height="400" data-path="images/integrations/ray.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/ray.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=67443de2a244510388d49fe109578628 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/ray.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=74ff81fec2fbd12318432d12c909f683 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/ray.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=de83b453bd22f7da7af0462503dc8baf 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/ray.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a0af15a06a938de93197f1f9ebe31f20 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/ray.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=46493a8586601599295b096f68822c0e 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/ray.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=183b448c48f12b1cbdbe57be29e91f6f 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Shell">
    <a href="/integrations/prefect-shell">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/shell.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=10d831beb608b7e1ee6b00d37ec13fa5" noZoom alt="prefect-shell" data-og-width="256" width="256" data-og-height="256" height="256" data-path="images/integrations/shell.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/shell.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=3867e380b7dc3dd559350ff44dfcea55 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/shell.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=8ce5208c035a345a501131ae01a19a93 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/shell.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=cc49b85d732cc3fd3a30d22520bd676e 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/shell.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=10934538e1abf6a1f52e26570e77769d 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/shell.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=e6d29338ac81fe5ed424496b7a0602a6 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/shell.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c46fa83ff54a8d7d89c1a220658289da 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Slack">
    <a href="/integrations/prefect-slack">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/slack.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ad62c575839992ccb9dfc5561973dd57" noZoom alt="prefect-slack" data-og-width="268" width="268" data-og-height="268" height="268" data-path="images/integrations/slack.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/slack.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=f02cc170490e533346e54a4fd2189deb 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/slack.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=24669dfb992c3546ee6b2b4b514f2ca6 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/slack.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=442c0b3db69de533bf143fccf796573c 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/slack.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=b0871ebe641ebc13ddb1fe41e8856947 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/slack.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=1f81a17f088974892487e2f4bb512ed2 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/slack.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=4b0962cbd2205ae926fcf8fcb56afe7f 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="Snowflake">
    <a href="/integrations/prefect-snowflake">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/snowflake.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=5625593a6969f1ed40e21008c4d6aad9" noZoom alt="prefect-snowflake" data-og-width="280" width="280" data-og-height="280" height="280" data-path="images/integrations/snowflake.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/snowflake.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=18df13d1585258c70d7d2af7c0828f1b 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/snowflake.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=20b026b5b58ff395c0bae2f5bf84accc 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/snowflake.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9d88c5f96c90dde4e7831764f62176f6 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/snowflake.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=7e0b260f01a66cabe6f9ce79d6521adb 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/snowflake.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=1c69d5f858dfedbf0a731454ff29a0d5 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/snowflake.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=aaddf692b1a7fad82736d258a4045ab0 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>

  <Card title="SQLAlchemy">
    <a href="/integrations/prefect-sqlalchemy">
      <img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/sqlalchemy.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=6586068d0dfc0256a37f32d64f98098a" noZoom alt="prefect-sqlalchemy" data-og-width="452" width="452" data-og-height="452" height="452" data-path="images/integrations/sqlalchemy.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/sqlalchemy.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=41bffe9fd56d05d106eb86db147ec526 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/sqlalchemy.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=b0db5e1a20c408b7597b052868ef2b2d 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/sqlalchemy.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=508a0cd93f95e120a1b351346b9493f1 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/sqlalchemy.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=56703da96f4116a67b412ad98f69955a 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/sqlalchemy.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=3459517d09efd060fba850e081eaca7b 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/sqlalchemy.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=207e354911c857cf386c9a23d8b0b7f3 2500w" data-optimize="true" data-opv="2" />
    </a>

    Maintained by <a href="https://prefect.io"> Prefect </a>
  </Card>
</CardGroup>


# Get to know the ECS worker
Source: https://docs-3.prefect.io/integrations/prefect-aws/ecs-worker/index

Deploy production-ready Prefect workers on AWS Elastic Container Service (ECS) for scalable, containerized flow execution. ECS workers provide robust infrastructure management with automatic scaling, high availability, and seamless AWS integration.

## Why use ECS for flow run execution?

ECS (Elastic Container Service) is an excellent choice for executing Prefect flow runs in production environments:

* **Production-ready scalability**: ECS automatically scales your infrastructure based on demand, efficiently managing container distribution across multiple instances
* **Flexible compute options**: Choose between AWS Fargate for serverless execution or Amazon EC2 for faster job start times and additional control
* **Native AWS integration**: Seamlessly connect with AWS services like IAM, CloudWatch, Secrets Manager, and VPC networking
* **Containerized reliability**: Docker container support ensures reproducible deployments and consistent runtime environments
* **Cost optimization**: Pay only for the compute resources you use with automatic scaling and spot instance support

## Architecture Overview

ECS workers operate within your AWS infrastructure, providing secure and scalable flow execution. Prefect enables remote flow execution via workers and work pools - to learn more about these concepts see the [deployment docs](/v3/deploy/infrastructure-concepts/work-pools/).

```mermaid
%%{
  init: {
    'theme': 'neutral',
    'themeVariables': {
      'margin': '10px'
    }
  }
}%%

flowchart TB
    subgraph ecs_cluster[ECS Cluster]
        subgraph ecs_service[ECS Service]
            td_worker[Worker Task Definition] --> |defines| prefect_worker[Prefect Worker]
        end

        prefect_worker -->|kicks off| ecs_task

        fr_task_definition[Flow Run Task Definition]

        subgraph ecs_task[ECS Task Execution]
            flow_run((Flow Run))
        end

        fr_task_definition -->|defines| ecs_task
    end

    subgraph prefect_cloud[Prefect Cloud]
        work_pool[ECS Work Pool]
    end

    subgraph github[ECR]
        flow_code["Flow Code"]
    end

    flow_code --> |pulls| ecs_task
    prefect_worker -->|polls| work_pool
    work_pool -->|configures| fr_task_definition
```

### Key Components

* **ECS Worker**: Long-running service that polls work pools and manages flow run execution. Runs as an ECS Service for auto-recovery in case of failure
* **Task Definitions**: Blueprint for ECS tasks that describes which Docker containers to run and their configuration
* **ECS Cluster**: Provides the underlying compute capacity with auto-scaling capabilities
* **Work Pools**: Typed according to infrastructure - flow runs in `ecs` work pools are executed as ECS tasks
* **Flow Run Tasks**: Ephemeral ECS tasks that execute individual Prefect flows until completion

### How It Works

1. **Continuous Polling**: The ECS worker continuously polls your Prefect server or Prefect Cloud for scheduled flow runs
2. **Task Creation**: When work is available, the worker creates ECS task definitions based on work pool configuration
3. **Flow Execution**: Flow runs are launched as ECS tasks with appropriate resource allocation and configuration
4. **Auto-scaling**: ECS automatically manages container distribution and scaling based on demand
5. **Cleanup**: After flow completion, containers are cleaned up while the worker continues polling

<Tip>
  **ECS tasks ≠ Prefect tasks**

  An ECS task is **not** the same as a [Prefect task](/v3/develop/write-tasks). ECS tasks are groupings of containers that run within an ECS Cluster, defined by task definitions. They're ideal for ephemeral processes like Prefect flow runs.
</Tip>

## Deployment options

### With the `prefect-aws` CLI

The fastest way to deploy production-ready ECS workers is by using the `prefect-aws` CLI:

```bash
prefect-aws ecs-worker deploy-service \
  --work-pool-name my-ecs-pool \
  --stack-name prefect-ecs-worker \
  --existing-cluster-identifier my-ecs-cluster \
  --existing-vpc-id vpc-12345678 \
  --existing-subnet-ids subnet-12345,subnet-67890 \
  --prefect-api-url https://api.prefect.cloud/api/accounts/.../workspaces/... \
  --prefect-api-key your-api-key
```

This command creates a CloudFormation stack that provisions all the infrastructure required for a production-ready ECS worker service.

**Key benefits:**

* **One-command deployment**: Provisions complete infrastructure with a single command
* **CloudFormation managed**: Infrastructure as code with rollback capabilities
* **Auto-scaling configured**: Built-in scaling policies for production workloads
* **Monitoring included**: CloudWatch logs and alarms pre-configured
* **Production defaults**: Secure, optimized settings out of the box

**Additional CLI commands:**

* `prefect-aws ecs-worker list` - View all deployed stacks
* `prefect-aws ecs-worker status <stack-name>` - Check deployment status
* `prefect-aws ecs-worker delete <stack-name>` - Clean up infrastructure
* `prefect-aws ecs-worker export-template` - Export CloudFormation templates for customization

For detailed CLI options run `prefect-aws ecs-worker deploy-service --help`.

### Manual deployment

For users who want full control over their ECS infrastructure setup:

**[Deploy manually →](deploy_manually)**
Step-by-step guide for creating ECS clusters, task definitions, and configuring workers from scratch.

## Prerequisites

Before deploying ECS workers, ensure you have:

* **AWS Account**: Active AWS account with appropriate permissions
* **IAM Permissions**: Rights to create ECS clusters, task definitions, and IAM roles
* **Docker Knowledge**: Basic understanding of containerization concepts
* **Prefect Setup**: Active Prefect server or Prefect Cloud workspace

## Getting started

1. **Choose your deployment method**: Manual setup provides maximum flexibility, while infrastructure as code offers reproducible deployments
2. **Configure AWS credentials**: Set up IAM roles and permissions for secure AWS service access
3. **Create work pools**: Define work pool configurations that match your ECS infrastructure
4. **Deploy workers**: Launch ECS workers that will poll for and execute flow runs
5. **Monitor and scale**: Use CloudWatch and ECS metrics to optimize performance

## Next steps

* **[Manual Deployment Guide](deploy_manually)** - Complete walkthrough for setting up ECS workers step-by-step
* **[Work Pool Configuration](/v3/deploy/infrastructure-concepts/work-pools/)** - Learn about Prefect work pools and worker concepts
* **[AWS ECS Documentation](https://docs.aws.amazon.com/ecs/)** - Official AWS documentation for ECS services
* **[Prefect Cloud Push Work Pools](/v3/how-to-guides/deployment_infra/serverless)** - Serverless alternative to self-managed workers


# How to manually deploy an ECS worker to an ECS cluster
Source: https://docs-3.prefect.io/integrations/prefect-aws/ecs-worker/manual-deployment

Step-by-step guide for manually setting up ECS infrastructure to run Prefect workers with full control over cluster configuration, IAM roles, and task definitions.

<Note>
  This guide is valid for users of self-hosted Prefect server or Prefect Cloud users with a tier that allows hybrid work pools.
</Note>

This guide walks you through manually setting up ECS infrastructure to run Prefect workers. For architecture concepts and overview, see the [ECS Worker overview](/integrations/prefect-aws/ecs-worker).

## Prerequisites

You will need the following to successfully complete this guide:

* A Prefect server. You will need either:
  * [Prefect Cloud](https://app.prefect.cloud) account on Starter tier or above
  * [Prefect self-managed instance](/v3/concepts/server)
* An AWS account with permissions to create:
  * IAM roles
  * IAM policies
  * Secrets in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)
  * ECS task definitions
  * ECS services
* The AWS CLI installed on your local machine. You can [download it from the AWS website](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
* An existing [ECS Cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html)
* An existing [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) - this guide assumes the use the default VPC.

<Accordion title={"What if I don't have an ECS cluster?"} icon={"boxes-stacked"}>
  You can create an ECS cluster using the AWS CLI or the AWS Management Console.

  To create an ECS cluster using the AWS CLI, run the following command:

  ```bash wrap
  aws ecs create-cluster --cluster-name my-ecs-cluster
  ```

  <Info>
    No further configuration is required for this guide, as we will use the Fargate launch type and the default VPC.
  </Info>
</Accordion>

<Tip>
  For production deployments, it is recommended that you create your own VPC with appropriate security policies based on your organization's recommendations.

  If you want to create a new VPC for this guide, follow the [VPC creation guide](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html).
</Tip>

## Create the Prefect ECS work pool

First, create an ECS [work pool](/v3/deploy/infrastructure-concepts/work-pools/) for your deployments to use. You can do this either from the CLI or the Prefect UI.

If doing so from the CLI, be sure to [authenticate with Prefect Cloud](/v3/how-to-guides/cloud/connect-to-cloud) or run a local Prefect server instance.

<Tabs>
  <Tab title={"From the CLI"}>
    Run the following command to create a new ECS work pool named `my-ecs-pool`:

    ```bash
    prefect work-pool create --type ecs my-ecs-pool
    ```
  </Tab>

  <Tab title={"From the Web UI"}>
    1. Navigate to the **Work Pools** page in the Prefect UI.
    2. Click the `+` button to the right of the **Work Pool** page header.
    3. Select **AWS Elastic Container Service**. In Prefect Cloud, this will be under the **Hybrid** section.

    <img src={"/images/Workpool_UI.png"} alt={"Work Pool"} noZoom />
  </Tab>
</Tabs>

<Info>
  Because this guide uses Fargate as the capacity provider, this step requires no further action.
</Info>

## Create a Secret for the Prefect API key

<Info>
  If you are using a Prefect self-hosted server and have authentication disabled, you can skip this step.
</Info>

The Prefect worker needs to authenticate with your Prefect server to poll the work pool for flow runs. For authentication, you must provide a Bearer token (`PREFECT_API_KEY`) or Basic Auth string (`PREFECT_API_AUTH_STRING`) to the Prefect API. As a security best practice, we recommend you store your Prefect API key in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html).

<Steps>
  <Step title={"Find your secret"}>
    You can find your Prefect API key several ways:

    <AccordionGroup>
      <Accordion title={"Prefect Cloud - Paid Plans"}>
        If you are on a paid plan you can create a [service account](/v3/how-to-guides/cloud/manage-users/service-accounts) for the worker.
      </Accordion>

      <Accordion title={"Prefect Cloud - Free Plans"}>
        If you are on a free plan, you can use a user's API key.

        To find your API key, use the Prefect CLI:

        ```bash wrap
        # If not already authenticated, log in first
        prefect cloud login

        prefect config view --show-secrets
        ```
      </Accordion>

      <Accordion title={"Self-hosted Prefect server"}>
        There is no concept of a `PREFECT_API_KEY` in a self-hosted Prefect server.

        Instead, you use the `PREFECT_API_AUTH_STRING` containing your basic auth credentials (if your server uses [basic authentication](/v3/advanced/security-settings#basic-authentication)).

        You can find this information on the Settings page for your Prefect server.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title={"Create a secret"}>
    Choose between AWS Secrets Manager or Systems Manager Parameter Store to store your Prefect API key. Both services allow you to securely store and manage sensitive information such as API keys, passwords, and other secrets.

    <Tabs>
      <Tab title={"Secrets Manager"}>
        To create a Secret in AWS Secrets Manager, use the [`aws secretsmanager create-secret`](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/create-secret.html) command:

        ```bash wrap
        aws secretsmanager create-secret --name PrefectECSWorkerAPIKey --secret-string '<your-prefect-api-key>'
        ```

        Make a note of the Amazon Resource Name (ARN) of the secret that is returned in the command output. You will need it later when configuring the ECS worker task definition.
      </Tab>

      <Tab title={"Systems Manager Parameter Store"}>
        To create a SecureString parameter in AWS Systems Manager Parameter Store, use the [`aws ssm put-parameter`](https://docs.aws.amazon.com/cli/latest/reference/ssm/put-parameter.html) command:

        ```bash wrap
        aws ssm put-parameter --name "/prefect/my-ecs-pool/api/key" --value "<your-prefect-api-key>" --type "SecureString"
        ```

        You may customize the parameter hierarchy and name to suit your needs. In this example we've used, `/prefect/my-ecs-pool/api/key` but any parameter name works. Your ECS task execution role will need to be able to read this value.

        Make a note of the name you specified for the parameter, as you will need it later when configuring the ECS worker.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Create the AWS IAM resources

We will create two [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html#roles-creatingrole-custom-trust-policy-console):

1. `ecsTaskExecutionRole`: This role will be used by ECS to start ECS tasks.
2. `ecsTaskRole`: This role will contain the permissions required by Prefect ECS worker in order to run your flows as ECS tasks.

The role permissions are based on the principle of [least-privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started-reduce-permissions.html), meaning that each role will only have the permissions it needs to perform its job.

### Create a trust policy

The trust policy will allow the ECS service containing the Prefect worker to assume the role required for calling other AWS services. This is called a [service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create-service-linked-role.html). The trust policy is a JSON document that specifies which AWS service can assume the role.

Save this policy to a file, such as `trust-policy.json`:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ecs-tasks.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

Alternately, you can download this file using the following command:

<CodeGroup>
  ```bash curl wrap
  curl -O https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/trust-policy.json
  ```

  ```bash wget wrap
  wget https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/trust-policy.json
  ```
</CodeGroup>

### Create the IAM roles

Now, we will create the IAM roles that will be used by the ECS worker.

#### Create the ECS task execution role

The ECS task execution role will be used to start the ECS worker task. We will assign it a minimal set of permissions to allow the worker to pull images from ECR and publish logs to CloudWatch.

<Steps>
  <Step title={"Create the role"}>
    Create the role using the [`aws iam create-role`](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command:

    ```bash wrap
    aws iam create-role --role-name ecsTaskExecutionRole --assume-role-policy-document file://trust-policy.json
    ```

    Make a note of the ARN (Amazon Resource Name) of the role that is returned in the command output. You will need it later when creating the ECS task definition.
  </Step>

  <Step title={"Create the Secret Policy"}>
    <Tabs>
      <Tab title={"Secrets Manager"}>
        The following is a minimal policy that grants the necessary permissions for ECS to obtain the current value of the secret and inject it into the ECS task. Save this policy to a file, such as `secret-policy.json`:

        ```json
        {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Action": [
                        "secretsmanager:GetSecretValue",
                    ],
                    "Effect": "Allow",
                    "Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:PrefectECSWorkerAPIKey"
                }
            ]
        }
        ```

        Alternately, you can download this file using the following command:

        <CodeGroup>
          ```bash curl wrap
          curl -O https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/secrets/secrets-manager/secret-policy.json
          ```

          ```bash wget wrap
          wget https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/secrets/secrets-manager/secret-policy.json
          ```
        </CodeGroup>
      </Tab>

      <Tab title={"Systems Manager Parameter Store"}>
        The following is a minimal policy that grants the necessary permissions for ECS to obtain the current value of the parameter and inject it into the ECS task. Save this policy to a file, such as `secret-policy.json`:

        ```json
        {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Action": [
                        "ssm:GetParameters"
                    ],
                    "Effect": "Allow",
                    "Resource": "arn:aws:ssm:<region>:<account-id>:parameter/prefect/my-ecs-pool/api/key"
                }
            ]
        }
        ```

        Alternately, you can download this file using the following command:

        <CodeGroup>
          ```bash curl wrap
          curl -O https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/secrets/ssm-parameter-store/secret-policy.json
          ```

          ```bash wget wrap
          wget https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/secrets/ssm-parameter-store/secret-policy.json
          ```
        </CodeGroup>
      </Tab>
    </Tabs>

    <Accordion title={"Using a customer-managed key (CMK)?"} icon={"lock"}>
      If your secret is encrypted with a customer-managed key (CMK) in AWS Key Management Service (KMS), you will also need to add the `kms:Decrypt` permission to the policy. For example:

      ```json focus={11-17}
      {
        "Version": "2012-10-17",
        "Statement": [
          {
              "Action": [
                  "secretsmanager:GetSecretValue",
              ],
              "Effect": "Allow",
              "Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:PrefectECSWorkerAPIKey"
          },
          {
             "Action": [
                  "kms:Decrypt"
              ],
              "Effect": "Allow",
              "Resource": "arn:aws:kms:<region>:<account-id>:key/<your-kms-key-id>"
          }
        ]
      }
      ```
    </Accordion>
  </Step>

  <Step title={"Register the policy"}>
    Create a new IAM policy named `ecsTaskExecutionPolicy` using the policy document you just created.

    ```bash wrap
    aws iam create-policy --policy-name ecsTaskExecutionPolicy --policy-document file://secret-policy.json
    ```
  </Step>

  <Step title={"Attach the Policies"}>
    The `AmazonECSTaskExecutionRolePolicy` managed policy grants the minimum permissions necessary for starting ECS tasks. [See here](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html) for other common execution role permissions.

    Attach this policy to your task execution role using the [`aws iam attach-role-policy`](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html):

    ```bash wrap
    aws iam attach-role-policy --role-name ecsTaskExecutionRole --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
    ```

    Attach the custom policy you created in the previous step so that the ECS task can access the Prefect API key stored in AWS Secrets Manager or Systems Manager Parameter Store:

    ```bash wrap
    aws iam put-role-policy --role-name ecsTaskExecutionRole --policy-name PrefectECSWorkerSecretPolicy --policy-document file://secret-policy.json
    ```
  </Step>
</Steps>

#### Create the worker ECS task role

The worker ECS task role will be used by the Prefect worker to interact with the AWS API to run flows as ECS containers. This role will require the ability to describe, register, and deregister ECS task definitions, as well as the ability to start and stop ECS tasks.

<Steps>
  <Step title={"Create the role"}>
    Use the following command to create the role. The same trust policy is also used for this role.

    ```bash wrap
    aws iam create-role --role-name ecsTaskRole --assume-role-policy-document file://trust-policy.json
    ```
  </Step>

  <Step title={"Create the task policy"}>
    The following is a minimal policy that grants the necessary permissions for the Prefect ECS worker to run your flows as ECS tasks. Save this policy to a file, such as `worker-policy.json`:

    ```json
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Action": [
            "ec2:DescribeSubnets",
            "ec2:DescribeVpcs",
            "ecs:DeregisterTaskDefinition",
            "ecs:DescribeTaskDefinition",
            "ecs:DescribeTasks",
            "ecs:RegisterTaskDefinition",
            "ecs:RunTask",
            "ecs:StopTask",
            "ecs:TagResource",
            "iam:PassRole",
            "logs:GetLogEvents",
            "logs:PutLogEvents"
          ],
          "Effect": "Allow",
          "Resource": "*"
        }
      ]
    }
    ```

    Alternately, you can download this file using the following command:

    <CodeGroup>
      ```bash curl wrap
      curl -O https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/worker-policy.json
      ```

      ```bash wget wrap
      wget https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/worker-policy.json
      ```
    </CodeGroup>
  </Step>

  <Step title={"Register the policy"}>
    Create a new IAM policy named `ecsTaskPolicy` using the policy document you just created.

    ```bash wrap
    aws iam create-policy --policy-name ecsTaskPolicy --policy-document file://worker-policy.json
    ```
  </Step>

  <Step title={"Attach policy to the role"}>
    Attach the custom `ecsTaskPolicy` to the `ecsTaskRole` so that the Prefect worker can dispatch flows to ECS:

    ```bash wrap
    aws iam attach-role-policy --role-name ecsTaskRole --policy-arn arn:aws:iam::<your-account-id>:policy/ecsTaskPolicy
    ```

    Replace `<your-account-id>` with your AWS account ID.
  </Step>
</Steps>

#### Create an ECS task role for Prefect flows

<Tip>
  This step is optional, but recommended if your flows require access to other AWS services.
</Tip>

Depending on the requirements of your flows, it is advised to create a [separate role for your ECS tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html). This role will contain the permissions required by the ECS tasks in which your flows will run. For example, if your workflow loads data into an S3 bucket, you would need a role with additional permissions to access S3.

<Accordion title={"Create flow run IAM role"} icon={"lock"}>
  <Steps>
    <Step title={"Create the role"}>
      Use the following command to create the role:

      ```bash wrap
      aws iam create-role --role-name PrefectECSRunnerTaskRole --assume-role-policy-document file://trust-policy.json
      ```
    </Step>

    <Step title={"Create the task policy"}>
      The following is an example policy that allows reading/writing to an S3 bucket named `prefect-demo-bucket`. Save this policy to a file, such as `runner-task-policy.json`:

      ```json
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "s3:ListBucket",
              "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::prefect-demo-bucket"
          },
          {
            "Effect": "Allow",
            "Action": [
              "s3:PutObject",
              "s3:PutObjectAcl",
              "s3:GetObject",
              "s3:GetObjectAcl",
              "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::prefect-demo-bucket/*"
          }
        ]
      }
      ```
    </Step>

    <Step title={"Register the policy"}>
      Create a new IAM policy named `PrefectECSRunnerTaskPolicy` using the policy document you just created:

      ```bash wrap
      aws iam create-policy --policy-name PrefectECSRunnerTaskPolicy --policy-document file://runner-task-policy.json
      ```
    </Step>

    <Step title={"Attach policy to the role"}>
      Attach the new `PrefectECSRunnerTaskPolicy` IAM policy to the `PrefectECSRunnerTaskRole` IAM role:

      ```bash wrap
      aws iam attach-role-policy --role-name PrefectECSRunnerTaskRole --policy-arn arn:aws:iam::<your-account-id>:policy/PrefectECSRunnerTaskPolicy
      ```

      Replace `<your-account-id>` with your AWS account ID.
    </Step>

    <Step title={"Add Task Role ARN to the work pool"}>
      Finally, add the ARN of the `PrefectECSRunnerTaskRole` to your ECS work pool.

      This can be configured two ways:

      1. Globally for all flows in the work pool by setting the **Task Role ARN (Optional)** field in the work pool configuration.
      2. On a per-deployment basis by specifying the `task_role_arn` job variable in the deployment configuration.
    </Step>
  </Steps>
</Accordion>

## Configure event monitoring infrastructure

To enable the ECS worker to monitor and update the status of flow runs, we need to set up SQS queues and EventBridge rules that capture ECS task state changes. This infrastructure allows the worker to:

* Track when ECS tasks (flow runs) start, stop, or fail
* Update flow run states in real-time based on ECS task events
* Provide better observability and status reporting for your workflows

<Info>
  This step sets up the same event monitoring infrastructure that the `prefect-aws ecs-worker deploy-events` command creates automatically. The worker will use the environment variable `PREFECT_INTEGRATIONS_AWS_ECS_OBSERVER_SQS_QUEUE_NAME` to discover and read from the events queue.
</Info>

<Steps>
  <Step title={"Create SQS queues for event monitoring"}>
    Create an SQS queue to receive ECS task state change events and a dead-letter queue for handling failed messages.

    First, create the dead-letter queue:

    ```bash
    aws sqs create-queue --queue-name my-ecs-pool-events-dlq --attributes MessageRetentionPeriod=1209600,VisibilityTimeout=60
    ```

    Get the ARN of the dead-letter queue:

    ```bash
    aws sqs get-queue-attributes --queue-url $(aws sqs get-queue-url --queue-name my-ecs-pool-events-dlq --query 'QueueUrl' --output text) --attribute-names QueueArn --query 'Attributes.QueueArn' --output text
    ```

    Now create the main queue with the dead-letter queue configured:

    ```bash
    aws sqs create-queue \
      --queue-name my-ecs-pool-events \
      --attributes '{
        "MessageRetentionPeriod": "604800",
        "VisibilityTimeout": "300",
        "RedrivePolicy": "{\"deadLetterTargetArn\":\"<dlq-arn>\",\"maxReceiveCount\":3}"
      }'
    ```

    Replace `<dlq-arn>` with the ARN of the dead-letter queue from the previous step, and `my-ecs-pool` with your work pool name.

    <Info>
      The queue name should follow the pattern `{work-pool-name}-events` for consistency with the automated deployment.
    </Info>
  </Step>

  <Step title={"Configure SQS queue policy"}>
    Allow EventBridge to send messages to your SQS queue by updating the queue policy:

    ```bash
    aws sqs set-queue-attributes \
      --queue-url $(aws sqs get-queue-url --queue-name my-ecs-pool-events --query 'QueueUrl' --output text) \
      --attributes '{"Policy":"{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"events.amazonaws.com\"},\"Action\":[\"sqs:SendMessage\",\"sqs:GetQueueAttributes\",\"sqs:GetQueueUrl\"],\"Resource\":\"<queue-arn>\"}]}"}'
    ```

    Replace `<queue-arn>` with the ARN of the queue created in the previous step.
  </Step>

  <Step title={"Create EventBridge rule for ECS task state changes"}>
    Create an EventBridge rule to capture ECS task state changes and send them to the SQS queue:

    ```bash wrap
    aws events put-rule \
      --name my-ecs-pool-task-state-changes \
      --event-pattern '{
        "source": ["aws.ecs"],
        "detail-type": ["ECS Task State Change"],
        "detail": {
          "clusterArn": ["arn:aws:ecs:<region>:<account-id>:cluster/<cluster-name>"]
        }
      }' \
      --description "Capture ECS task state changes for Prefect worker" \
      --state ENABLED
    ```

    Replace:

    * `<region>` with your AWS region
    * `<account-id>` with your AWS account ID
    * `<cluster-name>` with your ECS cluster name
    * `my-ecs-pool` with your work pool name

    <Accordion title={"Finding your cluster ARN"} icon={"circle-question"}>
      You can find your cluster ARN using:

      ```bash wrap
      aws ecs describe-clusters --clusters <cluster-name> --query 'clusters[0].clusterArn' --output text
      ```
    </Accordion>
  </Step>

  <Step title={"Add SQS queue as EventBridge rule target"}>
    Get the queue ARN and add it as a target for the EventBridge rule:

    ```bash
    aws events put-targets \
      --rule my-ecs-pool-task-state-changes \
      --targets "Id=1,Arn=<queue-arn>"
    ```

    Replace `<queue-arn>` with the ARN of the queue created in step 1.
  </Step>

  <Step title={"Update worker task role with SQS permissions"}>
    Add SQS permissions to the worker task role created earlier:

    Create a file named `sqs-policy.json`:

    ```json wrap
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "sqs:ReceiveMessage",
                    "sqs:DeleteMessage",
                    "sqs:GetQueueAttributes",
                    "sqs:GetQueueUrl",
                    "sqs:ChangeMessageVisibility"
                ],
                "Resource": "arn:aws:sqs:<region>:<account-id>:my-ecs-pool-events"
            }
        ]
    }
    ```

    Replace `<region>`, `<account-id>`, and `my-ecs-pool-events` with your values.

    Apply the policy to the worker task role:

    ```bash wrap
    aws iam put-role-policy \
      --role-name ecsTaskRole \
      --policy-name EcsWorkerSqsPolicy \
      --policy-document file://sqs-policy.json
    ```
  </Step>
</Steps>

## Creating the ECS worker service

Now that all the AWS IAM roles and event monitoring infrastructure have been created, we can deploy the Prefect worker to the ECS cluster.

<Steps>
  <Step title={"Create the task definition"}>
    This task definition will be used to run the Prefect worker in an ECS task.

    Ensure you replace the placeholders for:

    * `<ecs-task-execution-role-arn>` with the ARN of the `ecsTaskExecutionRole` you created in Step 2.

    <Accordion title={"Finding your ECS Task Execution Role ARN"} icon={"circle-question"}>
      You can find the ARN of the `ecsTaskExecutionRole` using the following command:

      ```bash wrap
      aws iam get-role --role-name ecsTaskExecutionRole --query 'Role.Arn' --output text
      ```
    </Accordion>

    * `<ecs-task-role-arn>` with the ARN of the `ecsTaskRole` you created in Step 2.

    <Accordion title={"Finding your ECS Task Role ARN"} icon={"circle-question"}>
      You can find the ARN of the `ecsTaskRole` using the following command:

      ```bash wrap
      aws iam get-role --role-name ecsTaskRole --query 'Role.Arn' --output text
      ```
    </Accordion>

    * `<prefect-api-url>` with the URL of your Prefect Server.

    <Accordion title={"Finding your PREFECT_API_URL"} icon={"circle-question"}>
      You can find your Prefect API URL several ways:

      <AccordionGroup>
        <Accordion title={"Using the CLI"}>
          If you have the Prefect CLI installed, you can run the following command to view your current Prefect profile's API URL:

          ```bash
          prefect config view
          ```
        </Accordion>

        <Accordion title={"For Prefect Cloud"}>
          To manually construct the Prefect Cloud API URL, use the following format:

          ```text wrap
          https://api.prefect.cloud/api/accounts/<account-id>/workspaces/<workspace-id>
          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    * `<aws-arn-of-secret>` with the ARN of the resource from Secrets Manager or Systems Manager Parameter Store.
    * `my-ecs-pool-events` in the `PREFECT_INTEGRATIONS_AWS_ECS_OBSERVER_SQS_QUEUE_NAME` environment variable with your actual queue name from the event monitoring setup.

    <Accordion title={"Finding your Secret ARN"} icon={"circle-question"}>
      Your secret ARN is based on the service you are using:

      <AccordionGroup>
        <Accordion title={"Secrets Manager"}>
          You can find the ARN of your secret using the following command:

          ```bash wrap
          aws secretsmanager describe-secret --secret-id PrefectECSWorkerAPIKey --query 'ARN' --output text
          ```
        </Accordion>

        <Accordion title={"Systems Manager Parameter Store"}>
          You can find the ARN of your parameter using the following command:

          ```bash wrap
          aws ssm get-parameter --name "/prefect/my-ecs-pool/api/key" --query 'Parameter.ARN' --output text
          ```
        </Accordion>

        <Accordion title={"Self-hosted Prefect server"}>
          As `PREFECT_API_KEY` is not used with a self-hosted Prefect server, you will need to replace the `PREFECT_API_KEY` environment variable in the task definition secrets with `PREFECT_API_AUTH_STRING`.

          ```json focus={28-35}
          {
              "family": "prefect-worker-task",
              "networkMode": "awsvpc",
              "requiresCompatibilities": [
                  "FARGATE"
              ],
              "cpu": "512",
              "memory": "1024",
              "executionRoleArn": "<ecs-task-execution-role-arn>",
              "taskRoleArn": "<ecs-task-role-arn>",
              "containerDefinitions": [
                  {
                      "name": "prefect-worker",
                      "image": "prefecthq/prefect:3-latest",
                      "cpu": 512,
                      "memory": 1024,
                      "essential": true,
                      "command": [
                          "/bin/sh",
                          "-c",
                          "pip install prefect-aws && prefect worker start --pool my-ecs-pool --type ecs"
                      ],
                      "environment": [
                          {
                              "name": "PREFECT_API_URL",
                              "value": "<prefect-api-url>"
                          },
                          {
                              "name": "PREFECT_INTEGRATIONS_AWS_ECS_OBSERVER_SQS_QUEUE_NAME",
                              "value": "my-ecs-pool-events"
                          }
                      ],
                      "secrets": [
                          {
                              "name": "PREFECT_API_KEY", // [!code --]
                              "name": "PREFECT_API_AUTH_STRING", // [!code ++]
                              "value": "<aws-arn-of-secret>"
                          }
                      ]
                  }
              ]
          }
          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    Save the following JSON to a file named `task-definition.json`:

    ```json wrap
    {
        "family": "prefect-worker-task",
        "networkMode": "awsvpc",
        "requiresCompatibilities": [
            "FARGATE"
        ],
        "cpu": "512",
        "memory": "1024",
        "executionRoleArn": "<ecs-task-execution-role-arn>",
        "taskRoleArn": "<ecs-task-role-arn>",
        "containerDefinitions": [
            {
                "name": "prefect-worker",
                "image": "prefecthq/prefect:3-latest",
                "cpu": 512,
                "memory": 1024,
                "essential": true,
                "command": [
                    "/bin/sh",
                    "-c",
                    "pip install prefect-aws && prefect worker start --pool my-ecs-pool --type ecs"
                ],
                "environment": [
                    {
                        "name": "PREFECT_API_URL",
                        "value": "<prefect-api-url>"
                    },
                    {
                        "name": "PREFECT_INTEGRATIONS_AWS_ECS_OBSERVER_SQS_QUEUE_NAME",
                        "value": "my-ecs-pool-events"
                    }
                ],
                "secrets": [
                    {
                        "name": "PREFECT_API_KEY",
                        "valueFrom": "<aws-arn-of-secret>"
                    }
                ]
            }
        ]
    }
    ```

    Alternately, you can download this file using the following command:

    <CodeGroup>
      ```bash curl wrap
      curl -O https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/task-definition.json
      ```

      ```bash wget wrap
      wget https://raw.githubusercontent.com/PrefectHQ/prefect/refs/heads/main/docs/integrations/prefect-aws/ecs/iam/task-definition.json
      ```
    </CodeGroup>

    <Note>
      Notice that the CPU and Memory allocations are relatively small. The worker's main responsibility is to submit work through API calls to AWS, *not* to execute your Prefect flow code.
    </Note>

    <Tip>
      To avoid hardcoding your API key into the task definition JSON see [how to add sensitive data using AWS secrets manager to the container definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-tutorial.html#specifying-sensitive-data-tutorial-create-taskdef).
    </Tip>
  </Step>

  <Step title={"Register task definition"}>
    Before creating a service, you first need to register a task definition. You can do that using the [`register-task-definition` command](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html):

    ```bash wrap
    aws ecs register-task-definition --cli-input-json file://task-definition.json
    ```

    Replace `task-definition.json` with the name of your task definition file.
  </Step>

  <Step title={"Create the ECS service"}>
    Finally, create a service that will manage your Prefect worker.

    Ensure you replace the placeholders for:

    * `<ecs-cluster>` with the name of your ECS cluster.
    * `<task-definition-arn>` with the ARN of the task definition you just registered.
    * `<subnet-ids>` with a comma-separated list of your VPC subnet IDs.
    * Replace `<security-group-ids>` with a comma-separated list of your VPC security group IDs.

    <Accordion title="Get default VPC info" icon={"circle-question"}>
      If you are using the default VPC, you will need to gather some information about it to use in the next steps.

      We will use the default VPC for this guide. To find the default VPC ID, run the following command:

      ```bash wrap
      aws ec2 describe-vpcs --filters "Name=isDefault,Values=true" --query "Vpcs[0].VpcId" --output text
      ```

      This will output the VPC ID (e.g. `vpc-abcdef01`) of the default VPC, which you can use in the next steps in this section.

      To find the subnets associated with the default VPC:

      ```bash wrap
      aws ec2 describe-subnets --filters "Name=vpc-id,Values=<vpc-id>" --query "Subnets[*].SubnetId" --output text
      ```

      Which will output a list of available subnets (e.g. `subnet-12345678 subnet-23456789`).

      Finally, we will need the security group ID for the default VPC:

      ```bash wrap
      aws ec2 describe-security-groups --filters "Name=vpc-id,Values=<vpc-id>" "Name=group-name,Values=default" --query "SecurityGroups[*].GroupId" --output text
      ```

      This will output the security group ID (e.g. `sg-12345678`) of the default security group.

      Copy the subnet IDs and security group ID for use in Step 3.
    </Accordion>

    Use the [`aws ecs create-service`](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html) command to create an ECS service running on Fargate for the Prefect worker:

    ```bash wrap
    aws ecs create-service --service-name prefect-worker-service --cluster <ecs-cluster> --task-definition <task-definition-arn> --launch-type FARGATE --desired-count 1 --network-configuration "awsvpcConfiguration={subnets=[<subnet-ids>],securityGroups=[<security-group-ids>],assignPublicIp='ENABLED'}"
    ```
  </Step>

  <Step title={"Verify the Prefect worker is running"}>
    The work pool page in the Prefect UI allows you to check the health of your workers - make sure your new worker is live!

    <Info>
      It may take a few minutes for the worker to come online after creating the service.
    </Info>

    Refer to the [troubleshooting](#troubleshooting) section for further assistance if the worker isn't online.
  </Step>
</Steps>

## Configure work pool defaults

Now that your infrastructure is deployed, you should update your ECS work pool configuration with the resource identifiers so they don't need to be specified on every deployment.

<Steps>
  <Step title={"Update work pool via the UI"}>
    Navigate to your work pool in the Prefect UI and update the following fields in the **Infrastructure** tab:

    * **Cluster ARN**: Set to your ECS cluster ARN (e.g., `arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster`)
    * **VPC ID**: Set to your VPC ID (e.g., `vpc-12345678`)
    * **Subnets**: Add your subnet IDs (e.g., `subnet-12345678,subnet-87654321`)
    * **Execution Role ARN**: Set to the task execution role ARN (e.g., `arn:aws:iam::123456789012:role/ecsTaskExecutionRole`)

    These settings will be used as defaults for all deployments using this work pool, but can be overridden per deployment if needed.
  </Step>

  <Step title={"Alternative: Update work pool via API"}>
    You can also update the work pool configuration programmatically using the Prefect API:

    ```python
    from prefect.client.schemas.objects import WorkPoolUpdate
    from prefect import get_client

    async def update_work_pool():
        async with get_client() as client:
            work_pool = await client.read_work_pool("my-ecs-pool")

            # Update base job template variables
            base_template = work_pool.base_job_template
            variables = base_template.get("variables", {})
            properties = variables.get("properties", {})

            # Update infrastructure defaults
            properties["cluster"] = {
                "default": "arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster"
            }
            properties["vpc_id"] = {
                "default": "vpc-12345678"
            }
            properties["execution_role_arn"] = {
                "default": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
            }

            # Update network configuration
            network_config = properties.setdefault("network_configuration", {})
            network_props = network_config.setdefault("properties", {})
            awsvpc_config = network_props.setdefault("awsvpcConfiguration", {})
            awsvpc_props = awsvpc_config.setdefault("properties", {})
            awsvpc_props["subnets"] = {
                "default": ["subnet-12345678", "subnet-87654321"]
            }

            # Update work pool
            variables["properties"] = properties
            base_template["variables"] = variables

            await client.update_work_pool(
                "my-ecs-pool",
                WorkPoolUpdate(base_job_template=base_template)
            )

    # Run the update
    import asyncio
    asyncio.run(update_work_pool())
    ```

    Replace the ARNs and IDs with your actual resource identifiers.
  </Step>
</Steps>

## Deploy a flow run to your ECS work pool

This guide uses the [AWS Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/) to store a Docker image containing your flow code. To do this, we will write a flow, then deploy it using build and push steps that copy flow code into a Docker image and push that image to an ECR repository.

<Steps>
  <Step title={"Write a simple test flow"}>
    ```python my_flow.py lines icon="python"
    from prefect import flow
    from prefect.logging import get_run_logger

    @flow
    def my_flow():
        logger = get_run_logger()
        logger.info("Hello from ECS!!")

    if __name__ == "__main__":
        my_flow()
    ```
  </Step>

  <Step title={"Create an ECR repository"}>
    Use the [`aws ecr create-repository`](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) command to create an ECR repository. The name you choose for your repository will be reused in the next step when defining your Prefect deployment.

    ```bash wrap
    aws ecr create-repository --repository-name <my-ecr-repo>
    ```
  </Step>

  <Step title={"Create a `prefect.yaml` file"}>
    To have Prefect build your image when deploying your flow create a `prefect.yaml` file with the following specification:

    ```yaml prefect.yaml lines
    name: ecs-worker-guide

    pull:
    - prefect.deployments.steps.set_working_directory:
        directory: /opt/prefect/ecs-worker-guide

    # build section allows you to manage and build docker images
    build:
    - prefect_docker.deployments.steps.build_docker_image:
        id: build_image
        requires: prefect-docker>=0.3.1
        image_name: <my-ecr-repo>
        tag: latest
        dockerfile: auto

    # push section allows you to manage if and how this project is uploaded to remote locations
    push:
    - prefect_docker.deployments.steps.push_docker_image:
        requires: prefect-docker>=0.3.1
        image_name: '{{ build_image.image_name }}'
        tag: '{{ build_image.tag }}'

     # the deployments section allows you to provide configuration for deploying flows
    deployments:
    - name: my_ecs_deployment
        version:
        tags: []
        description:
        entrypoint: flow.py:my_flow
        parameters: {}
        work_pool:
          name: my-ecs-pool
          work_queue_name:
          job_variables:
            image: '{{ build_image.image }}'
        schedules: []
    ```
  </Step>

  <Step title={"Deploy the flow"}>
    [Deploy](https://docs.prefect.io/deploy/serve-flows/#create-a-deployment) the flow to the Prefect Cloud or your self-managed server instance.

    ```bash
    prefect deploy my_flow.py:my_ecs_deployment
    ```
  </Step>

  <Step title={"Run!"}>
    Find the deployment in the UI and click the **Quick Run** button!
  </Step>
</Steps>

## Troubleshooting

If your worker does not appear in the Prefect UI, check the following:

* Ensure that the ECS service is running and that the task definition is registered correctly.
* Check the ECS service logs in CloudWatch to see if there are any errors.
* Verify that the IAM roles have the correct permissions.
* Ensure that the `PREFECT_API_URL` and `PREFECT_API_KEY` environment variables are set correctly in the task definition.
* For self-hosted Prefect servers, ensure that you replaced `PREFECT_API_KEY` from the example with `PREFECT_API_AUTH_STRING` in the task definition.
* Ensure your Prefect ECS worker has network connectivity to the Prefect API. If you are using a private VPC, ensure that there is a NAT gateway or internet gateway configured to allow outbound traffic to the Prefect API.

### Event monitoring issues

If flow runs are not updating their status properly, check the event monitoring setup:

* Verify the SQS queue was created and is receiving messages from EventBridge
* Check that the EventBridge rule is active and properly configured for your ECS cluster
* Ensure the worker task role has the necessary SQS permissions (`sqs:ReceiveMessage`, `sqs:DeleteMessage`, etc.)
* Verify the `PREFECT_INTEGRATIONS_AWS_ECS_OBSERVER_SQS_QUEUE_NAME` environment variable is set correctly in the worker task definition
* Check CloudWatch logs for any SQS-related errors in the worker logs

## Next steps

Now that you are confident your ECS worker is healthy, you can experiment with different work pool configurations.

* Do your flow runs require higher `CPU`?
* Would an EC2 `Launch Type` speed up your flow run execution?

These infrastructure configuration values can be set on your ECS work pool or they can be overridden on the deployment level through [job\_variables](/v3/deploy/infrastructure-concepts/customize/) if desired.


# prefect-aws
Source: https://docs-3.prefect.io/integrations/prefect-aws/index

Build production-ready data workflows that seamlessly integrate with AWS services. `prefect-aws` provides battle-tested blocks, tasks, and infrastructure integrations for AWS, including ECS orchestration, S3 storage, Secrets Manager, Lambda functions, Batch computing, and Glue ETL operations.

## Why use prefect-aws?

`prefect-aws` offers significant advantages over direct boto3 integration:

* **Production-ready integrations**: Pre-built, tested components that handle common AWS patterns and edge cases
* **Unified credential management**: Secure, centralized authentication that works consistently across all AWS services
* **Built-in observability**: Automatic logging, monitoring, and state tracking for all AWS operations
* **Infrastructure as code**: Deploy and scale workflows on AWS ECS with minimal configuration

## Getting started

### Prerequisites

* An [AWS account](https://aws.amazon.com/account/) and the necessary permissions to access desired services.

### Install prefect-aws

The following command will install a version of `prefect-aws` compatible with your installed version of `prefect`. If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[aws]"
```

Upgrade to the latest versions of `prefect` and `prefect-aws`:

```bash
pip install -U "prefect[aws]"
```

## Blocks setup

### Credentials

Most AWS services requires an authenticated session.
Prefect makes it simple to provide credentials via AWS Credentials blocks.

Steps:

1. Refer to the [AWS Configuration documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds) to retrieve your access key ID and secret access key.
2. Copy the access key ID and secret access key.
3. Create an `AwsCredentials` block in the Prefect UI or use a Python script like the one below.

```python
from prefect_aws import AwsCredentials


AwsCredentials(
    aws_access_key_id="PLACEHOLDER",
    aws_secret_access_key="PLACEHOLDER",
    aws_session_token=None,  # replace this with token if necessary
    region_name="us-east-2"
).save("BLOCK-NAME-PLACEHOLDER")
```

Prefect uses the Boto3 library under the hood.
To find credentials for authentication, any data not provided to the block are sourced at runtime in the order shown in the [Boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials).
Prefect creates the session object using the values in the block and then, any missing values follow the sequence in the Boto3 docs.

### S3

Create a block for reading and writing files to S3.

```python
from prefect_aws import AwsCredentials
from prefect_aws.s3 import S3Bucket

S3Bucket(
    bucket_name="BUCKET-NAME-PLACEHOLDER",
    credentials=aws_credentials
).save("S3-BLOCK-NAME-PLACEHOLDER")
```

### Lambda

Invoke AWS Lambdas, synchronously or asynchronously.

```python
from prefect_aws.lambda_function import LambdaFunction
from prefect_aws.credentials import AwsCredentials

LambdaFunction(
    function_name="test_lambda_function",
    aws_credentials=credentials,
).save("LAMBDA-BLOCK-NAME-PLACEHOLDER")
```

### Secret Manager

Create a block to read, write, and delete AWS Secret Manager secrets.

```python
from prefect_aws import AwsCredentials
from prefect_aws.secrets_manager import AwsSecret

AwsSecret(
    secret_name="test_secret_name",
    aws_credentials=credentials,
).save("AWS-SECRET-BLOCK-NAME-PLACEHOLDER")

```

## Supported AWS services

`prefect-aws` provides comprehensive integrations for key AWS services:

| Service             | Integration Type           | Use Cases                                              |
| ------------------- | -------------------------- | ------------------------------------------------------ |
| **S3**              | `S3Bucket` block           | File storage, data lake operations, deployment storage |
| **Secrets Manager** | `AwsSecret` block          | Secure credential storage, API key management          |
| **Lambda**          | `LambdaFunction` block     | Serverless function execution, event-driven processing |
| **Glue**            | `GlueJobBlock` block       | ETL operations, data transformation pipelines          |
| **ECS**             | `ECSWorker` infrastructure | Container orchestration, scalable compute workloads    |
| **Batch**           | `batch_submit` task        | High-throughput computing, batch job processing        |

**Integration types:**

* **Blocks**: Reusable configuration objects that can be saved and shared across flows
* **Tasks**: Functions decorated with `@task` for direct use in flows
* **Workers**: Infrastructure components for running flows on AWS compute services

## Scale workflows with AWS infrastructure

### ECS (Elastic Container Service)

Deploy and scale your Prefect workflows on [AWS ECS](https://aws.amazon.com/ecs/) for production workloads. `prefect-aws` provides:

* **ECS worker**: Long-running worker for hybrid deployments with full control over execution environment
* **Auto-scaling**: Dynamic resource allocation based on workflow demands
* **Cost optimization**: Pay only for compute resources when workflows are running

See the [ECS worker deployment guide](/integrations/prefect-aws/ecs_guide) for a step-by-step walkthrough of deploying production-ready workers to your ECS cluster.

### Docker Images

Pre-built Docker images with `prefect-aws` are available for simplified deployment:

```bash
docker pull prefecthq/prefect-aws:latest
```

#### Available Tags

Image tags have the following format:

* `prefecthq/prefect-aws:latest` - Latest stable release with Python 3.12
* `prefecthq/prefect-aws:latest-python3.11` - Latest stable with Python 3.11
* `prefecthq/prefect-aws:0.5.9-python3.12` - Specific prefect-aws version with Python 3.12
* `prefecthq/prefect-aws:0.5.9-python3.12-prefect3.4.9` - Full version specification

#### Usage Examples

**Running an ECS worker:**

```bash
docker run -d \
  --name prefect-ecs-worker \
  -e PREFECT_API_URL=https://api.prefect.cloud/api/accounts/your-account/workspaces/your-workspace \
  -e PREFECT_API_KEY=your-api-key \
  prefecthq/prefect-aws:latest \
  prefect worker start --pool ecs-pool
```

**Local development:**

```bash
docker run -it --rm \
  -v $(pwd):/opt/prefect \
  prefecthq/prefect-aws:latest \
  python your_flow.py
```

## Examples

### Read and write files to AWS S3

Upload a file to an AWS S3 bucket and download the same file under a different filename.
The following code assumes that the bucket already exists:

```python
from pathlib import Path
from prefect import flow
from prefect_aws import AwsCredentials, S3Bucket


@flow
def s3_flow():
    # create a dummy file to upload
    file_path = Path("test-example.txt")
    file_path.write_text("Hello, Prefect!")

    aws_credentials = AwsCredentials.load("BLOCK-NAME-PLACEHOLDER")
    s3_bucket = S3Bucket(
        bucket_name="BUCKET-NAME-PLACEHOLDER",
        credentials=aws_credentials
    )

    s3_bucket_path = s3_bucket.upload_from_path(file_path)
    downloaded_file_path = s3_bucket.download_object_to_path(
        s3_bucket_path, "downloaded-test-example.txt"
    )
    return downloaded_file_path.read_text()


if __name__ == "__main__":
    s3_flow()
```

### Access secrets with AWS Secrets Manager

Write a secret to AWS Secrets Manager, read the secret data, delete the secret, and return the secret data.

```python
from prefect import flow
from prefect_aws import AwsCredentials, AwsSecret


@flow
def secrets_manager_flow():
    aws_credentials = AwsCredentials.load("BLOCK-NAME-PLACEHOLDER")
    aws_secret = AwsSecret(secret_name="test-example", aws_credentials=aws_credentials)
    aws_secret.write_secret(secret_data=b"Hello, Prefect!")
    secret_data = aws_secret.read_secret()
    aws_secret.delete_secret()
    return secret_data


if __name__ == "__main__":
    secrets_manager_flow()
```

### Invoke lambdas

```python
from prefect_aws.lambda_function import LambdaFunction
from prefect_aws.credentials import AwsCredentials

credentials = AwsCredentials()
lambda_function = LambdaFunction(
    function_name="test_lambda_function",
    aws_credentials=credentials,
)
response = lambda_function.invoke(
    payload={"foo": "bar"},
    invocation_type="RequestResponse",
)
response["Payload"].read()
```

### Submit AWS Glue jobs

```python
from prefect import flow
from prefect_aws import AwsCredentials
from prefect_aws.glue_job import GlueJobBlock


@flow
def example_run_glue_job():
    aws_credentials = AwsCredentials(
        aws_access_key_id="your_access_key_id",
        aws_secret_access_key="your_secret_access_key"
    )
    glue_job_run = GlueJobBlock(
        job_name="your_glue_job_name",
        arguments={"--YOUR_EXTRA_ARGUMENT": "YOUR_EXTRA_ARGUMENT_VALUE"},
    ).trigger()

    return glue_job_run.wait_for_completion()


if __name__ == "__main__":
    example_run_glue_job()
```

### Submit AWS Batch jobs

```python
from prefect import flow
from prefect_aws import AwsCredentials
from prefect_aws.batch import batch_submit


@flow
def example_batch_submit_flow():
    aws_credentials = AwsCredentials(
        aws_access_key_id="access_key_id",
        aws_secret_access_key="secret_access_key"
    )
    job_id = batch_submit(
        "job_name",
        "job_queue",
        "job_definition",
        aws_credentials
    )
    return job_id


if __name__ == "__main__":
    example_batch_submit_flow()
```

## Resources

### Documentation

* **[prefect-aws SDK Reference](https://reference.prefect.io/prefect_aws/)** - Complete API documentation for all blocks and tasks
* **[ECS Deployment Guide](/integrations/prefect-aws/ecs_guide)** - Step-by-step guide for deploying workflows on ECS
* **[Prefect Secrets Management](/v3/develop/secrets)** - Using AWS credentials with third-party services

### AWS Resources

* **[AWS Documentation](https://docs.aws.amazon.com/)** - Official AWS service documentation
* **[Boto3 Documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)** - Python SDK reference for AWS services
* **[AWS IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)** - Security recommendations for AWS access


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-aws/sdk





# Azure Container Instances Worker Guide
Source: https://docs-3.prefect.io/integrations/prefect-azure/aci_worker



## Why use ACI for flow run execution?

ACI (Azure Container Instances) is a fully managed compute platform that streamlines running your Prefect flows on scalable, on-demand infrastructure on Azure.

## Prerequisites

Before starting this guide, make sure you have:

* An Azure account and user permissions for provisioning resource groups and container instances.
* The `azure` CLI installed on your local machine. You can follow Microsoft's [installation guide](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli).
* Docker installed on your local machine.

## Step 1. Create a resource group

Azure resource groups serve as containers for managing groupings of Azure resources.

Replace `<resource-group-name>` with the name of your choosing, and `<location>` with a valid Azure location name, such as`eastus`.

```bash
export RG_NAME=<resource-group-name> && \
az group create --name $RG_NAME --location <location>
```

Throughout the rest of the guide, we'll need to refer to the **scope** of the created resource group, which is a string describing where the resource group lives in the hierarchy of your Azure account. To save the scope of your resource group as an environment variable, run the following command:

```bash
RG_SCOPE=$(az group show --name $RG_NAME --query id --output tsv)
```

You can check that the scope is correct before moving on by running `echo $RG_SCOPE` in your terminal. It should be formatted as follows:

```
/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>
```

## Step 2. Prepare ACI permissions

In order for the worker to create, monitor, and delete the other container instances in which flows will run, we'll need to create a **custom role** and an **identity**, and then affiliate that role to the identity with a **role assignment**. When we start our worker, we'll assign that identity to the container instance it's running in.

### 1. Create a role

The custom `Container Instances Contributor` role has all the permissions your worker will need to run flows in other container instances. Create it by running the following command:

```bash
az role definition create --role-definition '{
  "Name": "Container Instances Contributor",
  "IsCustom": true,
  "Description": "Can create, delete, and monitor container instances.",
  "Actions": [
    "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action",
    "Microsoft.Resources/deployments/*",
    "Microsoft.ContainerInstance/containerGroups/*"
  ],
  "NotActions": [
  ],
  "AssignableScopes": [
    '"\"$RG_SCOPE\""'
  ]
}'
```

### 2. Create an identity

Create a user-managed identity with the following command, replacing `<identity-name>` with the name you'd like to use for the identity:

```bash
export IDENTITY_NAME=<identity_name> && \
az identity create -g $RG_NAME -n $IDENTITY_NAME
```

We'll also need to save the principal ID and full object ID of the identity for the role assignment and container creation steps, respectively:

```bash
IDENTITY_PRINCIPAL_ID=$(az identity list --query "[?name=='$IDENTITY_NAME'].principalId" --output tsv) && \
IDENTITY_ID=$(az identity list --query "[?name=='$IDENTITY_NAME'].id" --output tsv)
```

### 3. Assign roles to the identity

Now let's assign the `Container Instances Contributor` role we created earlier to the new identity:

```bash
az role assignment create \
    --assignee $IDENTITY_PRINCIPAL_ID \
    --role "Container Instances Contributor" \
    --scope $RG_SCOPE
```

Since we'll be using ACR to host a custom Docker image containing a Prefect flow later in the guide, let's also assign the built in `AcrPull` role to the identity:

```bash
az role assignment create \
    --assignee $IDENTITY_PRINCIPAL_ID \
    --role "AcrPull" \
    --scope $RG_SCOPE
```

## Step 3. Create the worker container instance

Before running this command, set your `PREFECT_API_URL` and `PREFECT_API_KEY` as environment variables:

```bash
export PREFECT_API_URL=<PREFECT_API_URL_HERE> PREFECT_API_KEY=<PREFECT_API_KEY_HERE>
```

Running the following command will create a container instance in your Azure resource group that will start a Prefect ACI worker. If there is not already a work pool in Prefect with the name you chose, a work pool will also be created.

Replace `<work-pool-name>` with the name of the ACI work pool you want to create in Prefect. Here we're using the work pool name as the name of the container instance in Azure as well, but you may name it something else if you prefer.

```bash
az container create \
    --name <work-pool-name> \
    --resource-group $RG_NAME \
    --assign-identity $IDENTITY_ID \
    --image "prefecthq/prefect:3-python3.12" \
    --secure-environment-variables PREFECT_API_URL=$PREFECT_API_URL PREFECT_API_KEY=$PREFECT_API_KEY \
    --command-line "/bin/bash -c 'pip install prefect-azure && prefect worker start --pool <work-pool-name> --type azure-container-instance'" 
```

This container instance uses default networking and security settings. For advanced configuration, refer the `az container create` [CLI reference](https://learn.microsoft.com/en-us/cli/azure/container?view=azure-cli-latest#az-container-create).

## Step 4. Create an ACR registry

In order to build and push images containing flow code to Azure, we'll need a container registry. Create one with the following command, replacing `<registry-name>` with the registry name of your choosing:

```bash
export REGISTRY_NAME=<registry-name> && \
az acr create --resource-group $RG_NAME \
  --name <registry-name> --sku Basic
```

## Step 5. Update your ACI work pool configuration

Once your work pool is created, navigate to the Edit page of your ACI work pool. You will need to update the following fields:

### Identities

This will be your `IDENTITY_ID`. You can get it from your terminal by running `echo $IDENTITY_ID`. When adding it to your work pool, it should be formatted as a JSON array:

```
["/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"]
```

<img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-identities.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=5b6a19d6b2a5a742fb8587da6941d606" alt="Configuring an ACI work pool's identities." data-og-width="2860" width="2860" data-og-height="426" height="426" data-path="images/integrations/aci-worker-identities.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-identities.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c94e92fb24ace9f1e5bc974620319445 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-identities.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=a034033ac86d5f81625f48ce9214efd4 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-identities.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=d8b8b4438a58e9913e87f9c86a9c0b9f 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-identities.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=73363567c6b816257111c97d32abb623 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-identities.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=cc52b0b048841969c2de5769b94f2c79 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-identities.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=60e77729d0b4a16796f85b631364e320 2500w" data-optimize="true" data-opv="2" />

### ACRManagedIdentity

ACRManagedIdentity is required for your flow code containers to be pulled from ACR. It consists of the following:

* Identity: the same `IDENTITY_ID` as above, as a string

```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
```

* Registry URL: your `<registry-name>`, followed by `.azurecr.io`

```
<registry-name>.azurecr.io
```

<img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-acridentity.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=c5d86b7c9e8dc2dce48c264f9a1f9bda" alt="Configuring an ACI work pool's ACR Managed Identity." data-og-width="2824" width="2824" data-og-height="552" height="552" data-path="images/integrations/aci-worker-acridentity.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-acridentity.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=1bc6ae99eb0c39617e236af171f8a721 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-acridentity.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=6bd76d504ab1fadb86f1f52ae5d31e5c 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-acridentity.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=3cdc56678297cc04e0f43d34ceeea969 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-acridentity.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=18a784d93b3e47bac2c1a6a40b9fa12a 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-acridentity.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=e2ad6047d0e7d7cbec12c9865d45dd2e 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-acridentity.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=4fd35c1c53b2a517d2cd1741c3c68cd8 2500w" data-optimize="true" data-opv="2" />

### Subscription ID and resource group name

Both the subscription ID and resource group name can be found in the `RG_SCOPE` environment variable created earlier in the guide. View their values by running `echo $RG_SCOPE`:

```
/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>
```

<img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-subscription.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=9f9351730b058bea5fd23ee474630bf8" alt="Configuring an ACI work pool." data-og-width="1256" width="1256" data-og-height="468" height="468" data-path="images/integrations/aci-worker-subscription.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-subscription.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=616f3da9418664e564343d730514a717 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-subscription.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=4def6268ce57c7ba802bb04058a3188d 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-subscription.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=7af1d7dedd653c1d379a1cc3cca181fe 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-subscription.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=bf9ac9f9ec29dbf3eace13929e1af63c 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-subscription.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=e88e96b30f7c1ca1ad5656a9b0c302e0 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/integrations/aci-worker-subscription.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=fb83f99e758670f03ed15fe6801a679e 2500w" data-optimize="true" data-opv="2" />

Then click Save.

## Step 6. Pick up a flow run with your new worker

This guide uses ACR to store a Docker image containing your flow code. Write a flow, then deploy it using `flow.deploy()`, which will copy flow code into a Docker image and push that image to an ACR registry.

### 1. Log in to ACR

Use the following commands to log in to ACR:

```
TOKEN=$(az acr login --name $REGISTRY_NAME --expose-token --output tsv --query accessToken)
```

```
docker login $REGISTRY_NAME.azurecr.io --username 00000000-0000-0000-0000-000000000000 --password-stdin <<< $TOKEN
```

### 2. Write and deploy a simple test flow

Create and run the following script to deploy your flow. Be sure to replace `<registry-name>` and `<work-pool-name>` with the appropriate values.

`my_flow.py`

```python
from prefect import flow
from prefect.logging import get_run_logger
from prefect.docker import DockerImage

@flow
def my_flow():
    logger = get_run_logger()
    logger.info("Hello from ACI!")

if __name__ == "__main__":
    my_flow.deploy(
        name="aci-deployment",
        image=DockerImage(
            name="<registry-name>.azurecr.io/example:latest",
            platform="linux/amd64",
        ),
        work_pool_name="<work-pool-name>",
    )
```

### 3. Find the deployment in the UI and click the **Quick Run** button!


# prefect-azure
Source: https://docs-3.prefect.io/integrations/prefect-azure/index



`prefect-azure` makes it easy to leverage the capabilities of Azure in your workflows.
For example, you can retrieve secrets, read and write Blob Storage objects, and deploy your flows on Azure Container Instances (ACI).

## Getting started

### Prerequisites

* An [Azure account](https://azure.microsoft.com/) and the necessary permissions to access desired services.

### Install `prefect-azure`

The following command will install a version of `prefect-azure` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[azure]"
```

Upgrade to the latest versions of `prefect` and `prefect-azure`:

```bash
pip install -U "prefect[azure]"
```

If necessary, see [additional installation options for Blob Storage, Cosmos DB, and ML Datastore](#additional-installation-options).

To install prefect-azure with all additional capabilities, run the install command above and then run the following command:

```bash
pip install "prefect-azure[all_extras]"
```

### Register newly installed block types

Register the block types in the module to make them available for use.

```bash
prefect block register -m prefect_azure
```

## Examples

### Download a blob

```python
from prefect import flow

from prefect_azure import AzureBlobStorageCredentials
from prefect_azure.blob_storage import blob_storage_download

@flow
def example_blob_storage_download_flow():
    connection_string = "connection_string"
    blob_storage_credentials = AzureBlobStorageCredentials(
        connection_string=connection_string,
    )
    data = blob_storage_download(
        blob="prefect.txt",
        container="prefect",
        blob_storage_credentials=blob_storage_credentials,
    )
    return data

example_blob_storage_download_flow()
```

Use `with_options` to customize options on any existing task or flow:

```python
custom_blob_storage_download_flow = example_blob_storage_download_flow.with_options(
    name="My custom task name",
    retries=2,
    retry_delay_seconds=10,
)
```

### Run flows on Azure Container Instances

Run flows on [Azure Container Instances (ACI)](https://learn.microsoft.com/en-us/azure/container-instances/) to dynamically scale your infrastructure.

See the [Azure Container Instances Worker Guide](/integrations/prefect-azure/aci_worker/) for a walkthrough of using ACI in a hybrid work pool.

If you're using Prefect Cloud, [ACI push work pools](/v3/how-to-guides/deployment_infra/serverless#azure-container-instances) provide all the benefits of ACI with a quick setup and no worker needed.

## Resources

For assistance using Azure, consult the [Azure documentation](https://learn.microsoft.com/en-us/azure).

Refer to the `prefect-azure` API documentation linked in the sidebar to explore all the capabilities of the `prefect-azure` library.

### Additional installation options

First install the main library compatible with your `prefect` version:

```bash
pip install "prefect[azure]"
```

Then install the additional capabilities you need.

To use Blob Storage:

```bash
pip install "prefect-azure[blob_storage]"
```

To use Cosmos DB:

```bash
pip install "prefect-azure[cosmos_db]"
```

To use ML Datastore:

```bash
pip install "prefect-azure[ml_datastore]"
```


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-azure/sdk





# prefect-bitbucket
Source: https://docs-3.prefect.io/integrations/prefect-bitbucket/index



The `prefect-bitbucket` library makes it easy to interact with Bitbucket repositories and credentials.

## Getting started

### Prerequisites

* A [Bitbucket account](https://bitbucket.org/product).

### Install `prefect-bitbucket`

The following command will install a version of `prefect-bitbucket` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[bitbucket]"
```

Upgrade to the latest versions of `prefect` and `prefect-bitbucket`:

```bash
pip install -U "prefect[bitbucket]"
```

### Register newly installed block types

Register the block types in the `prefect-bitbucket` module to make them available for use.

```bash
prefect block register -m prefect_bitbucket
```

## Examples

In the examples below, you create blocks with Python code.
Alternatively, blocks can be created through the Prefect UI.

## Store deployment flow code in a private Bitbucket repository

To create a deployment and run a deployment where the flow code is stored in a private Bitbucket repository, you can use the `BitBucketCredentials` block.

A deployment can use flow code stored in a Bitbucket repository without using this library in either of the following cases:

* The repository is public
* The deployment uses a [Secret block](/v3/develop/secrets) to store the token

Create a Bitbucket Credentials block:

```python
from prefect_bitbucket import BitBucketCredentials


bitbucket_credentials_block = BitBucketCredentials(token="x-token-auth:my-token")
bitbucket_credentials_block.save(name="my-bitbucket-credentials-block")
```

<Info>
  **Difference between Bitbucket Server and Bitbucket Cloud authentication**

  If using a token to authenticate to Bitbucket Cloud, only set the `token` to authenticate. Do not include a value in the `username` field or authentication will fail. If using Bitbucket Server, provide both the `token` and `username` values.
</Info>

### Access flow code stored in a private Bitbucket repository in a deployment

Use the credentials block you created above to pass the Bitbucket access token during deployment creation. The code below assumes there's flow code stored in a private Bitbucket repository.

```python
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect_bitbucket import BitBucketCredentials


if __name__ == "__main__":
    
    source = GitRepository(
        url="https://bitbucket.com/org/private-repo.git",
        credentials=BitBucketCredentials.load("my-bitbucket-credentials-block")
        )

    flow.from_source(
        source=source,
        entrypoint="my_file.py:my_flow",
    ).deploy(
        name="private-bitbucket-deploy",
        work_pool_name="my_pool",
    )
```

Alternatively, if you use a `prefect.yaml` file to create the deployment, reference the Bitbucket Credentials block in the `pull` step:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        credentials: https://bitbucket.org/org/private-repo.git
        credentials: "{{ prefect.blocks.bitbucket-credentials.my-bitbucket-credentials-block }}"
```

### Interact with a Bitbucket repository

The code below shows how to reference a particular branch or tag of a Bitbucket repository.

```python
from prefect_bitbucket import BitbucketRepository


def save_bitbucket_block():
    bitbucket_block = BitbucketRepository(
        repository="https://bitbucket.org/testing/my-repository.git",
        reference="branch-or-tag-name",
    )

    bitbucket_block.save("my-bitbucket-block")


if __name__ == "__main__":
    save_bitbucket_block()
```

Exclude the `reference` field to use the default branch.
Reference a BitBucketCredentials block for authentication if the repository is private.

Use the newly created block to interact with the Bitbucket repository.

For example, download the repository contents with the `.get_directory()` method like this:

```python
from prefect_bitbucket.repositories import BitbucketRepository


def fetch_repo():
    bitbucket_block = BitbucketRepository.load("my-bitbucket-block")
    bitbucket_block.get_directory()


if __name__ == "__main__":
    fetch_repo()
```

## Resources

For assistance using Bitbucket, consult the [Bitbucket documentation](https://bitbucket.org/product/guides).

Refer to the `prefect-bitbucket` [SDK documentation](https://reference.prefect.io/prefect_bitbucket/) to explore all the capabilities of the `prefect-bitbucket` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-bitbucket/sdk





# prefect-dask
Source: https://docs-3.prefect.io/integrations/prefect-dask/index

Accelerate your workflows by running tasks in parallel with Dask

Dask can run your tasks in parallel and distribute them over multiple machines.
The `prefect-dask` integration makes it easy to accelerate your flow runs with Dask.

## Getting started

### Install `prefect-dask`

The following command will install a version of `prefect-dask` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

<CodeGroup>
  ```bash pip
  pip install "prefect[dask]"
  ```

  ```bash uv
  uv pip install "prefect[dask]"
  ```
</CodeGroup>

Upgrade to the latest versions of `prefect` and `prefect-dask`:

<CodeGroup>
  ```bash pip
  pip install -U "prefect[dask]"
  ```

  ```bash uv
  uv pip install -U "prefect[dask]"
  ```
</CodeGroup>

## Why use Dask?

Say your flow downloads many images to train a machine learning model.
It takes longer than you'd like for the flow to run because it executes sequentially.

To accelerate your flow code, parallelize it with `prefect-dask` in three steps:

1. Add the import: `from prefect_dask import DaskTaskRunner`
2. Specify the task runner in the flow decorator: `@flow(task_runner=DaskTaskRunner)`
3. Submit tasks to the flow's task runner: `a_task.submit(*args, **kwargs)`

Below is code with and without the DaskTaskRunner:

<Tabs>
  <Tab title="Sequential by default">
    ```python
    # Completed in 15.2 seconds

    from typing import List
    from pathlib import Path

    import httpx
    from prefect import flow, task

    URL_FORMAT = (
        "https://www.cpc.ncep.noaa.gov/products/NMME/archive/"
        "{year:04d}{month:02d}0800/current/images/nino34.rescaling.ENSMEAN.png"
    )

    @task
    def download_image(year: int, month: int, directory: Path) -> Path:
        # download image from URL
        url = URL_FORMAT.format(year=year, month=month)
        resp = httpx.get(url)

        # save content to directory/YYYYMM.png
        file_path = (directory / url.split("/")[-1]).with_stem(f"{year:04d}{month:02d}")
        file_path.write_bytes(resp.content)
        return file_path

    @flow
    def download_nino_34_plumes_from_year(year: int) -> List[Path]:
        # create a directory to hold images
        directory = Path("data")
        directory.mkdir(exist_ok=True)

        # download all images
        file_paths = []
        for month in range(1, 12 + 1):
            file_path = download_image(year, month, directory)
            file_paths.append(file_path)
        return file_paths

    if __name__ == "__main__":
        download_nino_34_plumes_from_year(2022)
    ```
  </Tab>

  <Tab title="Parallel with Dask">
    ```python
    # Completed in 5.7 seconds

    from typing import List
    from pathlib import Path

    import httpx
    from prefect import flow, task
    from prefect_dask import DaskTaskRunner

    URL_FORMAT = (
        "https://www.cpc.ncep.noaa.gov/products/NMME/archive/"
        "{year:04d}{month:02d}0800/current/images/nino34.rescaling.ENSMEAN.png"
    )

    @task
    def download_image(year: int, month: int, directory: Path) -> Path:
        # download image from URL
        url = URL_FORMAT.format(year=year, month=month)
        resp = httpx.get(url)

        # save content to directory/YYYYMM.png
        file_path = (directory / url.split("/")[-1]).with_stem(f"{year:04d}{month:02d}")
        file_path.write_bytes(resp.content)
        return file_path

    @flow(task_runner=DaskTaskRunner(cluster_kwargs={"processes": False}))
    def download_nino_34_plumes_from_year(year: int) -> List[Path]:
        # create a directory to hold images
        directory = Path("data")
        directory.mkdir(exist_ok=True)

        # download all images
        file_paths = []
        for month in range(1, 12 + 1):
            file_path = download_image.submit(year, month, directory)
            file_paths.append(file_path)
        return file_paths

    if __name__ == "__main__":
        download_nino_34_plumes_from_year(2022)
    ```
  </Tab>
</Tabs>

In our tests, the flow run took 15.2 seconds to execute sequentially.
Using the `DaskTaskRunner` reduced the runtime to **5.7** seconds!

## Run tasks on Dask

The `DaskTaskRunner` is a [task runner](/v3/develop/task-runners) that submits tasks to the [`dask.distributed`](http://distributed.dask.org/) scheduler.
By default, when the `DaskTaskRunner` is specified for a flow run, a temporary Dask cluster is created and used for the duration of the flow run.

If you already have a Dask cluster running, either cloud-hosted or local, you can provide the connection URL with the `address` kwarg.

`DaskTaskRunner` accepts the following optional parameters:

| Parameter       | Description                                                                                                                                                             |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address         | Address of a currently running Dask scheduler.                                                                                                                          |
| cluster\_class  | The cluster class to use when creating a temporary Dask cluster. It can be either the full class name (for example, `"distributed.LocalCluster"`), or the class itself. |
| cluster\_kwargs | Additional kwargs to pass to the `cluster_class` when creating a temporary Dask cluster.                                                                                |
| adapt\_kwargs   | Additional kwargs to pass to `cluster.adapt` when creating a temporary Dask cluster. Note that adaptive scaling is only enabled if `adapt_kwargs` are provided.         |
| client\_kwargs  | Additional kwargs to use when creating a [`dask.distributed.Client`](https://distributed.dask.org/en/latest/api.html#client).                                           |

<Warning>
  **Multiprocessing safety**

  Because the `DaskTaskRunner` uses multiprocessing, calls to flows in scripts must be guarded with `if __name__ == "__main__":` or you will encounter warnings and errors.
</Warning>

If you don't provide the `address` of a Dask scheduler, Prefect creates a temporary local cluster automatically.
The number of workers used is based on the number of cores on your machine.
The default provides a mix of processes and threads that work well for most workloads.
To specify this explicitly, pass values for `n_workers` or `threads_per_worker` to `cluster_kwargs`:

```python
from prefect_dask import DaskTaskRunner

# Use 4 worker processes, each with 2 threads
DaskTaskRunner(
    cluster_kwargs={"n_workers": 4, "threads_per_worker": 2}
)
```

### Use a temporary cluster

The `DaskTaskRunner` can create a temporary cluster using any of [Dask's cluster-manager options](https://docs.dask.org/en/latest/setup.html).
This is useful when you want each flow run to have its own Dask cluster, allowing for per-flow adaptive scaling.
To configure it, provide a `cluster_class`.
This can be:

* A string specifying the import path to the cluster class (for example, `"dask_cloudprovider.aws.FargateCluster"`)
* The cluster class itself
* A function for creating a custom cluster

You can also configure `cluster_kwargs`.
This takes a dictionary of keyword arguments to pass to `cluster_class` when starting the flow run.

For example, to configure a flow to use a temporary `dask_cloudprovider.aws.FargateCluster` with four workers running with an image named `my-prefect-image`:

```python
from prefect_dask import DaskTaskRunner

DaskTaskRunner(
    cluster_class="dask_cloudprovider.aws.FargateCluster",
    cluster_kwargs={"n_workers": 4, "image": "my-prefect-image"},
)
```

For larger workloads, you can accelerate execution further by distributing task runs over multiple machines.

### Connect to an existing cluster

Multiple Prefect flow runs can use the same existing Dask cluster.
You might manage a single long-running Dask cluster (for example, using the Dask [Helm Chart](https://docs.dask.org/en/latest/setup/kubernetes-helm.html)) and configure flows to connect to it during execution.
This has disadvantages compared to using a temporary Dask cluster:

* All workers in the cluster must have dependencies installed for all flows you intend to run.
* Multiple flow runs may compete for resources. Dask tries to do a good job
  sharing resources between tasks, but you may still run into issues.

Still, you may prefer managing a single long-running Dask cluster.

To configure a `DaskTaskRunner` to connect to an existing cluster, pass in the address of the scheduler to the `address` argument:

```python
from prefect_dask import DaskTaskRunner

@flow(task_runner=DaskTaskRunner(address="http://my-dask-cluster"))
def my_flow():
    ...
```

Suppose you have an existing Dask client/cluster such as a `dask.dataframe.DataFrame`.
With `prefect-dask`, it takes just a few steps:

1. Add imports
2. Add `task` and `flow` decorators
3. Use `get_dask_client` context manager to distribute work across Dask workers
4. Specify the task runner and client's address in the flow decorator
5. Submit the tasks to the flow's task runner

<Tabs>
  <Tab title="Without Prefect">
    ```python
    import dask.dataframe
    import dask.distributed


    client = dask.distributed.Client()

    def read_data(start: str, end: str) -> dask.dataframe.DataFrame:
        df = dask.datasets.timeseries(start, end, partition_freq="4w")
        return df


    def process_data(df: dask.dataframe.DataFrame) -> dask.dataframe.DataFrame:

        df_yearly_avg = df.groupby(df.index.year).mean()
        return df_yearly_avg.compute()


    def dask_pipeline():
        df = read_data("1988", "2022")
        df_yearly_average = process_data(df)
        return df_yearly_average


    if __name__ == "__main__":
        dask_pipeline()
    ```
  </Tab>

  <Tab title="With Prefect">
    ```python
    import dask.dataframe
    import dask.distributed
    from prefect import flow, task
    from prefect_dask import DaskTaskRunner, get_dask_client


    client = dask.distributed.Client()

    @task
    def read_data(start: str, end: str) -> dask.dataframe.DataFrame:
        df = dask.datasets.timeseries(start, end, partition_freq="4w")
        return df

    @task
    def process_data(df: dask.dataframe.DataFrame) -> dask.dataframe.DataFrame:
        with get_dask_client():
            df_yearly_avg = df.groupby(df.index.year).mean()
            return df_yearly_avg.compute()

    @flow(task_runner=DaskTaskRunner(address=client.scheduler.address))
    def dask_pipeline():
        df = read_data.submit("1988", "2022")
        df_yearly_average = process_data.submit(df)
        return df_yearly_average


    if __name__ == "__main__":
        dask_pipeline()
    ```
  </Tab>
</Tabs>

### Configure adaptive scaling

A key feature of using a `DaskTaskRunner` is the ability to scale adaptively to the workload.
Instead of specifying `n_workers` as a fixed number, you can specify a minimum and maximum number of workers to use, and the Dask cluster scales up and down as needed.

To do this, pass `adapt_kwargs` to `DaskTaskRunner`.
This takes the following fields:

* `maximum` (`int` or `None`, optional): the maximum number of workers to scale to. Set to `None` for no maximum.
* `minimum` (`int` or `None`, optional): the minimum number of workers to scale to. Set to `None` for no minimum.

For example, this configures a flow to run on a `FargateCluster` scaling up to a maximum of 10 workers:

```python
from prefect_dask import DaskTaskRunner

DaskTaskRunner(
    cluster_class="dask_cloudprovider.aws.FargateCluster",
    adapt_kwargs={"maximum": 10}
)
```

### Use Dask annotations

Use Dask annotations to further control the behavior of tasks.
For example, set the [priority](http://distributed.dask.org/en/stable/priority.html) of tasks in the Dask scheduler:

```python
import dask
from prefect import flow, task
from prefect_dask.task_runners import DaskTaskRunner


@task
def show(x):
    print(x)


@flow(task_runner=DaskTaskRunner())
def my_flow():
    with dask.annotate(priority=-10):
        future = show.submit(1)  # low priority task

    with dask.annotate(priority=10):
        future = show.submit(2)  # high priority task
```

Another common use case is [resource](http://distributed.dask.org/en/stable/resources.html) annotations:

```python
import dask
from prefect import flow, task
from prefect_dask.task_runners import DaskTaskRunner


@task
def show(x):
    print(x)

# Create a `LocalCluster` with some resource annotations
# Annotations are abstract in dask and not inferred from your system.
# Here, we claim that our system has 1 GPU and 1 process available per worker
@flow(
    task_runner=DaskTaskRunner(
        cluster_kwargs={"n_workers": 1, "resources": {"GPU": 1, "process": 1}}
    )
)

def my_flow():
    with dask.annotate(resources={'GPU': 1}):
        future = show(0)  # this task requires 1 GPU resource on a worker

    with dask.annotate(resources={'process': 1}):
        # These tasks each require 1 process on a worker; because we've
        # specified that our cluster has 1 process per worker and 1 worker,
        # these tasks will run sequentially
        future = show(1)
        future = show(2)
        future = show(3)


if __name__ == "__main__":
    my_flow()
```

## Additional Resources

Refer to the `prefect-dask` [SDK documentation](https://reference.prefect.io/prefect_dask/) to explore all the capabilities of the `prefect-dask` library.

For assistance using Dask, consult the [Dask documentation](https://docs.dask.org/en/stable/)

<Warning>
  **Resolving futures in sync client**

  Note, by default, `dask_collection.compute()` returns concrete values while `client.compute(dask_collection)` returns Dask Futures. Therefore, if you call `client.compute`, you must resolve all futures before exiting out of the context manager by either:

  1. setting `sync=True`

  ```python
  with get_dask_client() as client:
      df = dask.datasets.timeseries("2000", "2001", partition_freq="4w")
      summary_df = client.compute(df.describe(), sync=True)
  ```

  2. calling `result()`

  ```python
  with get_dask_client() as client:
      df = dask.datasets.timeseries("2000", "2001", partition_freq="4w")
      summary_df = client.compute(df.describe()).result()
  ```

  For more information, visit the docs on [Waiting on Futures](https://docs.dask.org/en/stable/futures.html#waiting-on-futures).
</Warning>

There is also an equivalent context manager for asynchronous tasks and flows: `get_async_dask_client`. When using the async client, you must `await client.compute(dask_collection)` before exiting the context manager.

Note that task submission (`.submit()`) and future resolution (`.result()`) are always synchronous operations in Prefect, even when working with async tasks and flows.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-dask/sdk





# prefect-databricks
Source: https://docs-3.prefect.io/integrations/prefect-databricks/index



Prefect integrations for interacting with Databricks.

## Getting started

### Prerequisites

* A [Databricks account](https://databricks.com/) and the necessary permissions to access desired services.

### Install `prefect-databricks`

The following command will install a version of `prefect-databricks` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[databricks]"
```

Upgrade to the latest versions of `prefect` and `prefect-databricks`:

```bash
pip install -U "prefect[databricks]"
```

### List jobs on the Databricks instance

```python
from prefect import flow
from prefect_databricks import DatabricksCredentials
from prefect_databricks.jobs import jobs_list


@flow
def example_execute_endpoint_flow():
    databricks_credentials = DatabricksCredentials.load("my-block")
    jobs = jobs_list(
        databricks_credentials,
        limit=5
    )
    return jobs

if __name__ == "__main__":
    example_execute_endpoint_flow()
```

### Use `with_options` to customize options on any existing task or flow

```python
custom_example_execute_endpoint_flow = example_execute_endpoint_flow.with_options(
    name="My custom flow name",
    retries=2,
    retry_delay_seconds=10,
)
```

### Launch a new cluster and run a Databricks notebook

Notebook named `example.ipynb` on Databricks which accepts a name parameter:

```python
name = dbutils.widgets.get("name")
message = f"Don't worry {name}, I got your request! Welcome to prefect-databricks!"
print(message)
```

Prefect flow that launches a new cluster to run `example.ipynb`:

```python
from prefect import flow
from prefect_databricks import DatabricksCredentials
from prefect_databricks.jobs import jobs_runs_submit
from prefect_databricks.models.jobs import (
    AutoScale,
    AwsAttributes,
    JobTaskSettings,
    NotebookTask,
    NewCluster,
)


@flow
def jobs_runs_submit_flow(notebook_path, **base_parameters):
    databricks_credentials = DatabricksCredentials.load("my-block")

    # specify new cluster settings
    aws_attributes = AwsAttributes(
        availability="SPOT",
        zone_id="us-west-2a",
        ebs_volume_type="GENERAL_PURPOSE_SSD",
        ebs_volume_count=3,
        ebs_volume_size=100,
    )
    auto_scale = AutoScale(min_workers=1, max_workers=2)
    new_cluster = NewCluster(
        aws_attributes=aws_attributes,
        autoscale=auto_scale,
        node_type_id="m4.large",
        spark_version="10.4.x-scala2.12",
        spark_conf={"spark.speculation": True},
    )

    # specify notebook to use and parameters to pass
    notebook_task = NotebookTask(
        notebook_path=notebook_path,
        base_parameters=base_parameters,
    )

    # compile job task settings
    job_task_settings = JobTaskSettings(
        new_cluster=new_cluster,
        notebook_task=notebook_task,
        task_key="prefect-task"
    )

    run = jobs_runs_submit(
        databricks_credentials=databricks_credentials,
        run_name="prefect-job",
        tasks=[job_task_settings]
    )

    return run

if __name__ == "__main__":
    jobs_runs_submit_flow("/Users/username@gmail.com/example.ipynb", name="Marvin")
```

Note, instead of using the built-in models, you may also input valid JSON. For example, `AutoScale(min_workers=1, max_workers=2)` is equivalent to `{"min_workers": 1, "max_workers": 2}`.

## Resources

For assistance using Databricks, consult the [Databricks documentation](https://www.databricks.com/databricks-documentation).

Refer to the `prefect-databricks` [SDK documentation](https://reference.prefect.io/prefect_databricks/) to explore all the capabilities of the `prefect-databricks` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-databricks/sdk





# prefect-dbt
Source: https://docs-3.prefect.io/integrations/prefect-dbt/index



With `prefect-dbt`, you can trigger and observe dbt Cloud jobs, execute dbt Core CLI commands, and incorporate other tools, such as [Snowflake](/integrations/prefect-snowflake/index), into your dbt runs.
Prefect provides a global view of the state of your workflows and allows you to take action based on state changes.

Prefect integrations may provide pre-built [blocks](/v3/develop/blocks), [flows](/v3/develop/write-flows), or [tasks](/v3/develop/write-tasks) for interacting with external systems.
Block types in this library allow you to do things such as run a dbt Cloud job or execute a dbt Core command.

## Getting started

### Prerequisites

* A [dbt Cloud account](https://cloud.getdbt.com/) if using dbt Cloud.

### Install `prefect-dbt`

The following command will install a version of `prefect-dbt` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[dbt]"
```

Upgrade to the latest versions of `prefect` and `prefect-dbt`:

```bash
pip install -U "prefect[dbt]"
```

If necessary, see [additional installation options for dbt Core with BigQuery, Snowflake, and Postgres](#additional-installation-options).

### Register newly installed blocks types

Register the block types in the `prefect-dbt` module to make them available for use.

```bash
prefect block register -m prefect_dbt
```

## dbt Cloud

If you have an existing dbt Cloud job, use the pre-built flow `run_dbt_cloud_job` to trigger a job run and wait until the job run is finished. If some nodes fail, `run_dbt_cloud_job` can efficiently retry the unsuccessful nodes. Prior to running this flow, save your dbt Cloud credentials to a DbtCloudCredentials block and create a dbt Cloud Job block:

### Save dbt Cloud credentials to a block

Blocks can be [created through code](/v3/develop/blocks) or through the UI.

To create a dbt Cloud Credentials block:

1. Log into your [dbt Cloud account](https://cloud.getdbt.com/settings/profile).
2. Click **API Tokens** on the sidebar.
3. Copy a Service Token.
4. Copy the account ID from the URL: `https://cloud.getdbt.com/settings/accounts/<ACCOUNT_ID>`.
5. Create and run the following script, replacing the placeholders:

```python
from prefect_dbt.cloud import DbtCloudCredentials


DbtCloudCredentials(
    api_key="API-KEY-PLACEHOLDER",
    account_id="ACCOUNT-ID-PLACEHOLDER"
).save("CREDENTIALS-BLOCK-NAME-PLACEHOLDER")
```

### Create a dbt Cloud job block

1. In dbt Cloud, click on **Deploy** -> **Jobs**.
2. Select a job.
3. Copy the job ID from the URL: `https://cloud.getdbt.com/deploy/<ACCOUNT_ID>/projects/<PROJECT_ID>/jobs/<JOB_ID>`
4. Create and run the following script, replacing the placeholders.

```python
from prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob


dbt_cloud_credentials = DbtCloudCredentials.load("CREDENTIALS-BLOCK-PLACEHOLDER")
dbt_cloud_job = DbtCloudJob(
    dbt_cloud_credentials=dbt_cloud_credentials,
    job_id="JOB-ID-PLACEHOLDER"
).save("JOB-BLOCK-NAME-PLACEHOLDER")
```

### Run a dbt Cloud job and wait for completion

```python
from prefect import flow
from prefect_dbt.cloud import DbtCloudJob
from prefect_dbt.cloud.jobs import run_dbt_cloud_job
import asyncio

@flow
async def run_dbt_job_flow():
    result = await run_dbt_cloud_job(
        dbt_cloud_job = await DbtCloudJob.load("JOB-BLOCK-NAME-PLACEHOLDER"),
        targeted_retries = 0,
    )
    return await result

if __name__ == "__main__":
    asyncio.run(run_dbt_job_flow())
```

## dbt Core

### prefect-dbt 0.7.0 and later

Versions 0.7.0 and later of `prefect-dbt` include the `PrefectDbtRunner` class, which provides an improved interface for running dbt Core commands with better logging, failure handling, and automatic asset lineage.

<Tip>
  The `PrefectDbtRunner` is inspired by the `DbtRunner` from dbt Core, and its `invoke` method accepts the same arguments.
  Refer to the [`DbtRunner` documentation](https://docs.getdbt.com/reference/programmatic-invocations) for more information on how to call `invoke`.
</Tip>

Basic usage:

```python
from prefect import flow
from prefect_dbt import PrefectDbtRunner


@flow
def run_dbt():
    PrefectDbtRunner().invoke(["build"])


if __name__ == "__main__":
    run_dbt()
```

When calling `.invoke()` in a flow or task, each node in dbt's execution graph is reflected as a task in Prefect's execution graph.
Logs from each node will belong to the corresponding task, and each task's state is determined by the state of that node's execution.

```bash
15:54:59.119 | INFO    | Flow run 'imposing-partridge' - Found 8 models, 3 seeds, 18 data tests, 543 macros
15:54:59.134 | INFO    | Flow run 'imposing-partridge' - 
15:54:59.148 | INFO    | Flow run 'imposing-partridge' - Concurrency: 1 threads (target='dev')
15:54:59.164 | INFO    | Flow run 'imposing-partridge' - 
15:54:59.665 | INFO    | Task run 'model my_first_dbt_model' - 1 of 29 OK created sql table model main.my_first_dbt_model ..................... [OK in 0.18s]
15:54:59.671 | INFO    | Task run 'model my_first_dbt_model' - Finished in state Completed()
...
15:55:02.373 | ERROR   | Task run 'model product_metrics' -   Runtime Error in model product_metrics (models/marts/product/product_metrics.sql)
  Binder Error: Values list "o" does not have a column named "product_id"
  
  LINE 47:         on p.product_id = o.product_id
15:55:02.857 | ERROR   | Task run 'model product_metrics' - Finished in state Failed('Task run encountered an exception Exception: Node model.demo.product_metrics finished with status error')
```

<Warning>
  The task runs created by calling `.invoke()` run separately from dbt Core, and do not affect dbt's execution behavior.
  These tasks do not persist results and cannot be cached.

  Use [dbt's native retry functionality](https://docs.getdbt.com/reference/commands/retry) in combination with [runtime data from `prefect`](/v3/how-to-guides/workflows/access-runtime-info) to retry failed nodes.

  ```python
  from prefect import flow
  from prefect.runtime.flow_run import get_run_count
  from prefect_dbt import PrefectDbtRunner


  @flow(retries=2)
  def run_dbt():
      runner = PrefectDbtRunner()

      if get_run_count() == 1:
          runner.invoke(["build"])
      else:
          runner.invoke(["retry"])


  if __name__ == "__main__":
      run_dbt()
  ```
</Warning>

#### Assets

Prefect Cloud maintains a graph of [assets](/v3/concepts/assets), objects produced by your workflows.

Any dbt seed, source or model will appear on your asset graph in Prefect Cloud once it has been executed using the `PrefectDbtRunner`.
The upstream dependencies of an asset materialized by `prefect-dbt` are derived from the `depends_on` field in dbt's `manifest.json`.

The asset's `key` will be its corresponding dbt resource's `relation_name`.

The `name` and `description` asset properties are populated by a dbt resource's name description.

The `owners` asset property is populated if there is data assigned to the `owner` key under a resoure's `meta` config.

```yaml
models:
  - name: product_metrics
    description: "Product metrics and categorization"
    config:
      meta:
        owner: "kevin-g"
```

Asset metadata is collected from the result of the node's execution.

```json
{
  "node_path": "marts/product/product_metrics.sql",
  "node_name": "product_metrics",
  "unique_id": "model.demo.product_metrics",
  "resource_type": "model",
  "materialized": "table",
  "node_status": "error",
  "node_started_at": "2025-06-26T20:55:05.661126",
  "node_finished_at": "2025-06-26T20:55:05.733257",
  "meta": {
    "owner": "kevin-g"
  },
  "node_relation": {
    "database": "dev",
    "schema": "main_marts",
    "alias": "product_metrics",
    "relation_name": "\"dev\".\"main_marts\".\"product_metrics\""
  }
}
```

Optionally, the compiled code of a dbt model can be appended to the asset description.

```python
from prefect import flow
from prefect_dbt import PrefectDbtRunner


@flow
def run_dbt():
    PrefectDbtRunner(include_compiled_code=True).invoke(["build"])


if __name__ == "__main__":
    run_dbt()
```

#### dbt settings

The `PrefectDbtSettings` class, based on Pydantic's `BaseSettings` class, automatically detects `DBT_`-prefixed environment variables that have a direct effect on the `PrefectDbtRunner` class.
If no environment variables are set, dbt's defaults are used.

Provide a `PrefectDbtSettings` instance to `PrefectDbtRunner` to customize dbt settings or override environment variables.

```python
from prefect import flow
from prefect_dbt import PrefectDbtRunner, PrefectDbtSettings


@flow
def run_dbt():
    PrefectDbtRunner(
        settings=PrefectDbtSettings(
            project_dir="test",
            profiles_dir="examples/run_dbt"
        )
    ).invoke(["build"])


if __name__ == "__main__":
    run_dbt()
```

#### Logging

The `PrefectDbtRunner` class maps all dbt log levels to standard Python logging levels, so filtering for log levels like `WARNING` or `ERROR` in the Prefect UI applies to dbt's logs.

By default, the logging level used by dbt is Prefect's logging level, which can be configured using the `PREFECT_LOGGING_LEVEL` Prefect setting.

The dbt logging level can be set independently from Prefect's by using the `DBT_LOG_LEVEL` environment variable, setting `log_level` in `PrefectDbtSettings`, or passing the `--log-level` flag or `log_level` kwarg to `.invoke()`.
Only logging levels of higher severity (more restrictive) than Prefect's logging level will have an effect.

```python
from dbt_common.events.base_types import EventLevel
from prefect import flow
from prefect_dbt import PrefectDbtRunner, PrefectDbtSettings


@flow
def run_dbt():
    PrefectDbtRunner(
        settings=PrefectDbtSettings(
            project_dir="test",
            profiles_dir="examples/run_dbt",
            log_level=EventLevel.ERROR, # explicitly choose a higher log level for dbt
        )
    ).invoke(["build"])


if __name__ == "__main__":
    run_dbt()
```

#### `profiles.yml` templating

The `PrefectDbtRunner` class supports templating in your `profiles.yml` file, allowing you to reference Prefect blocks and variables that will be resolved at runtime.
This enables you to store sensitive credentials securely using Prefect blocks, and configure different targets based on the Prefect workspace.

For example, a Prefect variable called `target` can have a different value in development (`dev`) and production (`prod`) workspaces.
This allows you to use the same `profiles.yml` file to automatically reference a local DuckDB instance in development and a Snowflake instance in production.

```yaml
example:
  outputs:
    dev:
      type: duckdb
      path: dev.duckdb
      threads: 1

    prod:
      type: snowflake
      account: "{{ prefect.blocks.snowflake-credentials.warehouse-access.account }}"
      user: "{{ prefect.blocks.snowflake-credentials.warehouse-access.user }}"
      password: "{{ prefect.blocks.snowflake-credentials.warehouse-access.password }}"
      database: "{{ prefect.blocks.snowflake-connector.prod-connector.database }}"
      schema: "{{ prefect.blocks.snowflake-connector.prod-connector.schema }}"
      warehouse: "{{ prefect.blocks.snowflake-connector.prod-connector.warehouse }}"
      threads: 4

  target: "{{ prefect.variables.target }}"
```

#### Failure handling

By default, any dbt node execution failures cause the entire dbt run to raise an exception with a message containing detailed information about the failure.

```
Failures detected during invocation of dbt command 'build':
Test not_null_my_first_dbt_model_id failed with message: "Got 1 result, configured to fail if != 0"
```

The `PrefectDbtRunner`'s `raise_on_failure` option can be set to `False` to prevent failures in dbt from causing the failure of the flow or task in which `.invoke()` is called.

```python
from prefect import flow
from prefect_dbt import PrefectDbtRunner


@flow
def run_dbt():
    PrefectDbtRunner(
        raise_on_failure=False  # Failed tests will not fail the flow run
    ).invoke(["build"])


if __name__ == "__main__":
    run_dbt()
```

#### Native dbt configuration

You can disable automatic asset lineage detection for all resources in your dbt project config, or for specific resources in their own config:

```yaml
prefect:
  enable_assets: False
```

### prefect-dbt 0.6.6 and earlier

`prefect-dbt` supports a couple of ways to run dbt Core commands.
A `DbtCoreOperation` block will run the commands as shell commands, while other tasks use dbt's [Programmatic Invocation](#programmatic-invocation).

Optionally, specify the `project_dir`.
If `profiles_dir` is not set, the `DBT_PROFILES_DIR` environment variable will be used.
If `DBT_PROFILES_DIR` is not set, the default directory will be used `$HOME/.dbt/`.

#### Use an existing profile

If you have an existing dbt `profiles.yml` file, specify the `profiles_dir` where the file is located:

```python
from prefect import flow
from prefect_dbt.cli.commands import DbtCoreOperation


@flow
def trigger_dbt_flow() -> str:
    result = DbtCoreOperation(
        commands=["pwd", "dbt debug", "dbt run"],
        project_dir="PROJECT-DIRECTORY-PLACEHOLDER",
        profiles_dir="PROFILES-DIRECTORY-PLACEHOLDER"
    ).run()
    return result


if __name__ == "__main__":
    trigger_dbt_flow()
```

If you are already using Prefect blocks such as the [Snowflake Connector block](integrations/prefect-snowflake), you can use those blocks to [create a new `profiles.yml` with a `DbtCliProfile` block](#create-a-new-profile-with-blocks).

##### Use environment variables with Prefect secret blocks

If you use environment variables in `profiles.yml`, set a Prefect Secret block as an environment variable:

```python
import os
from prefect.blocks.system import Secret


secret_block = Secret.load("DBT_PASSWORD_PLACEHOLDER")

# Access the stored secret
DBT_PASSWORD = secret_block.get()
os.environ["DBT_PASSWORD"] = DBT_PASSWORD
```

This example `profiles.yml` file could then access that variable.

```yaml
profile:
  target: prod
  outputs:
    prod:
      type: postgres
      host: 127.0.0.1
      # IMPORTANT: Make sure to quote the entire Jinja string here
      user: dbt_user
      password: "{{ env_var('DBT_PASSWORD') }}"
```

#### Create a new `profiles.yml` file with blocks

If you don't have a `profiles.yml` file, you can use a DbtCliProfile block to create `profiles.yml`.
Then, specify `profiles_dir` where `profiles.yml` will be written.
Here's example code with placeholders:

```python
from prefect import flow
from prefect_dbt.cli import DbtCliProfile, DbtCoreOperation


@flow
def trigger_dbt_flow():
    dbt_cli_profile = DbtCliProfile.load("DBT-CORE-OPERATION-BLOCK-PLACEHOLDER")
    with DbtCoreOperation(
        commands=["dbt debug", "dbt run"],
        project_dir="PROJECT-DIRECTORY-PLACEHOLDER",
        profiles_dir="PROFILES-DIRECTORY-PLACEHOLDER",
        dbt_cli_profile=dbt_cli_profile,
    ) as dbt_operation:
        dbt_process = dbt_operation.trigger()
        # do other things before waiting for completion
        dbt_process.wait_for_completion()
        result = dbt_process.fetch_result()
    return result


if __name__ == "__main__":
    trigger_dbt_flow()
```

<Warning>
  **Supplying the `dbt_cli_profile` argument will overwrite existing `profiles.yml` files**

  If you already have a `profiles.yml` file in the specified `profiles_dir`, the file will be overwritten. If you do not specify a profiles directory, `profiles.yml` at `~/.dbt/` would be overwritten.
</Warning>

Visit the SDK reference in the side navigation to see other built-in `TargetConfigs` blocks.

If the desired service profile is not available, you can build one from the generic `TargetConfigs` class.

#### Programmatic Invocation

`prefect-dbt` has some pre-built tasks that use dbt's [programmatic invocation](https://docs.getdbt.com/reference/programmatic-invocations).

For example:

```python
from prefect import flow
from prefect_dbt.cli.tasks import from prefect import flow
from prefect_dbt.cli.commands import trigger_dbt_cli_command, dbt_build_task


@flow
def dbt_build_flow():
    trigger_dbt_cli_command(
        command="dbt deps", project_dir="/Users/test/my_dbt_project_dir",
    )
    dbt_build_task(
        project_dir = "/Users/test/my_dbt_project_dir",
        create_summary_artifact = True,
        summary_artifact_key = "dbt-build-task-summary",
        extra_command_args=["--select", "foo_model"]
    )


if __name__ == "__main__":
    dbt_build_flow()
```

See the [SDK docs](https://reference.prefect.io/prefect_dbt/) for other pre-built tasks.

##### Create a summary artifact

These pre-built tasks can also create artifacts. These artifacts have extra information about dbt Core runs, such as messages and compiled code for nodes that fail or have errors.

<img src="https://mintcdn.com/prefect-bd373955/9tQZbEaDbWbFiuGw/images/prefect-dbt-summary-artifact.png?fit=max&auto=format&n=9tQZbEaDbWbFiuGw&q=85&s=fc5044f3fd6b7e41bb5e74c74ac4ac09" alt="prefect-dbt Summary Artifact" data-og-width="597" width="597" data-og-height="933" height="933" data-path="images/prefect-dbt-summary-artifact.png" srcset="https://mintcdn.com/prefect-bd373955/9tQZbEaDbWbFiuGw/images/prefect-dbt-summary-artifact.png?w=280&fit=max&auto=format&n=9tQZbEaDbWbFiuGw&q=85&s=c21798df9da02ae1f5193423dca91cfd 280w, https://mintcdn.com/prefect-bd373955/9tQZbEaDbWbFiuGw/images/prefect-dbt-summary-artifact.png?w=560&fit=max&auto=format&n=9tQZbEaDbWbFiuGw&q=85&s=215c6897bf1c9f4e0d440058b7d1e73a 560w, https://mintcdn.com/prefect-bd373955/9tQZbEaDbWbFiuGw/images/prefect-dbt-summary-artifact.png?w=840&fit=max&auto=format&n=9tQZbEaDbWbFiuGw&q=85&s=dcc05662b0cf6a0d527d41ca9cd6a36f 840w, https://mintcdn.com/prefect-bd373955/9tQZbEaDbWbFiuGw/images/prefect-dbt-summary-artifact.png?w=1100&fit=max&auto=format&n=9tQZbEaDbWbFiuGw&q=85&s=caf563a85e6e5d1afec584a047958b17 1100w, https://mintcdn.com/prefect-bd373955/9tQZbEaDbWbFiuGw/images/prefect-dbt-summary-artifact.png?w=1650&fit=max&auto=format&n=9tQZbEaDbWbFiuGw&q=85&s=b750585c0911f67c5c83123a5415a0c6 1650w, https://mintcdn.com/prefect-bd373955/9tQZbEaDbWbFiuGw/images/prefect-dbt-summary-artifact.png?w=2500&fit=max&auto=format&n=9tQZbEaDbWbFiuGw&q=85&s=c8a9acb3fb00b0b45f2b13a6246cd3a1 2500w" data-optimize="true" data-opv="2" />

#### BigQuery CLI profile block example

To create dbt Core target config and profile blocks for BigQuery:

1. Save and load a `GcpCredentials` block.
2. Determine the schema / dataset you want to use in BigQuery.
3. Create a short script, replacing the placeholders.

```python
from prefect_gcp.credentials import GcpCredentials
from prefect_dbt.cli import BigQueryTargetConfigs, DbtCliProfile


credentials = GcpCredentials.load("CREDENTIALS-BLOCK-NAME-PLACEHOLDER")
target_configs = BigQueryTargetConfigs(
    schema="SCHEMA-NAME-PLACEHOLDER",  # also known as dataset
    credentials=credentials,
)
target_configs.save("TARGET-CONFIGS-BLOCK-NAME-PLACEHOLDER")

dbt_cli_profile = DbtCliProfile(
    name="PROFILE-NAME-PLACEHOLDER",
    target="TARGET-NAME-placeholder",
    target_configs=target_configs,
)
dbt_cli_profile.save("DBT-CLI-PROFILE-BLOCK-NAME-PLACEHOLDER")
```

To create a dbt Core operation block:

1. Determine the dbt commands you want to run.
2. Create a short script, replacing the placeholders.

```python
from prefect_dbt.cli import DbtCliProfile, DbtCoreOperation


dbt_cli_profile = DbtCliProfile.load("DBT-CLI-PROFILE-BLOCK-NAME-PLACEHOLDER")
dbt_core_operation = DbtCoreOperation(
    commands=["DBT-CLI-COMMANDS-PLACEHOLDER"],
    dbt_cli_profile=dbt_cli_profile,
    overwrite_profiles=True,
)
dbt_core_operation.save("DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER")
```

Load the saved block that holds your credentials:

```python
from prefect_dbt.cloud import DbtCoreOperation


DbtCoreOperation.load("DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER")
```

## Resources

For assistance using dbt, consult the [dbt documentation](https://docs.getdbt.com/docs/building-a-dbt-project/documentation).

Refer to the `prefect-dbt` [SDK documentation](https://reference.prefect.io/prefect_dbt/) to explore all the capabilities of the `prefect-dbt` library.

### Additional installation options

Additional installation options for dbt Core with BigQuery, Snowflake, and Postgres are shown below.

#### Additional capabilities for dbt Core and Snowflake profiles

First install the main library compatible with your Prefect version:

```bash
pip install "prefect[dbt]"
```

Then install the additional capabilities you need.

```bash
pip install "prefect-dbt[snowflake]"
```

#### Additional capabilities for dbt Core and BigQuery profiles

```bash
pip install "prefect-dbt[bigquery]"
```

#### Additional capabilities for dbt Core and Postgres profiles

```bash
pip install "prefect-dbt[postgres]"
```

Or, install all of the extras.

```bash
pip install -U "prefect-dbt[all_extras]"
```


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-dbt/sdk





# prefect-docker
Source: https://docs-3.prefect.io/integrations/prefect-docker/index



The `prefect-docker` library is required to create deployments that will submit runs to most Prefect work pool infrastructure types.

## Getting started

### Prerequisites

* [Docker installed](https://www.docker.com/) and running.

### Install `prefect-docker`

The following command will install a version of `prefect-docker` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[docker]"
```

Upgrade to the latest versions of `prefect` and `prefect-docker`:

```bash
pip install -U "prefect[docker]"
```

### Examples

See the Prefect [Workers docs](/v3/how-to-guides/deployment_infra/docker) to learn how to create and run deployments that use Docker.

## Resources

For assistance using Docker, consult the [Docker documentation](https://docs.docker.com/).

Refer to the `prefect-docker` [SDK documentation](https://reference.prefect.io/prefect_docker/) to explore all the capabilities of the `prefect-docker` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-docker/sdk





# prefect-email
Source: https://docs-3.prefect.io/integrations/prefect-email/index



The `prefect-email` library helps you send emails from your Prefect flows.

## Getting started

### Prerequisites

* Many email services, such as Gmail, require an [App Password](https://support.google.com/accounts/answer/185833) to successfully send emails.
  If you encounter an error similar to `smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted...`, it's likely you are not using an App Password.

### Install `prefect-email`

The following command will install a version of prefect-email compatible with your installed version of Prefect.
If you don't already have Prefect installed, it will install the newest version of Prefect as well.

```bash
pip install "prefect[email]"
```

Upgrade to the latest versions of Prefect and prefect-email:

```bash
pip install -U "prefect[email]"
```

### Register newly installed block types

Register the block types in the prefect-email module to make them available for use.

```bash
prefect block register -m prefect_email
```

## Save credentials to an EmailServerCredentials block

Save your email credentials to a block.
Replace the placeholders with your email address and password.

```python
from prefect_email import EmailServerCredentials


credentials = EmailServerCredentials(
    username="EMAIL-ADDRESS-PLACEHOLDER",
    password="PASSWORD-PLACEHOLDER",  # must be an application password
)
credentials.save("BLOCK-NAME-PLACEHOLDER")
```

In the examples below you load a credentials block to authenticate with the email server.

## Send emails

The code below shows how to send an email using the pre-built `email_send_message` [task](https://docs.prefect.io/latest/develop/write-tasks/).

```python
from prefect import flow
from prefect_email import EmailServerCredentials, email_send_message


@flow
def example_email_send_message_flow(email_addresses):
    email_server_credentials = EmailServerCredentials.load("BLOCK-NAME-PLACEHOLDER")
    for email_address in email_addresses:
        subject = email_send_message.with_options(name=f"email {email_address}").submit(
            email_server_credentials=email_server_credentials,
            subject="Example Flow Notification using Gmail",
            msg="This proves email_send_message works!",
            email_to=email_address,
        )


if __name__ == "__main__":
    example_email_send_message_flow(["EMAIL-ADDRESS-PLACEHOLDER"])
```

## Capture exceptions and send an email

This example demonstrates how to send an email notification with the details of the exception when a flow run fails.

`prefect-email` can be wrapped in an `except` statement to do just that!

```python
from prefect import flow
from prefect.context import get_run_context
from prefect_email import EmailServerCredentials, email_send_message


def notify_exc_by_email(exc):
    context = get_run_context()
    flow_run_name = context.flow_run.name
    email_server_credentials = EmailServerCredentials.load("email-server-credentials")
    email_send_message(
        email_server_credentials=email_server_credentials,
        subject=f"Flow run {flow_run_name!r} failed",
        msg=f"Flow run {flow_run_name!r} failed due to {exc}.",
        email_to=email_server_credentials.username,
    )

@flow
def example_flow():
    try:
        1 / 0
    except Exception as exc:
        notify_exc_by_email(exc)
        raise


if __name__ == "__main__":
    example_flow()
```

## Resources

Refer to the `prefect-email` [SDK documentation](https://reference.prefect.io/prefect_email/) to explore all the capabilities of the `prefect-email` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-email/sdk





# Google Cloud Run Worker Guide
Source: https://docs-3.prefect.io/integrations/prefect-gcp/gcp-worker-guide



## Why use Google Cloud Run for flow run execution?

Google Cloud Run is a fully managed compute platform that automatically scales your containerized applications.

1. Serverless architecture: Cloud Run follows a serverless architecture, which means you don't need to manage any underlying infrastructure. Google Cloud Run automatically handles the scaling and availability of your flow run infrastructure, allowing you to focus on developing and deploying your code.

2. Scalability: Cloud Run can automatically scale your pipeline to handle varying workloads and traffic. It can quickly respond to increased demand and scale back down during low activity periods, ensuring efficient resource utilization.

3. Integration with Google Cloud services: Google Cloud Run easily integrates with other Google Cloud services, such as Google Cloud Storage, Google Cloud Pub/Sub, and Google Cloud Build. This interoperability enables you to build end-to-end data pipelines that use a variety of services.

4. Portability: Since Cloud Run uses container images, you can develop your pipelines locally using Docker and then deploy them on Google Cloud Run without significant modifications. This portability allows you to run the same pipeline in different environments.

## Google Cloud Run guide

After completing this guide, you will have:

1. Created a Google Cloud Service Account
2. Created a Prefect Work Pool
3. Deployed a Prefect Worker as a Cloud Run Service
4. Deployed a Flow
5. Executed the Flow as a Google Cloud Run Job

### Prerequisites

Before starting this guide, make sure you have:

* A [Google Cloud Platform (GCP) account](https://cloud.google.com/gcp).
* A project on your GCP account where you have the necessary permissions to create Cloud Run Services and Service Accounts.
* The `gcloud` CLI installed on your local machine. You can follow Google Cloud's [installation guide](https://cloud.google.com/sdk/docs/install). If you're using Apple (or a Linux system) you can also use [Homebrew](https://formulae.brew.sh/cask/google-cloud-sdk) for installation.
* [Docker](https://www.docker.com/get-started/) installed on your local machine.
* A Prefect server instance. You can sign up for a forever free [Prefect Cloud Account](https://app.prefect.cloud/) or, alternatively, self-host a Prefect server.

### Step 1. Create a Google Cloud service account

First, open a terminal or command prompt on your local machine where `gcloud` is installed. If you haven't already authenticated with `gcloud`, run the following command and follow the instructions to log in to your GCP account.

```bash
gcloud auth login
```

Next, you'll set your project where you'd like to create the service account. Use the following command and replace `<PROJECT_ID>` with your GCP project's ID.

```bash
gcloud config set project <PROJECT-ID>
```

For example, if your project's ID is `prefect-project` the command will look like this:

```bash
gcloud config set project prefect-project
```

Now you're ready to make the service account. To do so, you'll need to run this command:

```bash
gcloud iam service-accounts create <SERVICE-ACCOUNT-NAME> --display-name="<DISPLAY-NAME>"
```

Here's an example of the command above which you can use which already has the service account name and display name provided. An additional option to describe the service account has also been added:

```bash
gcloud iam service-accounts create prefect-service-account \
    --description="service account to use for the prefect worker" \
    --display-name="prefect-service-account"
```

The last step of this process is to make sure the service account has the proper permissions to execute flow runs as Cloud Run jobs.
Run the following commands to grant the necessary permissions:

```bash
gcloud projects add-iam-policy-binding <PROJECT-ID> \
    --member="serviceAccount:<SERVICE-ACCOUNT-NAME>@<PROJECT-ID>.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountUser"
```

```bash
gcloud projects add-iam-policy-binding <PROJECT-ID> \
    --member="serviceAccount:<SERVICE-ACCOUNT-NAME>@<PROJECT-ID>.iam.gserviceaccount.com" \
    --role="roles/run.admin"
```

### Step 2. Create a Cloud Run work pool

Let's walk through the process of creating a Cloud Run work pool.

#### Fill out the work pool base job template

You can create a new work pool using the Prefect UI or CLI. The following command creates a work pool of type `cloud-run` via the CLI (you'll want to replace the `<WORK-POOL-NAME>` with the name of your work pool):

```bash
prefect work-pool create --type cloud-run <WORK-POOL-NAME>
```

Once the work pool is created, find the work pool in the UI and edit it.

There are many ways to customize the base job template for the work pool. Modifying the template influences the infrastructure configuration that the worker provisions for flow runs submitted to the work pool. For this guide we are going to modify just a few of the available fields.

Specify the region for the cloud run job.

<img src="https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-region.png?fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=e1861cc3e5c99b011882a246cc11e597" alt="region" data-og-width="461" width="461" data-og-height="111" height="111" data-path="images/cloud-run-work-pool-region.png" srcset="https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-region.png?w=280&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=d9021b8bb318477876894b43bca0ea06 280w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-region.png?w=560&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=a97dc4dd4379a0ed8d702a44eb991e10 560w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-region.png?w=840&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=424169eb3bfba32e5751ffdbb0b8cbc6 840w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-region.png?w=1100&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=7784ffebdd8a5e9caaa0c15717016e9d 1100w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-region.png?w=1650&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=7e2a0846b584bcfd3682bc47765c105b 1650w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-region.png?w=2500&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=fc292a690bee4b17fd7f58d1b1c38940 2500w" data-optimize="true" data-opv="2" />

Save the name of the service account created in first step of this guide.

<img src="https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-service-account-name.png?fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=f5c7ec0746ae7f5a2756eec666d83f61" alt="name" data-og-width="1225" width="1225" data-og-height="124" height="124" data-path="images/cloud-run-work-pool-service-account-name.png" srcset="https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-service-account-name.png?w=280&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=2188b818a427bb67a9f691abb54eda1e 280w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-service-account-name.png?w=560&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=cf74c609544f4bc1395ea893d541390b 560w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-service-account-name.png?w=840&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=ce35cfe3a5c3c5e4cb4c394b90dd1bd7 840w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-service-account-name.png?w=1100&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=c77fb3616291a1bf13a0d03660488be1 1100w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-service-account-name.png?w=1650&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=71952a120cdb6e59c49f697e8a08ca20 1650w, https://mintcdn.com/prefect-bd373955/LVZNr0ZLDFWJ9-DE/images/cloud-run-work-pool-service-account-name.png?w=2500&fit=max&auto=format&n=LVZNr0ZLDFWJ9-DE&q=85&s=3ff6812333cbc505b1aadb8b046fcb08 2500w" data-optimize="true" data-opv="2" />

Your work pool is now ready to receive scheduled flow runs!

### Step 3. Deploy a Cloud Run worker

Now you can launch a Cloud Run service to host the Cloud Run worker. This worker will poll the work pool that you created in the previous step.

Navigate back to your terminal and run the following commands to set your Prefect API key and URL as environment variables.
Be sure to replace `<ACCOUNT-ID>` and `<WORKSPACE-ID>` with your Prefect account and workspace IDs (both will be available in the URL of the UI when previewing the workspace dashboard).
You'll want to replace `<YOUR-API-KEY>` with an active API key as well.

```bash
export PREFECT_API_URL='https://api.prefect.cloud/api/accounts/<ACCOUNT-ID>/workspaces/<WORKSPACE-ID>'
export PREFECT_API_KEY='<YOUR-API-KEY>'
```

Once those variables are set, run the following shell command to deploy your worker as a service.
Don't forget to replace `<YOUR-SERVICE-ACCOUNT-NAME>` with the name of the service account you created in the first step of this guide, and replace `<WORK-POOL-NAME>` with the name of the work pool you created in the second step.

```bash
gcloud run deploy prefect-worker --image=prefecthq/prefect:3-latest \
--set-env-vars PREFECT_API_URL=$PREFECT_API_URL,PREFECT_API_KEY=$PREFECT_API_KEY \
--service-account <YOUR-SERVICE-ACCOUNT-NAME> \
--no-cpu-throttling \
--min-instances 1 \
--startup-probe httpGet.port=8080,httpGet.path=/health,initialDelaySeconds=100,periodSeconds=20,timeoutSeconds=20 \
--args "prefect","worker","start","--install-policy","always","--with-healthcheck","-p","<WORK-POOL-NAME>","-t","cloud-run"
```

After running this command, you'll be prompted to specify a region. Choose the same region that you selected when creating the Cloud Run work pool in the second step of this guide.
The next prompt will ask if you'd like to allow unauthenticated invocations to your worker. For this guide, you can select "No".

After a few seconds, you'll be able to see your new `prefect-worker` service by navigating to the Cloud Run page of your Google Cloud console. Additionally, you should be able to see a record of this worker in the Prefect UI on the work pool's page by navigating to the `Worker` tab.
Let's not leave our worker hanging, it's time to give it a job.

### Step 4. Deploy a flow

Let's prepare a flow to run as a Cloud Run job. In this section of the guide, we'll "bake" our code into a Docker image, and push that image to Google Artifact Registry.

### Create a registry

Let's create a docker repository in your Google Artifact Registry to host your custom image. If you already have a registry, and are authenticated to it, skip ahead to the *Write a flow* section.

The following command creates a repository using the gcloud CLI. You'll want to replace the `<REPOSITORY-NAME>` with your own value. :

```bash
gcloud artifacts repositories create <REPOSITORY-NAME> \
--repository-format=docker --location=us
```

Now you can authenticate to artifact registry:

```bash
gcloud auth configure-docker us-docker.pkg.dev
```

### Write a flow

First, create a new directory. This will serve as the root of your project's repository. Within the directory, create a sub-directory called `flows`.
Navigate to the `flows` subdirectory and create a new file for your flow. Feel free to write your own flow, but here's a ready-made one for your convenience:

```python
import httpx
from prefect import flow, task
from prefect.artifacts import create_markdown_artifact

@task
def mark_it_down(temp):
    markdown_report = f"""# Weather Report
## Recent weather

| Time      | Temperature |
| :-------- | ----------: |
| Now       |      {temp} |
| In 1 hour |  {temp + 2} |
"""
    create_markdown_artifact(
        key="weather-report",
        markdown=markdown_report,
        description="Very scientific weather report",
    )


@flow
def fetch_weather(lat: float, lon: float):
    base_url = "https://api.open-meteo.com/v1/forecast/"
    weather = httpx.get(
        base_url,
        params=dict(latitude=lat, longitude=lon, hourly="temperature_2m"),
    )
    most_recent_temp = float(weather.json()["hourly"]["temperature_2m"][0])
    mark_it_down(most_recent_temp)


if __name__ == "__main__":
    fetch_weather(38.9, -77.0)
```

In the remainder of this guide, this script will be referred to as `weather_flow.py`, but you can name yours whatever you'd like.

#### Creating a `prefect.yaml` file

Now we're ready to make a `prefect.yaml` file, which will be responsible for managing the deployments of this repository.
**Navigate back to the root of your directory**, and run the following command to create a `prefect.yaml` file using Prefect's docker deployment recipe.

```bash
prefect init --recipe docker
```

You'll receive a prompt to put in values for the image name and tag. Since we will be pushing the image to Google Artifact Registry, the name of your image should be prefixed with the path to the docker repository you created within the registry. For example: `us-docker.pkg.dev/<PROJECT-ID>/<REPOSITORY-NAME>/`. You'll want to replace `<PROJECT-ID>` with the ID of your project in GCP. This should match the ID of the project you used in first step of this guide. Here is an example of what this could look like:

```bash
image_name: us-docker.pkg.dev/prefect-project/my-artifact-registry/gcp-weather-image
tag: latest
```

At this point, there will be a new `prefect.yaml` file available at the root of your project. The contents will look similar to the example below, however, we've added in a combination of YAML templating options and Prefect deployment actions to build out a simple CI/CD process. Feel free to copy the contents and paste them in your prefect.yaml:

```yaml
# Welcome to your prefect.yaml file! You can you this file for storing and managing
# configuration for deploying your flows. We recommend committing this file to source
# control along with your flow code.

# Generic metadata about this project
name: <WORKING-DIRECTORY>
prefect-version: 3.0.0

# build section allows you to manage and build docker image
build:
- prefect_docker.deployments.steps.build_docker_image:
    id: build_image
    requires: prefect-docker>=0.3.1
    image_name: <PATH-TO-ARTIFACT-REGISTRY>/gcp-weather-image
    tag: latest
    dockerfile: auto
    platform: linux/amd64

# push section allows you to manage if and how this project is uploaded to remote locations
push:
- prefect_docker.deployments.steps.push_docker_image:
    requires: prefect-docker>=0.3.1
    image_name: '{{ build_image.image_name }}'
    tag: '{{ build_image.tag }}'

# pull section allows you to provide instructions for cloning this project in remote locations
pull:
- prefect.deployments.steps.set_working_directory:
    directory: /opt/prefect/<WORKING-DIRECTORY>

# the deployments section allows you to provide configuration for deploying flows
deployments:
- name: gcp-weather-deploy
  version: null
  tags: []
  description: null
  schedule: {}
  flow_name: null
  entrypoint: flows/weather_flow.py:fetch_weather
  parameters:
    lat: 14.5994
    lon: 28.6731
  work_pool:
    name: my-cloud-run-pool
    work_queue_name: default
    job_variables:
      image: '{{ build_image.image }}'
```

<Tip>
  After copying the example above, don't forget to replace `<WORKING-DIRECTORY>` with the name of the directory where your flow folder and `prefect.yaml` live. You'll also need to replace `<PATH-TO-ARTIFACT-REGISTRY>` with the path to the Docker repository in your Google Artifact Registry.
</Tip>

To get a better understanding of the different components of the `prefect.yaml` file above and what they do, feel free to read this next section. Otherwise, you can skip ahead to *Flow Deployment*.

In the `build` section of the `prefect.yaml` the following step is executed at deployment build time:

1. `prefect_docker.deployments.steps.build_docker_image` : builds a Docker image automatically which uses the name and tag chosen previously.

<Warning>
  If you are using an ARM-based chip (such as an M1 or M2 Mac), you'll want to ensure that you add `platform: linux/amd64` to your `build_docker_image` step to ensure that your docker image uses an AMD architecture. For example:

  ```yaml
  - prefect_docker.deployments.steps.build_docker_image:
  id: build_image
  requires: prefect-docker>=0.3.1
  image_name: us-docker.pkg.dev/prefect-project/my-docker-repository/gcp-weather-image
  tag: latest
  dockerfile: auto
  platform: linux/amd64
  ```
</Warning>

The `push` section sends the Docker image to the Docker repository in your Google Artifact Registry, so that it can be easily accessed by the worker for flow run execution.

The `pull` section sets the working directory for the process prior to importing your flow.

In the `deployments` section of the `prefect.yaml` file above, you'll see that there is a deployment declaration named `gcp-weather-deploy`. Within the declaration, the entrypoint for the flow is specified along with some default parameters which will be passed to the flow at runtime. Last but not least, the name of the work pool that we created in step 2 of this guide is specified.

#### Flow deployment

Once you're happy with the specifications in the `prefect.yaml` file, run the following command in the terminal to deploy your flow:

```bash
prefect deploy --name gcp-weather-deploy
```

Once the flow is deployed to Prefect Cloud or your local Prefect Server, it's time to queue up a flow run!

### Step 5. Flow execution

Find your deployment in the UI, and hit the *Quick Run* button.
You have now successfully submitted a flow run to your Cloud Run worker!
If you used the flow script provided in this guide, check the *Artifacts* tab for the flow run once it completes.
You'll have a nice little weather report waiting for you there. Hope your day is a sunny one!

### Recap and next steps

Congratulations on completing this guide! Looking back on our journey, you have:

1. Created a Google Cloud service account
2. Created a Cloud Run work pool
3. Deployed a Cloud Run worker
4. Deployed a flow
5. Executed a flow

For next steps, take a look at some of the other [work pools](/v3/how-to-guides/deployment_infra/serverless) Prefect has to offer.

The world is your oyster 🦪✨.


# prefect-gcp
Source: https://docs-3.prefect.io/integrations/prefect-gcp/index



`prefect-gcp` helps you leverage the capabilities of Google Cloud Platform (GCP) in your workflows.
For example, you can run flows on Vertex AI or Cloud Run, read and write data to BigQuery and Cloud Storage, and retrieve secrets with Secret Manager.

## Getting started

### Prerequisites

* A [GCP account](https://cloud.google.com/) and the necessary permissions to access desired services.

### Install `prefect-gcp`

Install `prefect-gcp` as an extra of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

<CodeGroup>
  ```bash pip
  pip install -U "prefect[gcp]"
  ```

  ```bash uv
  uv pip install -U "prefect[gcp]"
  ```
</CodeGroup>

If using BigQuery, Cloud Storage, Secret Manager, or Vertex AI, see [additional installation options](#install-extras).

#### Install extras

To install `prefect-gcp` with all additional capabilities, run the install command above and then run the following command:

<CodeGroup>
  ```bash pip
  pip install -U "prefect-gcp[all_extras]"
  ```

  ```bash uv
  uv pip install -U "prefect-gcp[all_extras]"
  ```
</CodeGroup>

Or, install extras individually:

<CodeGroup>
  ```bash pip
  # Use Cloud Storage
  pip install -U "prefect-gcp[cloud_storage]"

  # Use BigQuery
  pip install -U "prefect-gcp[bigquery]"

  # Use Secret Manager
  pip install -U "prefect-gcp[secret_manager]"

  # Use Vertex AI
  pip install -U "prefect-gcp[aiplatform]"
  ```

  ```bash uv
  # Use Cloud Storage
  uv pip install -U "prefect-gcp[cloud_storage]"

  # Use BigQuery
  uv pip install -U "prefect-gcp[bigquery]"

  # Use Secret Manager
  uv pip install -U "prefect-gcp[secret_manager]"

  # Use Vertex AI
  uv pip install -U "prefect-gcp[aiplatform]"
  ```
</CodeGroup>

### Register newly installed block types

Register the block types in the module to make them available for use.

```bash
prefect block register -m prefect_gcp
```

## Blocks setup

### Credentials

Authenticate with a service account to use `prefect-gcp` services.

1. Refer to the [GCP service account documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) to create and download a service account key file.
2. Copy the JSON contents.
3. Use the Python code below, replace the placeholders with your information.

```python
from prefect_gcp import GcpCredentials

# replace this PLACEHOLDER dict with your own service account info
service_account_info = {
  "type": "service_account",
  "project_id": "PROJECT_ID",
  "private_key_id": "KEY_ID",
  "private_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
  "client_email": "SERVICE_ACCOUNT_EMAIL",
  "client_id": "CLIENT_ID",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL"
}

GcpCredentials(
    service_account_info=service_account_info
).save("CREDENTIALS-BLOCK-NAME")
```

This credential block can be used to create other `prefect_gcp` blocks.

<Warning>
  **`service_account_info` vs `service_account_file`**

  The advantage of using `service_account_info`, instead of `service_account_file`, is that it is accessible across containers.

  If `service_account_file` is used, the provided path *must be available* in the container executing the flow.
</Warning>

### BigQuery

Read data from and write to Google BigQuery within your Prefect flows.

Be sure to [install](#install-extras) `prefect-gcp` with the BigQuery extra.

```python
from prefect_gcp.bigquery import GcpCredentials, BigQueryWarehouse

gcp_credentials = GcpCredentials.load("CREDENTIALS-BLOCK-NAME")

bigquery_block = BigQueryWarehouse(
    gcp_credentials = gcp_credentials,
    fetch_size = 1  # Optional: specify a default number of rows to fetch when calling fetch_many
)
bigquery_block.save("BIGQUERY-BLOCK-NAME")
```

### Secret Manager

Manage secrets in Google Cloud Platform's Secret Manager.

```python
from prefect_gcp import GcpCredentials, GcpSecret
gcp_credentials = GcpCredentials.load("CREDENTIALS-BLOCK-NAME")

gcp_secret = GcpSecret(
    secret_name = "your-secret-name",
    secret_version = "latest",
    gcp_credentials = gcp_credentials
)

gcp_secret.save("SECRET-BLOCK-NAME")
```

### Cloud Storage

Create a block to interact with a GCS bucket.

```python
from prefect_gcp import GcpCredentials, GcsBucket

gcs_bucket = GcsBucket(
    bucket="BUCKET-NAME",
    gcp_credentials=GcpCredentials.load("BIGQUERY-BLOCK-NAME")
)
gcs_bucket.save("GCS-BLOCK-NAME")

```

## Run flows on Google Cloud Run or Vertex AI

Run flows on [Google Cloud Run](https://cloud.google.com/run) or [Vertex AI](https://cloud.google.com/vertex-ai) to dynamically scale your infrastructure.

Prefect Cloud offers [Google Cloud Run push work pools](/v3/how-to-guides/deployment_infra/serverless). Push work pools submit runs directly to Google Cloud Run, instead of requiring a worker to actively poll for flow runs to execute.

See the [Google Cloud Run Worker Guide](/integrations/prefect-gcp/gcp-worker-guide) for a walkthrough of using Google Cloud Run in a hybrid work pool.

## Examples

### Interact with BigQuery

This code creates a new dataset in BigQuery, defines a table, insert rows, and fetches data from the table:

```python
from prefect import flow
from prefect_gcp.bigquery import GcpCredentials, BigQueryWarehouse

@flow
def bigquery_flow():
    all_rows = []
    gcp_credentials = GcpCredentials.load("CREDENTIALS-BLOCK-NAME")

    client = gcp_credentials.get_bigquery_client()
    client.create_dataset("test_example", exists_ok=True)

    with BigQueryWarehouse(gcp_credentials=gcp_credentials) as warehouse:
        warehouse.execute(
            "CREATE TABLE IF NOT EXISTS test_example.customers (name STRING, address STRING);"
        )
        warehouse.execute_many(
            "INSERT INTO test_example.customers (name, address) VALUES (%(name)s, %(address)s);",
            seq_of_parameters=[
                {"name": "Marvin", "address": "Highway 42"},
                {"name": "Ford", "address": "Highway 42"},
                {"name": "Unknown", "address": "Highway 42"},
            ],
        )
        while True:
            # Repeated fetch* calls using the same operation will
            # skip re-executing and instead return the next set of results
            new_rows = warehouse.fetch_many("SELECT * FROM test_example.customers", size=2)
            if len(new_rows) == 0:
                break
            all_rows.extend(new_rows)
    return all_rows


if __name__ == "__main__":
    bigquery_flow()
```

### Use Prefect with Google Cloud Storage

Interact with Google Cloud Storage.

The code below uses `prefect_gcp` to upload a file to a Google Cloud Storage bucket and download the same file under a different filename.

```python
from pathlib import Path
from prefect import flow
from prefect_gcp import GcpCredentials, GcsBucket


@flow
def cloud_storage_flow():
    # create a dummy file to upload
    file_path = Path("test-example.txt")
    file_path.write_text("Hello, Prefect!")

    gcp_credentials = GcpCredentials.load("CREDENTIALS-BLOCK-NAME")
    gcs_bucket = GcsBucket(
        bucket="BUCKET-NAME",
        gcp_credentials=gcp_credentials
    )

    gcs_bucket_path = gcs_bucket.upload_from_path(file_path)
    downloaded_file_path = gcs_bucket.download_object_to_path(
        gcs_bucket_path, "downloaded-test-example.txt"
    )
    return downloaded_file_path.read_text()


if __name__ == "__main__":
    cloud_storage_flow()
```

<Info>
  **Upload and download directories**

  `GcsBucket` supports uploading and downloading entire directories.
</Info>

### Save secrets with Google Secret Manager

Read and write secrets with Google Secret Manager.

Be sure to [install](#instal-prefect-gcp) `prefect-gcp` with the Secret Manager extra.

The code below writes a secret to the Secret Manager, reads the secret data, and deletes the secret.

```python
from prefect import flow
from prefect_gcp import GcpCredentials, GcpSecret


@flow
def secret_manager_flow():
    gcp_credentials = GcpCredentials.load("CREDENTIALS-BLOCK-NAME")
    gcp_secret = GcpSecret(secret_name="test-example", gcp_credentials=gcp_credentials)
    gcp_secret.write_secret(secret_data=b"Hello, Prefect!")
    secret_data = gcp_secret.read_secret()
    gcp_secret.delete_secret()
    return secret_data


if __name__ == "__main__":
    secret_manager_flow()
```

## Resources

For assistance using GCP, consult the [Google Cloud documentation](https://cloud.google.com/docs).

GCP can also authenticate without storing credentials in a block.
See [Access third-party secrets](/v3/develop/secrets) for an example that uses AWS Secrets Manager and Snowflake.

Refer to the `prefect-gcp` [SDK documentation](https://reference.prefect.io/prefect_gcp/) to explore all of the capabilities of the `prefect-gcp` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-gcp/sdk





# prefect-github
Source: https://docs-3.prefect.io/integrations/prefect-github/index



Prefect-github makes it easy to interact with GitHub repositories and use GitHub credentials.

## Getting started

### Prerequisites

* A [GitHub account](https://github.com/).

### Install `prefect-github`

The following command will install a version of `prefect-github` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[github]"
```

Upgrade to the latest versions of `prefect` and `prefect-github`:

```bash
pip install -U "prefect[github]"
```

### Register newly installed block types

Register the block types in the `prefect-github` module to make them available for use.

```bash
prefect block register -m prefect_github
```

## Examples

In the examples below, you create blocks with Python code.
Alternatively, blocks can be created through the Prefect UI.

To create a deployment and run a deployment where the flow code is stored in a private GitHub repository, you can use the `GitHubCredentials` block.

A deployment can use flow code stored in a GitHub repository without using this library in either of the following cases:

* The repository is public
* The deployment uses a [Secret block](https://docs.prefect.io/latest/develop/blocks/) to store the token

Code to create a GitHub Credentials block:

```python
from prefect_github import GitHubCredentials


github_credentials_block = GitHubCredentials(token="my_token")
github_credentials_block.save(name="my-github-credentials-block")
```

### Access flow code stored in a private GitHub repository in a deployment

Use the credentials block you created above to pass the GitHub access token during deployment creation. The code below assumes there's flow code stored in a private GitHub repository.

```python
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect_github import GitHubCredentials


if __name__ == "__main__":

    source = GitRepository(
        url="https://github.com/org/private-repo.git",
        credentials=GitHubCredentials.load("my-github-credentials-block")
    )

    flow.from_source(source=source, entrypoint="my_file.py:my_flow").deploy(
        name="private-github-deploy",
        work_pool_name="my_pool",
    )
```

Alternatively, if you use a `prefect.yaml` file to create the deployment, reference the GitHub Credentials block in the `pull` step:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/org/repo.git
        credentials: "{{ prefect.blocks.github-credentials.my-github-credentials-block }}"
```

### Interact with a GitHub repository

You can use prefect-github to create and retrieve issues and PRs from a repository.
Here's an example of adding a star to a GitHub repository:

```python
from prefect import flow
from prefect_github import GitHubCredentials
from prefect_github.repository import query_repository
from prefect_github.mutations import add_star_starrable


@flow()
def github_add_star_flow():
    github_credentials = GitHubCredentials.load("github-token")
    repository_id = query_repository(
        "PrefectHQ",
        "Prefect",
        github_credentials=github_credentials,
        return_fields="id"
    )["id"]
    starrable = add_star_starrable(
        repository_id,
        github_credentials
    )
    return starrable


if __name__ == "__main__":
    github_add_star_flow()
```

## Resources

For assistance using GitHub, consult the [GitHub documentation](https://docs.github.com).

Refer to the `prefect-github` [SDK documentation](https://reference.prefect.io/prefect_github/) to explore all the capabilities of the `prefect-github` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-github/sdk





# prefect-gitlab
Source: https://docs-3.prefect.io/integrations/prefect-gitlab/index



The prefect-gitlab library makes it easy to interact with GitLab repositories and credentials.

## Getting started

### Prerequisites

* A [GitLab account](https://gitlab.com/).

### Install `prefect-gitlab`

The following command will install a version of `prefect-gitlab` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[gitlab]"
```

Upgrade to the latest versions of `prefect` and `prefect-gitlab`:

```bash
pip install -U "prefect[gitlab]"
```

### Register newly installed block types

Register the block types in the `prefect-gitlab` module to make them available for use.

```bash
prefect block register -m prefect_gitlab
```

## Examples

In the examples below, you create blocks with Python code.
Alternatively, blocks can be created through the Prefect UI.

## Store deployment flow code in a private GitLab repository

To create a deployment where the flow code is stored in a private GitLab repository, you can use the `GitLabCredentials` block.

A deployment can use flow code stored in a GitLab repository without using this library in either of the following cases:

* The repository is public
* The deployment uses a [Secret block](https://docs.prefect.io/latest/develop/blocks/) to store the token

Code to create a GitLab Credentials block:

```python
from prefect_gitlab import GitLabCredentials


gitlab_credentials_block = GitLabCredentials(token="my_token")
gitlab_credentials_block.save(name="my-gitlab-credentials-block")
```

### Access flow code stored in a private GitLab repository in a deployment

Use the credentials block you created above to pass the GitLab access token during deployment creation. The code below assumes there's flow code in your private GitLab repository.

```python
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect_gitlab import GitLabCredentials


if __name__ == "__main__":

    source = GitRepository(
        url="https://gitlab.com/org/private-repo.git",
        credentials=GitLabCredentials.load("my-gitlab-credentials-block")
    )

    source = GitRepository(
    flow.from_source(
        source=source,
        entrypoint="my_file.py:my_flow",
    ).deploy(
        name="private-gitlab-deploy",
        work_pool_name="my_pool",
    )
```

Alternatively, if you use a `prefect.yaml` file to create the deployment, reference the GitLab Credentials block in the `pull` step:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/org/repo.git
        credentials: "{{ prefect.blocks.gitlab-credentials.my-gitlab-credentials-block }}"
```

### Interact with a GitLab repository

The code below shows how to reference a particular branch or tag of a GitLab repository.

```python
from prefect_gitlab import GitLabRepository


def save_private_gitlab_block():
    private_gitlab_block = GitLabRepository(
        repository="https://gitlab.com/testing/my-repository.git",
        access_token="YOUR_GITLAB_PERSONAL_ACCESS_TOKEN",
        reference="branch-or-tag-name",
    )

    private_gitlab_block.save("my-private-gitlab-block")


if __name__ == "__main__":
    save_private_gitlab_block()
```

Exclude the `access_token` field if the repository is public and exclude the `reference` field to use the default branch.

Use the newly created block to interact with the GitLab repository.

For example, download the repository contents with the `.get_directory()` method like this:

```python
from prefect_gitlab.repositories import GitLabRepository


def fetch_repo():
    private_gitlab_block = GitLabRepository.load("my-gitlab-block")
    private_gitlab_block.get_directory()


if __name__ == "__main__":
    fetch_repo()
```

## Resources

For assistance using GitLab, consult the [GitLab documentation](https://gitlab.com).

Refer to the `prefect-gitlab` [SDK documentation](https://reference.prefect.io/prefect_gitlab/) to explore all the capabilities of the `prefect-gitlab` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-gitlab/sdk





# prefect-kubernetes
Source: https://docs-3.prefect.io/integrations/prefect-kubernetes/index



`prefect-kubernetes` contains Prefect tasks, flows, and blocks enabling orchestration, observation and management of Kubernetes resources.

This library is most commonly used for installation with a Kubernetes worker. See the [Prefect docs on deploying with Kubernetes](/v3/how-to-guides/deployment_infra/kubernetes) to learn how to create and run deployments in Kubernetes.

Prefect provides a Helm chart for deploying a worker, a self-hosted Prefect server instance, and other resources to a Kubernetes cluster. See the [Prefect Helm chart](https://github.com/PrefectHQ/prefect-helm) for more information.

## Getting started

### Prerequisites

* [Kubernetes installed](https://kubernetes.io/).

### Install `prefect-kubernetes`

The following command will install a version of `prefect-kubernetes` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[kubernetes]"
```

Upgrade to the latest versions of `prefect` and `prefect-kubernetes`:

```bash
pip install -U "prefect[kubernetes]"
```

### Register newly installed block types

Register the block types in the `prefect-kubernetes` module to make them available for use.

```bash
prefect block register -m prefect_kubernetes
```

## Examples

### Use `with_options` to customize options on an existing task or flow

```python
from prefect_kubernetes.flows import run_namespaced_job

customized_run_namespaced_job = run_namespaced_job.with_options(
    name="My flow running a Kubernetes Job",
    retries=2,
    retry_delay_seconds=10,
) # this is now a new flow object that can be called
```

### Specify and run a Kubernetes Job from a YAML file

```python
from prefect import flow, get_run_logger
from prefect_kubernetes.credentials import KubernetesCredentials
from prefect_kubernetes.flows import run_namespaced_job # this is a flow
from prefect_kubernetes.jobs import KubernetesJob

k8s_creds = KubernetesCredentials.load("k8s-creds")

job = KubernetesJob.from_yaml_file( # or create in the UI with a dict manifest
    credentials=k8s_creds,
    manifest_path="path/to/job.yaml",
)

job.save("my-k8s-job", overwrite=True)


@flow
def kubernetes_orchestrator():
    # run the flow and send logs to the parent flow run's logger
    logger = get_run_logger()
    run_namespaced_job(job, print_func=logger.info)


if __name__ == "__main__":
    kubernetes_orchestrator()
```

As with all Prefect flows and tasks, you can call the underlying function directly if you don't need Prefect features:

```python
run_namespaced_job.fn(job, print_func=print)
```

### Generate a resource-specific client from `KubernetesClusterConfig`

```python
# with minikube / docker desktop & a valid ~/.kube/config this should ~just work~
from prefect_kubernetes.credentials import KubernetesCredentials, KubernetesClusterConfig

k8s_config = KubernetesClusterConfig.from_file('~/.kube/config')

k8s_credentials = KubernetesCredentials(cluster_config=k8s_config)

with k8s_credentials.get_client("core") as v1_core_client:
    for namespace in v1_core_client.list_namespace().items:
        print(namespace.metadata.name)
```

### List jobs in a namespace

```python
from prefect import flow
from prefect_kubernetes.credentials import KubernetesCredentials
from prefect_kubernetes.jobs import list_namespaced_job


@flow
def kubernetes_orchestrator():
    v1_job_list = list_namespaced_job(
        kubernetes_credentials=KubernetesCredentials.load("k8s-creds"),
        namespace="my-namespace",
    )
```

For assistance using Kubernetes, consult the [Kubernetes documentation](https://kubernetes.io/).

Refer to the `prefect-kubernetes` [SDK documentation](https://reference.prefect.io/prefect_kubernetes/) to explore all the capabilities of the `prefect-kubernetes` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-kubernetes/sdk





# prefect-ray
Source: https://docs-3.prefect.io/integrations/prefect-ray/index

Accelerate your workflows by running tasks in parallel with Ray

[Ray](https://docs.ray.io/en/latest/index.html) can run your tasks in parallel by distributing them over multiple machines.
The `prefect-ray` integration makes it easy to accelerate your flow runs with Ray.

## Install `prefect-ray`

The following command will install a version of `prefect-ray` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[ray]"
```

Upgrade to the latest versions of `prefect` and `prefect-ray`:

```bash
pip install -U "prefect[ray]"
```

<Warning>
  **Ray limitations**

  There are a few limitations with Ray:

  * Ray has [experimental](https://docs.ray.io/en/latest/ray-overview/installation.html#install-nightlies) support for Python 3.13, but Prefect [does *not* currently support](https://github.com/PrefectHQ/prefect/issues/16910) Python 3.13.
  * Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from `pip` alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with `conda`. See the [Ray documentation](https://docs.ray.io/en/latest/ray-overview/installation.html#m1-mac-apple-silicon-support) for instructions.
  * Ray support for Windows is currently in beta.

  See the [Ray installation documentation](https://docs.ray.io/en/latest/ray-overview/installation.html) for further compatibility information.
</Warning>

## Run tasks on Ray

The `RayTaskRunner` is a [Prefect task runner](https://docs.prefect.io/develop/task-runners/) that submits tasks to [Ray](https://www.ray.io/) for parallel execution.
By default, a temporary Ray instance is created for the duration of the flow run.
For example, this flow counts to three in parallel:

```python
import time

from prefect import flow, task
from prefect_ray import RayTaskRunner

@task
def shout(number):
    time.sleep(0.5)
    print(f"#{number}")

@flow(task_runner=RayTaskRunner)
def count_to(highest_number):
    shout.map(range(highest_number)).wait()

if __name__ == "__main__":
    count_to(10)

# outputs
#3
#7
#2
#6
#4
#0
#1
#5
#8
#9
```

If you already have a Ray instance running, you can provide the connection URL via an `address` argument.

To configure your flow to use the `RayTaskRunner`:

1. Make sure the `prefect-ray` collection is installed as described earlier: `pip install prefect-ray`.
2. In your flow code, import `RayTaskRunner` from `prefect_ray.task_runners`.
3. Assign it as the task runner when the flow is defined using the `task_runner=RayTaskRunner` argument.

For example, this flow uses the `RayTaskRunner` with a local, temporary Ray instance created by Prefect at flow run time.

```python
from prefect import flow
from prefect_ray.task_runners import RayTaskRunner

@flow(task_runner=RayTaskRunner())
def my_flow():
    ...
```

This flow uses the `RayTaskRunner` configured to access an existing Ray instance at `ray://<head_node_host>:10001`.

```python
from prefect import flow
from prefect_ray.task_runners import RayTaskRunner

@flow(
    task_runner=RayTaskRunner(
        address="ray://<head_node_host>:10001",
        init_kwargs={"runtime_env": {"pip": ["prefect-ray"]}},
    )
)
def my_flow():
    ...
```

`RayTaskRunner` accepts the following optional parameters:

| Parameter    | Description                                                                                                                         |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| address      | Address of a currently running Ray instance, starting with the [ray://](https://docs.ray.io/en/master/cluster/ray-client.html) URI. |
| init\_kwargs | Additional kwargs to use when calling `ray.init`.                                                                                   |

The Ray client uses the [ray://](https://docs.ray.io/en/master/cluster/ray-client.html) URI to indicate the address of a Ray instance.
If you don't provide the `address` of a Ray instance, Prefect creates a temporary instance automatically.

## Run tasks on a remote Ray cluster

When using the `RayTaskRunner` with a remote Ray cluster, you may run into issues that are not seen when using a local Ray instance.
To resolve these issues, we recommend taking the following steps when working with a remote Ray cluster:

1. By default, Prefect will not persist any data to the filesystem of the remote ray worker. However, if you want to take advantage of Prefect's caching ability, you will need to configure a remote result storage to persist results across task runs.

We recommend using the [Prefect UI to configure a storage block](https://docs.prefect.io/develop/blocks/) to use for remote results storage.

Here's an example of a flow that uses caching and remote result storage:

```python
from typing import List

from prefect import flow, task
from prefect.logging import get_run_logger
from prefect.tasks import task_input_hash
from prefect_aws import S3Bucket
from prefect_ray.task_runners import RayTaskRunner


# The result of this task will be cached in the configured result storage
@task(cache_key_fn=task_input_hash)
def say_hello(name: str) -> None:
    logger = get_run_logger()
    # This log statement will print only on the first run. Subsequent runs will be cached.
    logger.info(f"hello {name}!")
    return name


@flow(
    task_runner=RayTaskRunner(
        address="ray://<instance_public_ip_address>:10001",
    ),
    # Using an S3 block that has already been created via the Prefect UI
    result_storage="s3/my-result-storage",
)
def greetings(names: List[str]) -> None:
    say_hello.map(names).wait()


if __name__ == "__main__":
    greetings(["arthur", "trillian", "ford", "marvin"])
```

2. If you get an error stating that the module 'prefect' cannot be found, ensure `prefect` is installed on the remote cluster, with:

```bash
pip install prefect
```

3. If you get an error with a message similar to "File system created with scheme 's3' could not be created", ensure the required Python modules are installed on **both local and remote machines**. For example, if using S3 for storage:

```bash
pip install s3fs
```

4. If you are seeing timeout or other connection errors, double check the address provided to the `RayTaskRunner`. The address should look similar to: `address='ray://<head_node_ip_address>:10001'`:

```bash
RayTaskRunner(address="ray://1.23.199.255:10001")
```

## Specify remote options

The `remote_options` context can be used to control the task's remote options. For example, we can set the number of CPUs and GPUs to use for the `process` task:

```python
from prefect import flow, task
from prefect_ray.task_runners import RayTaskRunner
from prefect_ray.context import remote_options


@task
def process(x):
    return x + 1


@flow(task_runner=RayTaskRunner())
def my_flow():
    # equivalent to setting @ray.remote(num_cpus=4, num_gpus=2)
    with remote_options(num_cpus=4, num_gpus=2):
        process.submit(42).wait()
```

## Resources

Refer to the `prefect-ray` [SDK documentation](https://reference.prefect.io/prefect_ray/) to explore all the capabilities of the `prefect-ray` library.

For further assistance using Ray, consult the [Ray documentation](https://docs.ray.io/en/latest/index.html).


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-ray/sdk





# prefect-redis
Source: https://docs-3.prefect.io/integrations/prefect-redis/index



Integrations to extend Prefect's functionality with Redis.

## Getting started

### Install `prefect-redis`

The following command will install a version of `prefect-redis` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[redis]"
```

Upgrade to the latest versions of `prefect` and `prefect-redis`:

```bash
pip install -U "prefect[redis]"
```

### Register newly installed block types

Register the block types in the `prefect-redis` module to make them available for use.

```bash
prefect block register -m prefect_redis
```

## Resources

Refer to the [SDK documentation](https://reference.prefect.io/prefect_redis/) to explore all the capabilities of `prefect-redis`.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-redis/sdk





# prefect-shell
Source: https://docs-3.prefect.io/integrations/prefect-shell/index



Execute shell commands from within Prefect flows.

## Getting started

### Install `prefect-shell`

The following command will install a version of `prefect-shell` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[shell]"
```

Upgrade to the latest versions of `prefect` and `prefect-shell`:

```bash
pip install -U "prefect[shell]"
```

### Register newly installed block types

Register the block types in the `prefect-shell` module to make them available for use.

```bash
prefect block register -m prefect_shell
```

## Examples

### Integrate shell commands with Prefect flows

With `prefect-shell`, you can use shell commands (and/or scripts) in Prefect flows to provide observability and resiliency.
`prefect-shell` can be a useful tool if you're transitioning your orchestration from shell scripts to Prefect.

Let's get the shell-abration started!

The Python code below has shell commands embedded in a Prefect flow:

```python
from prefect import flow
from datetime import datetime
from prefect_shell import ShellOperation


@flow
def download_data():
    today = datetime.today().strftime("%Y%m%d")

    # for short running operations, you can use the `run` method
    # which automatically manages the context
    ShellOperation(
        commands=[
            "mkdir -p data",
            "mkdir -p data/${today}"
        ],
        env={"today": today}
    ).run()

    # for long running operations, you can use a context manager
    with ShellOperation(
        commands=[
            "curl -O https://masie_web.apps.nsidc.org/pub/DATASETS/NOAA/G02135/north/daily/data/N_seaice_extent_daily_v3.0.csv",
        ],
        working_dir=f"data/{today}",
    ) as download_csv_operation:

        # trigger runs the process in the background
        download_csv_process = download_csv_operation.trigger()

        # then do other things here in the meantime, like download another file
        ...

        # when you're ready, wait for the process to finish
        download_csv_process.wait_for_completion()

        # if you'd like to get the output lines, you can use the `fetch_result` method
        output_lines = download_csv_process.fetch_result()


if __name__ == "__main__":
    download_data()
```

Running this script results in output like this:

```bash
14:48:16.550 | INFO    | prefect.engine - Created flow run 'tentacled-chachalaca' for flow 'download-data'
14:48:17.977 | INFO    | Flow run 'tentacled-chachalaca' - PID 19360 triggered with 2 commands running inside the '.' directory.
14:48:17.987 | INFO    | Flow run 'tentacled-chachalaca' - PID 19360 completed with return code 0.
14:48:17.994 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 triggered with 1 commands running inside the PosixPath('data/20230201') directory.
14:48:18.009 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dl
14:48:18.010 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:
oad  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
14:48:18.840 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:
 11 1630k   11  192k    0     0   229k      0  0:00:07 --:--:--  0:00:07  231k
14:48:19.839 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:
 83 1630k   83 1368k    0     0   745k      0  0:00:02  0:00:01  0:00:01  747k
14:48:19.993 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:
100 1630k  100 1630k    0     0   819k      0  0
14:48:19.994 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:
:00:01  0:00:01 --:--:--  821k
14:48:19.996 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 completed with return code 0.
14:48:19.998 | INFO    | Flow run 'tentacled-chachalaca' - Successfully closed all open processes.
14:48:20.203 | INFO    | Flow run 'tentacled-chachalaca' - Finished in state Completed()
```

### Save shell commands in Prefect blocks

You can save commands within a `ShellOperation` block, then reuse them across multiple flows.

Save the block with desired commands:

```python
from prefect_shell import ShellOperation


ping_op = ShellOperation(commands=["ping -t 1 prefect.io"])
ping_op.save("block-name")

# Load the saved block:
ping_op = ShellOperation.load("block-name")
```

## Resources

Refer to the `prefect-shell` [SDK documentation](https://reference.prefect.io/prefect_shell/) to explore all the capabilities of the `prefect-shell` library.


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-shell/sdk





# prefect-slack
Source: https://docs-3.prefect.io/integrations/prefect-slack/index



## Welcome!

`prefect-slack` is a collection of prebuilt Prefect tasks that can be used to quickly construct Prefect flows.

## Getting started

### Prerequisites

A Slack account with permissions to create a Slack app and install it in your workspace.

### Installation

The following command will install a version of `prefect-slack` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[slack]"
```

Upgrade to the latest versions of `prefect` and `prefect-slack`:

```bash
pip install -U "prefect[slack]"
```

### Slack setup

To use tasks in the package, create a Slack app and install it in your Slack workspace. You can create a Slack app by navigating to the [apps page](https://api.slack.com/apps) for your Slack account and selecting 'Create New App'.

For tasks that require a Bot user OAuth token, you can get a token for your app by navigating to your app's **OAuth & Permissions** page.

For tasks that require a Webhook URL, you can generate a new Webhook URL by navigating to you apps **Incoming Webhooks** page.

Slack's [Basic app setup](https://api.slack.com/authentication/basics) guide provides additional details on setting up a Slack app.

### Write and run a flow

<CodeGroup>
  ```python sync
  import asyncio
  from prefect import flow
  from prefect.context import get_run_context
  from prefect_slack import SlackCredentials
  from prefect_slack.messages import send_chat_message

  @flow
  def example_send_message_flow():
     context = get_run_context()

     # Run other tasks or flows here

     token = "xoxb-your-bot-token-here"
     asyncio.run(
          send_chat_message(
              slack_credentials=SlackCredentials(token),
              channel="#prefect",
              text=f"Flow run {context.flow_run.name} completed :tada:"
          )
      )

  if __name__ == "__main__":
      example_send_message_flow()
  ```

  ```python async
  from prefect import flow
  from prefect.context import get_run_context
  from prefect_slack import SlackCredentials
  from prefect_slack.messages import send_chat_message


  @flow
  async def example_send_message_flow():
     context = get_run_context()

     # Run other tasks or flows here

     token = "xoxb-your-bot-token-here"
     await send_chat_message(
          slack_credentials=SlackCredentials(token),
          channel="#prefect",
          text=f"Flow run {context.flow_run.name} completed :tada:"
     )

  if __name__ == "__main__":
      asyncio.run(example_send_message_flow())
  ```
</CodeGroup>

## Resources

Refer to the `prefect-slack` [SDK documentation](https://reference.prefect.io/prefect_slack/) to explore all the capabilities of the `prefect-slack` library.

For further assistance developing with Slack, consult the [Slack documentation](https://api.slack.com/).


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-slack/sdk





# prefect-snowflake
Source: https://docs-3.prefect.io/integrations/prefect-snowflake/index



The `prefect-snowflake` integration makes it easy to connect to Snowflake in your Prefect flows. You can run queries both synchronously and asynchronously as Prefect flows and tasks.

## Getting started

### Prerequisites

* [A Snowflake account](https://www.snowflake.com/en/) and the necessary connection information.

### Installation

Install `prefect-snowflake` as a dependency of Prefect.
If you don't already have Prefect installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[snowflake]"
```

Upgrade to the latest versions of `prefect` and `prefect-snowflake`:

```bash
pip install -U "prefect[snowflake]"
```

### Blocks setup

The `prefect-snowflake` integration has two blocks: one for storing credentials and one for storing connection information. Register blocks in this module to view and edit them on Prefect Cloud:

```bash
prefect block register -m prefect_snowflake
```

#### Create the credentials block

Below is a walkthrough on saving a `SnowflakeCredentials` block through code. Log into your Snowflake account to find your credentials.
The example below uses a user and password combination, but refer to the [SDK documentation](https://reference.prefect.io/prefect_snowflake/) for a full list of authentication and connection options.

```python
from prefect_snowflake import SnowflakeCredentials

credentials = SnowflakeCredentials(
    account="ACCOUNT-PLACEHOLDER",  # resembles nh12345.us-east-2.snowflake
    user="USER-PLACEHOLDER",
    password="PASSWORD-PLACEHOLDER"
)
credentials.save("CREDENTIALS-BLOCK-NAME-PLACEHOLDER")
```

#### Create the connection block

Then, to create a `SnowflakeConnector` block:

1. After logging in, click on any worksheet.
2. On the left side, select a database and schema.
3. On the top right, select a warehouse.
4. Create a short script, replacing the placeholders below.

```python
from prefect_snowflake import SnowflakeCredentials, SnowflakeConnector

credentials = SnowflakeCredentials.load("CREDENTIALS-BLOCK-NAME-PLACEHOLDER")

connector = SnowflakeConnector(
    credentials=credentials,
    database="DATABASE-PLACEHOLDER",
    schema="SCHEMA-PLACEHOLDER",
    warehouse="COMPUTE_WH",
)
connector.save("CONNECTOR-BLOCK-NAME-PLACEHOLDER")
```

You can now easily load the saved block, which holds your credentials and connection info:

```python
from prefect_snowflake import SnowflakeCredentials, SnowflakeConnector

SnowflakeConnector.load("CONNECTOR-BLOCK-NAME-PLACEHOLDER")
```

## Examples

To set up a table, use the `execute` and `execute_many` methods. Then, use the `fetch_all` method. If the results are too large to fit into memory, use the `fetch_many` method to retrieve data in chunks.

By using the `SnowflakeConnector` as a context manager, you can make sure that the Snowflake connection and cursors are closed properly after you're done with them.

```python
from prefect import flow, task
from prefect_snowflake import SnowflakeConnector


@task
def setup_table(block_name: str) -> None:
    with SnowflakeConnector.load(block_name) as connector:
        connector.execute(
            "CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);"
        )
        connector.execute_many(
            "INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);",
            seq_of_parameters=[
                {"name": "Ford", "address": "Highway 42"},
                {"name": "Unknown", "address": "Space"},
                {"name": "Me", "address": "Myway 88"},
            ],
        )

@task
def fetch_data(block_name: str) -> list:
    all_rows = []
    with SnowflakeConnector.load(block_name) as connector:
        while True:
            # Repeated fetch* calls using the same operation will
            # skip re-executing and instead return the next set of results
            new_rows = connector.fetch_many("SELECT * FROM customers", size=2)
            if len(new_rows) == 0:
                break
            all_rows.append(new_rows)
    return all_rows

@flow
def snowflake_flow(block_name: str) -> list:
    setup_table(block_name)
    all_rows = fetch_data(block_name)
    return all_rows


if __name__=="__main__":
    snowflake_flow()
```

If the native methods of the block don't meet your requirements, don't worry. You have the option to access the underlying Snowflake connection and utilize its built-in methods as well.

```python
import pandas as pd
from prefect import flow
from prefect_snowflake.database import SnowflakeConnector
from snowflake.connector.pandas_tools import write_pandas


@flow
def snowflake_write_pandas_flow():
    connector = SnowflakeConnector.load("my-block")
    with connector.get_connection() as connection:
        table_name = "TABLE_NAME"
        ddl = "NAME STRING, NUMBER INT"
        statement = f'CREATE TABLE IF NOT EXISTS {table_name} ({ddl})'
        with connection.cursor() as cursor:
            cursor.execute(statement)

        # case sensitivity matters here!
        df = pd.DataFrame([('Marvin', 42), ('Ford', 88)], columns=['NAME', 'NUMBER'])
        success, num_chunks, num_rows, _ = write_pandas(
            conn=connection,
            df=df,
            table_name=table_name,
            database=snowflake_connector.database,
            schema=snowflake_connector.schema_  # note the "_" suffix
        )
```

## Resources

Refer to the `prefect-snowflake` [SDK documentation](https://reference.prefect.io/prefect_snowflake/database/) to explore other capabilities of the `prefect-snowflake` library, such as async methods.

For further assistance using Snowflake, consult the [Snowflake documentation](https://docs.snowflake.com/) or the [Snowflake Python Connector documentation](https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-example).


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-snowflake/sdk





# prefect-sqlalchemy
Source: https://docs-3.prefect.io/integrations/prefect-sqlalchemy/index



# Welcome!

`prefect-sqlalchemy` helps you connect to a database in your Prefect flows.

## Getting started

### Install `prefect-sqlalchemy`

The following command will install a version of `prefect-sqlalchemy` compatible with your installed version of `prefect`.
If you don't already have `prefect` installed, it will install the newest version of `prefect` as well.

```bash
pip install "prefect[sqlalchemy]"
```

Upgrade to the latest versions of `prefect` and `prefect-sqlalchemy`:

```bash
pip install -U "prefect[sqlalchemy]"
```

### Register newly installed block types

Register the block types in the `prefect-sqlalchemy` module to make them available for use.

```bash
prefect block register -m prefect_sqlalchemy
```

## Examples

### Save credentials to a block

To use the `load` method on Blocks, you must have a block saved through code or saved through the UI.

```python
from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, SyncDriver

connector = SqlAlchemyConnector(
    connection_info=ConnectionComponents(
        driver=SyncDriver.POSTGRESQL_PSYCOPG2,
        username="USERNAME-PLACEHOLDER",
        password="PASSWORD-PLACEHOLDER",
        host="localhost",
        port=5432,
        database="DATABASE-PLACEHOLDER",
    )
)

connector.save("BLOCK_NAME-PLACEHOLDER")
```

Load the saved block that holds your credentials:

```python
from prefect_sqlalchemy import SqlAlchemyConnector

SqlAlchemyConnector.load("BLOCK_NAME-PLACEHOLDER")
```

The required arguments depend upon the desired driver. For example, SQLite requires only the `driver` and `database` arguments:

```python
from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, SyncDriver

connector = SqlAlchemyConnector(
    connection_info=ConnectionComponents(
        driver=SyncDriver.SQLITE_PYSQLITE,
        database="DATABASE-PLACEHOLDER.db"
    )
)

connector.save("BLOCK_NAME-PLACEHOLDER")
```

### Work with databases in a flow

To set up a table, use the `execute` and `execute_many` methods.

Use the `fetch_many` method to retrieve data in a stream until there's no more data.

Use the `SqlAlchemyConnector` as a context manager, to ensure that the SQLAlchemy engine and any connected resources are closed properly after you're done with them.

<Note>
  **Async support**

  `SqlAlchemyConnector`  supports async workflows. Just be sure to save, load, and use an async driver, as in the example below.

  ```python
  from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, AsyncDriver

  connector = SqlAlchemyConnector(
      connection_info=ConnectionComponents(
          driver=AsyncDriver.SQLITE_AIOSQLITE,
          database="DATABASE-PLACEHOLDER.db"
      )
  )

  if __name__ == "__main__":
      connector.save("BLOCK_NAME-PLACEHOLDER")
  ```
</Note>

<Tabs>
  <Tab title="Sync">
    ```python
    from prefect import flow, task
    from prefect_sqlalchemy import SqlAlchemyConnector


    @task
    def setup_table(block_name: str) -> None:
        with SqlAlchemyConnector.load(block_name) as connector:
            connector.execute(
                "CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);"
            )
            connector.execute(
                "INSERT INTO customers (name, address) VALUES (:name, :address);",
                parameters={"name": "Marvin", "address": "Highway 42"},
            )
            connector.execute_many(
                "INSERT INTO customers (name, address) VALUES (:name, :address);",
                seq_of_parameters=[
                    {"name": "Ford", "address": "Highway 42"},
                    {"name": "Unknown", "address": "Highway 42"},
                ],
            )

    @task
    def fetch_data(block_name: str) -> list:
        all_rows = []
        with SqlAlchemyConnector.load(block_name) as connector:
            while True:
                # Repeated fetch* calls using the same operation will
                # skip re-executing and instead return the next set of results
                new_rows = connector.fetch_many("SELECT * FROM customers", size=2)
                if len(new_rows) == 0:
                    break
                all_rows.append(new_rows)
        return all_rows

    @flow
    def sqlalchemy_flow(block_name: str) -> list:
        setup_table(block_name)
        all_rows = fetch_data(block_name)
        return all_rows


    if __name__ == "__main__":
        sqlalchemy_flow("BLOCK-NAME-PLACEHOLDER")
    ```
  </Tab>

  <Tab title="Async">
    ```python
    from prefect import flow, task
    from prefect_sqlalchemy import SqlAlchemyConnector
    import asyncio


    @task
    async def setup_table(block_name: str) -> None:
        async with await SqlAlchemyConnector.load(block_name) as connector:
            await connector.execute(
                "CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);"
            )
            await connector.execute(
                "INSERT INTO customers (name, address) VALUES (:name, :address);",
                parameters={"name": "Marvin", "address": "Highway 42"},
            )
            await connector.execute_many(
                "INSERT INTO customers (name, address) VALUES (:name, :address);",
                seq_of_parameters=[
                    {"name": "Ford", "address": "Highway 42"},
                    {"name": "Unknown", "address": "Highway 42"},
                ],
            )

    @task
    async def fetch_data(block_name: str) -> list:
        all_rows = []
        async with await SqlAlchemyConnector.load(block_name) as connector:
            while True:
                # Repeated fetch* calls using the same operation will
                # skip re-executing and instead return the next set of results
                new_rows = await connector.fetch_many("SELECT * FROM customers", size=2)
                if len(new_rows) == 0:
                    break
                all_rows.append(new_rows)
        return all_rows

    @flow
    async def sqlalchemy_flow(block_name: str) -> list:
        await setup_table(block_name)
        all_rows = await fetch_data(block_name)
        return all_rows


    if __name__ == "__main__":
        asyncio.run(sqlalchemy_flow("BLOCK-NAME-PLACEHOLDER"))
    ```
  </Tab>
</Tabs>

## Resources

Refer to the `prefect-sqlalchemy` [SDK documentation](https://reference.prefect.io/prefect_sqlalchemy/) to explore all the capabilities of the `prefect-sqlalchemy` library.

For assistance using SQLAlchemy, consult the [SQLAlchemy documentation](https://www.sqlalchemy.org/).


# SDK docs
Source: https://docs-3.prefect.io/integrations/prefect-sqlalchemy/sdk





# null
Source: https://docs-3.prefect.io/integrations/use-integrations

Prefect integrations are PyPI packages you can install to help you build and integrate your workflows with third parties.

## Install an integration package

Install an integration package with `pip`.

For example, to install `prefect-aws` you can:

* install the package directly:

```bash
pip install prefect-aws
```

* install the corresponding extra:

```bash
pip install 'prefect[aws]'
```

See [the `project.optional-dependencies` section of `pyproject.toml`](https://github.com/PrefectHQ/prefect/blob/main/pyproject.toml) for the full list of extras and the versions they specify.

## Register blocks from an integration

Once the package is installed, [register the blocks](/v3/develop/blocks/#registering-blocks-for-use-in-the-prefect-ui) within the integration to view them in the Prefect Cloud UI:

For example, to register the blocks available in `prefect-aws`:

```bash
prefect block register -m prefect_aws
```

To use a block's `load` method, you must have a block [saved](/v3/develop/blocks/#saving-blocks). [Learn more about blocks](/v3/develop/blocks).

## Use tasks and flows from an Integration

Integrations may contain pre-built tasks and flows that can be imported and called within your code.

For example, read a secret from AWS Secrets Manager with the `read_secret` task with the following code:

```python
from prefect import flow
from prefect_aws import AwsCredentials
from prefect_aws.secrets_manager import read_secret

@flow
def connect_to_database():
    aws_credentials = AwsCredentials.load("MY_BLOCK_NAME")
    secret_value = read_secret(
        secret_name="db_password",
        aws_credentials=aws_credentials
    )

    # Then, use secret_value to connect to a database
```

## Customize tasks and flows from an integration

To customize pre-configured tasks or flows, use `with_options`. For example, configure retries for dbt Cloud jobs:

```python
from prefect import flow
from prefect_dbt.cloud import DbtCloudCredentials
from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion


custom_run_dbt_cloud_job = trigger_dbt_cloud_job_run_and_wait_for_completion.with_options(
    name="Run My DBT Cloud Job",
    retries=2,
    retry_delay_seconds=10
)

@flow
def run_dbt_job_flow():
    run_result = custom_run_dbt_cloud_job(
        dbt_cloud_credentials=DbtCloudCredentials.load("my-dbt-cloud-credentials"),
        job_id=1
    )


if __name__ == "__main__":  
    run_dbt_job_flow()
```


# How to use and configure the API client
Source: https://docs-3.prefect.io/v3/advanced/api-client



## Overview

The [`PrefectClient`](https://reference.prefect.io/prefect/client/)
offers methods to simplify common operations against Prefect's REST API that may not be abstracted away by the SDK.

For example, to [reschedule flow runs](/v3/develop/interact-with-api/#reschedule-late-flow-runs), one might use methods like:

* `read_flow_runs` with a `FlowRunFilter` to read certain flow runs
* `create_flow_run_from_deployment` to schedule new flow runs
* `delete_flow_run` to delete a very `Late` flow run

### Getting a client

By default, `get_client()` returns an asynchronous client to be used as a context manager, but you may also use a synchronous client.

<CodeGroup>
  {/* pmd-metadata: notest */}

  ```python async
  from prefect import get_client

  async with get_client() as client:
      response = await client.hello()
      print(response.json()) # 👋
  ```

  You can also use a synchronous client:

  ```python sync
  from prefect import get_client

  with get_client(sync_client=True) as client:
      response = client.hello()
      print(response.json()) # 👋
  ```
</CodeGroup>

## Configure custom headers

You can configure custom HTTP headers to be sent with every API request by setting the `PREFECT_CLIENT_CUSTOM_HEADERS` setting. This is useful for adding authentication headers, API keys, or other custom headers required by proxies, CDNs, or security systems.

### Setting custom headers

Custom headers can be configured via environment variables or settings. The headers are specified as key-value pairs in JSON format.

<CodeGroup>
  ```bash Environment variable
  export PREFECT_CLIENT_CUSTOM_HEADERS='{"CF-Access-Client-Id": "your-client-id", "CF-Access-Client-Secret": "your-secret"}'
  ```

  ```bash CLI
  prefect config set PREFECT_CLIENT_CUSTOM_HEADERS='{"CF-Access-Client-Id": "your-client-id", "CF-Access-Client-Secret": "your-secret"}'
  ```

  ```toml prefect.toml
  [client]
  custom_headers = '''{
      "CF-Access-Client-Id": "your-client-id",
      "CF-Access-Client-Secret": "your-secret",
      "X-API-Key": "your-api-key"
  }'''
  ```
</CodeGroup>

<Warning>
  **Protected headers**

  Certain headers are protected and cannot be overridden by custom headers for security reasons:

  * `User-Agent` - Managed by Prefect to identify client version
  * `Prefect-Csrf-Token` - Used for CSRF protection
  * `Prefect-Csrf-Client` - Used for CSRF protection

  If you attempt to override these headers, Prefect will log a warning and ignore the custom header value.
</Warning>

## Examples

These examples are meant to illustrate how one might develop their own utilities for interacting with the API.

<Note>
  If you believe a client method is missing, or you'd like to see a specific pattern better represented in the SDK generally, please [open an issue](https://github.com/PrefectHQ/prefect/issues/new/choose).
</Note>

### Reschedule late flow runs

To bulk reschedule flow runs that are late, delete the late flow runs and create new ones in a
`Scheduled` state with a delay. This is useful if you accidentally scheduled many
flow runs of a deployment to an inactive work pool, for example.

The following example reschedules the last three late flow runs of a deployment named
`healthcheck-storage-test` to run six hours later than their original expected start time.
It also deletes any remaining late flow runs of that deployment.

First, define the rescheduling function:

{/* pmd-metadata: notest */}

```python
async def reschedule_late_flow_runs(
    deployment_name: str,
    delay: timedelta,
    most_recent_n: int,
    delete_remaining: bool = True,
    states: list[str] | None = None
) -> list[FlowRun]:
    states = states or ["Late"]

    async with get_client() as client:
        flow_runs = await client.read_flow_runs(
            flow_run_filter=FlowRunFilter(
                state=dict(name=dict(any_=states)),
                expected_start_time=dict(before_=datetime.now(timezone.utc)),
            ),
            deployment_filter=DeploymentFilter(name={'like_': deployment_name}),
            sort=FlowRunSort.START_TIME_DESC,
            limit=most_recent_n if not delete_remaining else None
        )

        rescheduled_flow_runs: list[FlowRun] = []
        for i, run in enumerate(flow_runs):
            await client.delete_flow_run(flow_run_id=run.id)
            if i < most_recent_n:
                new_run = await client.create_flow_run_from_deployment(
                    deployment_id=run.deployment_id,
                    state=Scheduled(scheduled_time=run.expected_start_time + delay),
                )
                rescheduled_flow_runs.append(new_run)
            
        return rescheduled_flow_runs
```

Then use it to reschedule flows:

{/* pmd-metadata: notest */}

```python
rescheduled_flow_runs = asyncio.run(
    reschedule_late_flow_runs(
        deployment_name="healthcheck-storage-test",
        delay=timedelta(hours=6),
        most_recent_n=3,
    )
)
```

<Accordion title="View the complete example">
  ```python reschedule_late_flows.py
  from __future__ import annotations

  import asyncio
  from datetime import datetime, timedelta, timezone

  from prefect import get_client
  from prefect.client.schemas.filters import DeploymentFilter, FlowRunFilter
  from prefect.client.schemas.objects import FlowRun
  from prefect.client.schemas.sorting import FlowRunSort
  from prefect.states import Scheduled

  async def reschedule_late_flow_runs(
      deployment_name: str,
      delay: timedelta,
      most_recent_n: int,
      delete_remaining: bool = True,
      states: list[str] | None = None
  ) -> list[FlowRun]:
      states = states or ["Late"]

      async with get_client() as client:
          flow_runs = await client.read_flow_runs(
              flow_run_filter=FlowRunFilter(
                  state=dict(name=dict(any_=states)),
                  expected_start_time=dict(before_=datetime.now(timezone.utc)),
              ),
              deployment_filter=DeploymentFilter(name={'like_': deployment_name}),
              sort=FlowRunSort.START_TIME_DESC,
              limit=most_recent_n if not delete_remaining else None
          )

          if not flow_runs:
              print(f"No flow runs found in states: {states!r}")
              return []
          
          rescheduled_flow_runs: list[FlowRun] = []
          for i, run in enumerate(flow_runs):
              await client.delete_flow_run(flow_run_id=run.id)
              if i < most_recent_n:
                  new_run = await client.create_flow_run_from_deployment(
                      deployment_id=run.deployment_id,
                      state=Scheduled(scheduled_time=run.expected_start_time + delay),
                  )
                  rescheduled_flow_runs.append(new_run)
              
          return rescheduled_flow_runs


  if __name__ == "__main__":
      rescheduled_flow_runs = asyncio.run(
          reschedule_late_flow_runs(
              deployment_name="healthcheck-storage-test",
              delay=timedelta(hours=6),
              most_recent_n=3,
          )
      )
      
      print(f"Rescheduled {len(rescheduled_flow_runs)} flow runs")
      
      assert all(run.state.is_scheduled() for run in rescheduled_flow_runs)
      assert all(
          run.expected_start_time > datetime.now(timezone.utc)
          for run in rescheduled_flow_runs
      )
  ```
</Accordion>

### Get the last `N` completed flow runs from your workspace

To get the last `N` completed flow runs from your workspace, use `read_flow_runs` and `prefect.client.schemas`.

This example gets the last three completed flow runs from your workspace:

{/* pmd-metadata: notest */}

```python
async def get_most_recent_flow_runs(
    n: int,
    states: list[str] | None = None
) -> list[FlowRun]:    
    async with get_client() as client:
        return await client.read_flow_runs(
            flow_run_filter=FlowRunFilter(
                state={'type': {'any_': states or ["COMPLETED"]}}
            ),
            sort=FlowRunSort.END_TIME_DESC,
            limit=n,
        )
```

Use it to get the last 3 completed runs:

{/* pmd-metadata: notest */}

```python
flow_runs: list[FlowRun] = asyncio.run(
    get_most_recent_flow_runs(n=3)
)
```

<Accordion title="View the complete example">
  ```python get_recent_flows.py
  from __future__ import annotations

  import asyncio

  from prefect import get_client
  from prefect.client.schemas.filters import FlowRunFilter
  from prefect.client.schemas.objects import FlowRun
  from prefect.client.schemas.sorting import FlowRunSort

  async def get_most_recent_flow_runs(
      n: int,
      states: list[str] | None = None
  ) -> list[FlowRun]:    
      async with get_client() as client:
          return await client.read_flow_runs(
              flow_run_filter=FlowRunFilter(
                  state={'type': {'any_': states or ["COMPLETED"]}}
              ),
              sort=FlowRunSort.END_TIME_DESC,
              limit=n,
          )


  if __name__ == "__main__":
      flow_runs: list[FlowRun] = asyncio.run(
          get_most_recent_flow_runs(n=3)
      )
      assert len(flow_runs) == 3
      
      assert all(
          run.state.is_completed() for run in flow_runs
      )
      assert (
          end_times := [run.end_time for run in flow_runs]
      ) == sorted(end_times, reverse=True)
  ```
</Accordion>

Instead of the last three from the whole workspace, you can also use the `DeploymentFilter`
to get the last three completed flow runs of a specific deployment.

### Transition all running flows to cancelled through the Client

Use `get_client`to set multiple runs to a `Cancelled` state.
This example cancels all flow runs that are in `Pending`, `Running`, `Scheduled`, or `Late` states when the script is run.

{/* pmd-metadata: notest */}

```python
async def list_flow_runs_with_states(states: list[str]) -> list[FlowRun]:
    async with get_client() as client:
        return await client.read_flow_runs(
            flow_run_filter=FlowRunFilter(
                state=FlowRunFilterState(
                    name=FlowRunFilterStateName(any_=states)
                )
            )
        )

async def cancel_flow_runs(flow_runs: list[FlowRun]):
    async with get_client() as client:
        for flow_run in flow_runs:
            state = flow_run.state.copy(
                update={"name": "Cancelled", "type": StateType.CANCELLED}
            )
            await client.set_flow_run_state(flow_run.id, state, force=True)
```

Cancel all pending, running, scheduled or late flows:

{/* pmd-metadata: notest */}

```python
async def bulk_cancel_flow_runs():
    states = ["Pending", "Running", "Scheduled", "Late"]
    flow_runs = await list_flow_runs_with_states(states)

    while flow_runs:
        print(f"Cancelling {len(flow_runs)} flow runs")
        await cancel_flow_runs(flow_runs)
        flow_runs = await list_flow_runs_with_states(states)

asyncio.run(bulk_cancel_flow_runs())
```

<Accordion title="View the complete example">
  ```python cancel_flows.py
  import asyncio

  from prefect import get_client
  from prefect.client.schemas.filters import FlowRunFilter, FlowRunFilterState, FlowRunFilterStateName
  from prefect.client.schemas.objects import FlowRun, StateType

  async def list_flow_runs_with_states(states: list[str]) -> list[FlowRun]:
      async with get_client() as client:
          return await client.read_flow_runs(
              flow_run_filter=FlowRunFilter(
                  state=FlowRunFilterState(
                      name=FlowRunFilterStateName(any_=states)
                  )
              )
          )


  async def cancel_flow_runs(flow_runs: list[FlowRun]):
      async with get_client() as client:
          for idx, flow_run in enumerate(flow_runs):
              print(f"[{idx + 1}] Cancelling flow run '{flow_run.name}' with ID '{flow_run.id}'")
              state_updates: dict[str, str] = {}
              state_updates.setdefault("name", "Cancelled")
              state_updates.setdefault("type", StateType.CANCELLED)
              state = flow_run.state.copy(update=state_updates)
              await client.set_flow_run_state(flow_run.id, state, force=True)


  async def bulk_cancel_flow_runs():
      states = ["Pending", "Running", "Scheduled", "Late"]
      flow_runs = await list_flow_runs_with_states(states)

      while len(flow_runs) > 0:
          print(f"Cancelling {len(flow_runs)} flow runs\n")
          await cancel_flow_runs(flow_runs)
          flow_runs = await list_flow_runs_with_states(states)
      print("Done!")


  if __name__ == "__main__":
      asyncio.run(bulk_cancel_flow_runs())
  ```
</Accordion>

### Create, read, or delete artifacts

Create, read, or delete artifacts programmatically through the [Prefect REST API](/v3/api-ref/rest-api/).
With the Artifacts API, you can automate the creation and management of artifacts as part of your workflow.

For example, to read the five most recently created Markdown, table, and link artifacts, you can run the following:

```python fixture:mock_post_200
import requests


PREFECT_API_URL="https://api.prefect.cloud/api/accounts/abc/workspaces/xyz"
PREFECT_API_KEY="pnu_ghijk"
data = {
    "sort": "CREATED_DESC",
    "limit": 5,
    "artifacts": {
        "key": {
            "exists_": True
        }
    }
}

headers = {"Authorization": f"Bearer {PREFECT_API_KEY}"}
endpoint = f"{PREFECT_API_URL}/artifacts/filter"

response = requests.post(endpoint, headers=headers, json=data)
assert response.status_code == 200
for artifact in response.json():
    print(artifact)
```

If you don't specify a key or that a key must exist, you will also return results, which are a type of key-less artifact.

See the [Prefect REST API documentation](/v3/api-ref/rest-api/) on artifacts for more information.


# How to customize asset metadata
Source: https://docs-3.prefect.io/v3/advanced/assets

This guide covers how to enhance your assets with rich metadata, custom properties, and explicit dependency management beyond what's automatically inferred from your task graph.

<span class="badge cloud" />

Both `@materialize` and `asset_deps` accept either a string referencing an asset key or a full `Asset` class instance. Using the `Asset` class is the way to provide additional metadata like names, descriptions, and ownership information beyond just the key.

## The Asset class

While you can use simple string keys with the `@materialize` decorator, the `Asset` class provides more control over asset properties and metadata. Create `Asset` instances to add organizational context and improve discoverability.

### Asset initialization fields

The `Asset` class accepts the following parameters:

* **`key`** (required): A valid URI that uniquely identifies your asset. This is the only required field.

* **`properties`** (optional): An `AssetProperties` instance containing metadata about the asset.

```python
from prefect.assets import Asset, AssetProperties

# Simple asset with just a key
basic_asset = Asset(key="s3://my-bucket/data.csv")

# Asset with full properties
detailed_asset = Asset(
    key="s3://my-bucket/processed-data.csv",
    properties=AssetProperties(
        name="Processed Customer Data",
        description="Clean customer data with PII removed",
        owners=["data-team@company.com", "alice@company.com"],
        url="https://dashboard.company.com/datasets/customer-data"
    )
)
```

Each of these fields will be displayed alongside the asset in the UI.

<Note>
  **Interactive fields**

  The owners field can optionally reference user emails, as well as user and team handles within your Prefect Cloud workspace.
  The URL field becomes a clickable link when this asset is displayed.
</Note>

<Warning>
  **Updates occur at runtime**

  Updates to asset metadata are always performed at workflow runtime whenever a materializing task is executed that references the asset.
</Warning>

## Using assets in materializations

Once you've defined your `Asset` instances, use them directly with the `@materialize` decorator:

```python
from prefect import flow
from prefect.assets import Asset, AssetProperties, materialize


detailed_asset = Asset(
    key="s3://my-bucket/processed-data.csv",
    properties=AssetProperties(
        name="Processed Customer Data",
        description="Clean customer data with PII removed",
        owners=["data-team@company.com", "alice@company.com"],
        url="https://dashboard.company.com/datasets/customer-data"
    )
)

properties = AssetProperties(
    name="Sales Analytics Dataset",
    description="This dataset contains daily sales figures by region along with customer segmentation data",
    owners=["analytics-team", "john.doe@company.com"],
    url="https://analytics.company.com/sales-dashboard"
)

sales_asset = Asset(
    key="snowflake://warehouse/analytics/sales_summary",
    properties=properties
)


@materialize(detailed_asset)
def process_customer_data():
    # Your processing logic here
    pass


@materialize(sales_asset)
def generate_sales_report():
    # Your reporting logic here
    pass


@flow
def analytics_pipeline():
    process_customer_data()
    generate_sales_report()
```

## Adding runtime metadata

Beyond static properties, you can add dynamic metadata during task execution. This is useful for tracking runtime information like row counts, processing times, or data quality metrics.

### Using `Asset.add_metadata()`

The preferred approach is to use the `add_metadata()` method on your `Asset` instances. This prevents typos in asset keys and provides better IDE support:

```python
from prefect.assets import Asset, AssetProperties, materialize

customer_data = Asset(
    key="s3://my-bucket/customer-data.csv",
    properties=AssetProperties(
        name="Customer Data",
        owners=["data-team@company.com"]
    )
)

@materialize(customer_data)
def process_customers():
    # Your processing logic
    result = perform_customer_processing()
    
    # Add runtime metadata
    customer_data.add_metadata({
        "record_count": len(result),
        "processing_duration_seconds": 45.2,
        "data_quality_score": 0.95,
        "last_updated": "2024-01-15T10:30:00Z"
    })
    
    return result
```

### Using `add_asset_metadata()` utility

Alternatively, you can use the `add_asset_metadata()` function, which requires specifying the asset key:

```python
from prefect.assets import materialize, add_asset_metadata

@materialize("s3://my-bucket/processed-data.csv")
def process_data():
    result = perform_processing()
    
    add_asset_metadata(
        "s3://my-bucket/processed-data.csv",
        {"rows_processed": len(result), "processing_time": "2.5s"}
    )
    
    return result
```

### Accumulating metadata

You can call metadata methods multiple times to accumulate information:

{/* pmd-metadata: notest */}

```python
@materialize(customer_data)
def comprehensive_processing():
    # First processing step
    raw_data = extract_data()
    customer_data.add_metadata({"raw_records": len(raw_data)})
    
    # Second processing step
    cleaned_data = clean_data(raw_data)
    customer_data.add_metadata({
        "cleaned_records": len(cleaned_data),
        "records_removed": len(raw_data) - len(cleaned_data)
    })
    
    # Final step
    final_data = enrich_data(cleaned_data)
    customer_data.add_metadata({
        "final_records": len(final_data),
        "enrichment_success_rate": 0.92
    })
    
    return final_data
```

## Explicit asset dependencies

While Prefect automatically infers dependencies from your task graph, you can explicitly declare asset relationships using the `asset_deps` parameter. This is useful when:

* The task graph doesn't fully capture your data dependencies due to dynamic execution rules
* You need to reference assets that aren't directly passed between tasks
* You want to be explicit about critical dependencies for documentation purposes

### Hard-coding dependencies

Use `asset_deps` to explicitly declare which assets your materialization depends on. You can reference assets by key string or by full `Asset` instance:

```python
from prefect import flow
from prefect.assets import Asset, AssetProperties, materialize


# Define your assets
raw_data_asset = Asset(key="s3://my-bucket/raw-data.csv")
config_asset = Asset(key="s3://my-bucket/processing-config.json")
processed_asset = Asset(key="s3://my-bucket/processed-data.csv")

@materialize(raw_data_asset)
def extract_raw_data():
    pass

@materialize(
    processed_asset,
    asset_deps=[raw_data_asset, config_asset]  # Explicit dependencies
)
def process_data():
    # This function depends on both raw data and config
    # even if they're not directly passed as parameters
    pass

@flow
def explicit_dependencies_flow():
    extract_raw_data()
    process_data()  # Explicitly depends on raw_data_asset and config_asset
```

### Mixing inferred and explicit dependencies

You can combine task graph inference with explicit dependencies:

```python
from prefect import flow
from prefect.assets import Asset, materialize


upstream_asset = Asset(key="s3://my-bucket/upstream.csv")
config_asset = Asset(key="s3://my-bucket/config.json")
downstream_asset = Asset(key="s3://my-bucket/downstream.csv")

@materialize(upstream_asset)
def create_upstream():
    return "upstream_data"

@materialize(
    downstream_asset,
    asset_deps=[config_asset]  # Explicit dependency on config
)
def create_downstream(upstream_data):  # Inferred dependency on upstream_asset
    # This asset depends on:
    # 1. upstream_asset (inferred from task graph)
    # 2. config_asset (explicit via asset_deps)
    pass

@flow
def mixed_dependencies():
    data = create_upstream()
    create_downstream(data)
```

### Best practices for `asset_deps` references

Use *string keys* when referencing assets that are materialized by other Prefect workflows. This avoids duplicate metadata definitions and lets the materializing workflow be the source of truth:

```python
from prefect.assets import materialize

# Good: Reference by key when another workflow materializes the asset
@materialize(
    "s3://my-bucket/final-report.csv",
    asset_deps=["s3://my-bucket/data-from-other-workflow.csv"]  # String key
)
def create_report():
    pass
```

Use *full `Asset` instances* when referencing assets that are completely external to Prefect. This provides metadata about external systems that Prefect wouldn't otherwise know about:

```python
from prefect.assets import Asset, AssetProperties, materialize


# Good: Full Asset for external systems
external_database = Asset(
    key="postgres://prod-db/public/users",
    properties=AssetProperties(
        name="Production Users Table",
        description="Main user database maintained by the platform team",
        owners=["platform-team@company.com"],
        url="https://internal-db-dashboard.com/users"
    )
)

@materialize(
    "s3://my-bucket/user-analytics.csv",
    asset_deps=[external_database]  # Full Asset for external system
)
def analyze_users():
    pass
```

## Updating asset properties

Asset properties should have one source of truth to avoid conflicts. When you materialize an asset with properties, those properties perform a complete overwrite of all metadata fields for that asset.

<Warning>
  **Important**

  Any `Asset` instance with properties will completely replace all existing metadata. Partial updates are not supported - you must provide all the metadata you want to preserve.
</Warning>

```python
from prefect.assets import Asset, AssetProperties, materialize


# Initial materialization with full properties
initial_asset = Asset(
    key="s3://my-bucket/evolving-data.csv",
    properties=AssetProperties(
        name="Evolving Dataset",
        description="Initial description",
        owners=["team-a@company.com"],
        url="https://dashboard.company.com/evolving-data"
    )
)

@materialize(initial_asset)
def initial_creation():
    pass

# Later materialization - OVERWRITES all properties
updated_asset = Asset(
    key="s3://my-bucket/evolving-data.csv",
    properties=AssetProperties(
        name="Evolving Dataset",  # Must include to preserve
        description="Updated description with new insights",  # Updated
        owners=["team-a@company.com"],  # Must include to preserve
        # url is now None because it wasn't included
    )
)

@materialize(updated_asset)
def update_dataset():
    pass

# The final asset will have:
# - name: "Evolving Dataset" (preserved)
# - description: "Updated description with new insights" (updated)
# - owners: ["team-a@company.com"] (preserved)
# - url: None (lost because not included in update)
```

<Tip>
  **Best practice**

  Designate one workflow as the authoritative source for each asset's metadata. Other workflows that reference the asset should use string keys only to avoid conflicting metadata definitions.
</Tip>

## Further Reading

* [Learn about asset health and asset events](/v3/concepts/assets)


# How to deploy a web application powered by background tasks
Source: https://docs-3.prefect.io/v3/advanced/background-tasks

Learn how to background heavy tasks from a web application to dedicated infrastructure.

This example demonstrates how to use [background tasks](/v3/concepts/tasks#background-tasks) in the context of a web application using Prefect for task submission, execution, monitoring, and result storage. We'll build out an application using FastAPI to offer API endpoints to our clients, and task workers to execute the background tasks these endpoints defer.

<Tip>
  Refer to the [examples repository](https://github.com/PrefectHQ/examples/tree/main/apps/background-tasks) for the complete example's source code.
</Tip>

This pattern is useful when you need to perform operations that are too long for a standard web request-response cycle, such as data processing, sending emails, or interacting with external APIs that might be slow.

## Overview

This example will build out:

* `@prefect.task` definitions representing the work you want to run in the background
* A `fastapi` application providing API endpoints to:
  * Receive task parameters via `POST` request and submit the task to Prefect with `.delay()`
  * Allow polling for the task's status via a `GET` request using its `task_run_id`
* A `Dockerfile` to build a multi-stage image for the web app, Prefect server and task worker(s)
* A `compose.yaml` to manage lifecycles of the web app, Prefect server and task worker(s)

```bash
├── Dockerfile
├── README.md
├── compose.yaml
├── pyproject.toml
├── src
│   └── foo
│       ├── __init__.py
│       ├── _internal/*.py
│       ├── api.py
│       └── task.py
```

You can follow along by cloning the [examples repository](https://github.com/PrefectHQ/examples) or instead use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) to bootstrap a your own new project:

```bash
uv init --lib foo
uv add prefect marvin
```

This example application is structured as a library with a `src/foo` directory for portability and organization.

<Note>
  This example does ***not*** require:

  * Prefect Cloud
  * creating a Prefect Deployment
  * creating a work pool
</Note>

## Useful things to remember

* You can call any Python code from your task definitions (including other flows and tasks!)
* Prefect [Results](/v3/concepts/caching) allow you to save/serialize the `return` value of your task definitions to your result storage (e.g. a local directory, S3, GCS, etc), enabling [caching](/v3/concepts/caching) and [idempotency](/v3/advanced/transactions).

## Defining the background task

The core of the background processing is a Python function decorated with `@prefect.task`. This marks the function as a unit of work that Prefect can manage (e.g. observe, cache, retry, etc.)

{/* pmd-metadata: notest */}

```python src/foo/task.py
from typing import Any, TypeVar

import marvin

from prefect import task, Task
from prefect.cache_policies import INPUTS, TASK_SOURCE
from prefect.states import State
from prefect.task_worker import serve
from prefect.client.schemas.objects import TaskRun

T = TypeVar("T")


def _print_output(task: Task, task_run: TaskRun, state: State[T]):
    result = state.result()
    print(f"result type: {type(result)}")
    print(f"result: {result!r}")


@task(cache_policy=INPUTS + TASK_SOURCE, on_completion=[_print_output])
async def create_structured_output(data: Any, target: type[T], instructions: str) -> T:
    return await marvin.cast_async(
        data,
        target=target,
        instructions=instructions,
    )


def main():
    serve(create_structured_output)


if __name__ == "__main__":
    main()
```

Key details:

* `@task`: Decorator to define our task we want to run in the background.
* `cache_policy`: Caching based on `INPUTS` and `TASK_SOURCE`.
* `serve(create_structured_output)`: This function starts a task worker subscribed to newly `delay()`ed task runs.

## Building the FastAPI application

The FastAPI application provides API endpoints to trigger the background task and check its status.

{/* pmd-metadata: notest */}

```python src/foo/api.py
import logging
from uuid import UUID

from fastapi import Depends, FastAPI, Response
from fastapi.responses import JSONResponse

from foo._internal import get_form_data, get_task_result, StructuredOutputRequest
from foo.task import create_structured_output

logger = logging.getLogger(__name__)

app = FastAPI()


@app.post("/tasks", status_code=202)
async def submit_task(
    form_data: StructuredOutputRequest = Depends(get_form_data),
) -> JSONResponse:
    """Submit a task to Prefect for background execution."""
    future = create_structured_output.delay(
        form_data.payload,
        target=form_data.target_type,
        instructions=form_data.instructions,
    )
    logger.info(f"Submitted task run: {future.task_run_id}")
    return {"task_run_id": str(future.task_run_id)}


@app.get("/tasks/{task_run_id}/status")
async def get_task_status_api(task_run_id: UUID) -> Response:
    """Checks the status of a submitted task run."""
    status, data = await get_task_result(task_run_id)

    response_data = {"task_run_id": str(task_run_id), "status": status}
    http_status_code = 200

    if status == "completed":
        response_data["result"] = data
    elif status == "error":
        response_data["message"] = data
        # Optionally set a different HTTP status for errors
    return JSONResponse(response_data, status_code=http_status_code)
```

<Accordion title="Checking Task Status with the Prefect Client">
  The `get_task_result` helper function (in `src/foo/_internal/_prefect.py`) uses the Prefect Python client to interact with the Prefect API:

  ```python src/foo/_internal/_prefect.py
  from typing import Any, Literal, cast
  from uuid import UUID


  from prefect.client.orchestration import get_client
  from prefect.client.schemas.objects import TaskRun
  from prefect.logging import get_logger

  logger = get_logger(__name__)

  Status = Literal["completed", "pending", "error"]


  def _any_task_run_result(task_run: TaskRun) -> Any:
      try:
          return cast(Any, task_run.state.result(_sync=True))  # type: ignore
      except Exception as e:
          logger.warning(f"Could not retrieve result for task run {task_run.id}: {e}")
          return None


  async def get_task_result(task_run_id: UUID) -> tuple[Status, Any]:
      """Get task result or status.

      Returns:
          tuple: (status, data)
              status: "completed", "pending", or "error"
              data: the result if completed, error message if error, None if pending
      """
      try:
          async with get_client() as client:
              task_run = await client.read_task_run(task_run_id)
              if not task_run.state:
                  return "pending", None

              if task_run.state.is_completed():
                  try:
                      result = _any_task_run_result(task_run)
                      return "completed", result
                  except Exception as e:
                      logger.warning(
                          f"Could not retrieve result for completed task run {task_run_id}: {e}"
                      )
                      return "completed", "<Could not retrieve result>"

              elif task_run.state.is_failed():
                  try:
                      error_result = _any_task_run_result(task_run)
                      error_message = (
                          str(error_result)
                          if error_result
                          else "Task failed without specific error message."
                      )
                      return "error", error_message
                  except Exception as e:
                      logger.warning(
                          f"Could not retrieve error result for failed task run {task_run_id}: {e}"
                      )
                      return "error", "<Could not retrieve error message>"

              else:
                  return "pending", None

      except Exception as e:
          logger.error(f"Error checking task status for {task_run_id}: {e}")
          return "error", f"Failed to check task status: {str(e)}"
  ```

  This function fetches the `TaskRun` object from the API and checks its `state` to determine if it's `Completed`, `Failed`, or still `Pending`/`Running`. If completed, it attempts to retrieve the result using `task_run.state.result()`. If failed, it tries to get the error message.
</Accordion>

## Building the Docker Image

A multi-stage `Dockerfile` is used to create optimized images for each service (Prefect server, task worker, and web API). This approach helps keep image sizes small and separates build dependencies from runtime dependencies.

```dockerfile Dockerfile
# Stage 1: Base image with Python and uv
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:python3.12-bookworm-slim as base

WORKDIR /app

ENV UV_SYSTEM_PYTHON=1
ENV PATH="/root/.local/bin:$PATH"

COPY pyproject.toml uv.lock* ./

# Note: We install all dependencies needed for all stages here.
# A more optimized approach might separate dependencies per stage.
RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install --system -r pyproject.toml

COPY src/ /app/src

FROM base as server

CMD ["prefect", "server", "start"]

# --- Task Worker Stage --- #
FROM base as task

# Command to start the task worker by running the task script
# This script should call `prefect.task_worker.serve(...)`
CMD ["python", "src/foo/task.py"]

# --- API Stage --- #
FROM base as api

# Command to start the FastAPI server using uvicorn
CMD ["uvicorn", "src.foo.api:app", "--host", "0.0.0.0", "--port", "8000"]

```

<Accordion title="Dockerfile Key Details">
  * **Base Stage (`base`)**: Sets up Python, `uv`, installs all dependencies from `pyproject.toml` into a base layer to make use of Docker caching, and copies the source code.
  * **Server Stage (`server`)**: Builds upon the `base` stage. Sets the default command (`CMD`) to start the Prefect server.
  * **Task Worker Stage (`task`)**: Builds upon the `base` stage. Sets the `CMD` to run the `src/foo/task.py` script, which is expected to contain the `serve()` call for the task(s).
  * **API Stage (`api`)**: Builds upon the `base` stage. Sets the `CMD` to start the FastAPI application using `uvicorn`.

  The `compose.yaml` file then uses the `target` build argument to specify which of these final stages (`server`, `task`, `api`) to use for each service container.
</Accordion>

## Declaring the application services

We use `compose.yaml` to define and run the multi-container application, managing the lifecycles of the FastAPI web server, the Prefect API server, database and task worker(s).

```yaml compose.yaml
services:

  prefect-server:
    build:
      context: .
      target: server
    ports:
      - "4200:4200"
    volumes:
      - prefect-data:/root/.prefect # Persist Prefect DB
    environment:
      # Allow connections from other containers
      PREFECT_SERVER_API_HOST: 0.0.0.0
  # Task Worker
  task:
    build:
      context: .
      target:
    deploy:
      replicas: 1 # task workers are safely horizontally scalable (think redis stream consumer groups)
    volumes:
      # Mount storage for results
      - ./task-storage:/task-storage
    depends_on:
      prefect-server:
        condition: service_started
    environment:
      PREFECT_API_URL: http://prefect-server:4200/api
      PREFECT_LOCAL_STORAGE_PATH: /task-storage
      PREFECT_LOGGING_LOG_PRINTS: "true"
      PREFECT_RESULTS_PERSIST_BY_DEFAULT: "true"
      MARVIN_ENABLE_DEFAULT_PRINT_HANDLER: "false"
      OPENAI_API_KEY: ${OPENAI_API_KEY}

    develop:
      # Optionally watch for code changes for development
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - .venv/
            - task-storage/
        - action: rebuild
          path: uv.lock

  api:
    build:
      context: .
      target: api
    volumes:
      # Mount storage for results
      - ./task-storage:/task-storage
    ports:
      - "8000:8000"
    depends_on:
      task:
        condition: service_started
      prefect-server:
        condition: service_started
    environment:
      PREFECT_API_URL: http://prefect-server:4200/api
      PREFECT_LOCAL_STORAGE_PATH: /task-storage
    develop:
      # Optionally watch for code changes for development
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - .venv/
            - task-storage/
        - action: rebuild
          path: uv.lock

volumes:
  # Named volumes for data persistence
  prefect-data: {}
  task-storage: {}
```

In a production use-case, you'd likely want to:

* write a `Dockerfile` for each service
* add a `postgres` service and [configure it as the Prefect database](/v3/manage/server/index#quickstart%3A-configure-a-postgresql-database-with-docker).
* remove the hot-reloading configuration in the `develop` section

<Accordion title="Key Service Configurations">
  - **`prefect-server`**: Runs the Prefect API server and UI.
    * `build`: Uses a multi-stage `Dockerfile` (not shown here, but present in the example repo) targeting the `server` stage.
    * `ports`: Exposes the Prefect API/UI on port `4200`.
    * `volumes`: Uses a named volume `prefect-data` to persist the Prefect SQLite database (`/root/.prefect/prefect.db`) across container restarts.
    * `PREFECT_SERVER_API_HOST=0.0.0.0`: Makes the API server listen on all interfaces within the Docker network, allowing the `task` and `api` services to connect.

  - **`task`**: Runs the Prefect task worker process (executing `python src/foo/task.py` which calls `serve`).
    * `build`: Uses the `task` stage from the `Dockerfile`.
    * `depends_on`: Ensures the `prefect-server` service is started before this service attempts to connect.
    * `PREFECT_API_URL`: Crucial setting that tells the worker where to find the Prefect API to poll for submitted task runs.
    * `PREFECT_LOCAL_STORAGE_PATH=/task-storage`: Configures the worker to store task run results in the `/task-storage` directory inside the container. This path is mounted to the host using the `task-storage` named volume via `volumes: - ./task-storage:/task-storage` (or just `task-storage:` if using a named volume without a host path binding).
    * `PREFECT_RESULTS_PERSIST_BY_DEFAULT=true`: Tells Prefect tasks to automatically save their results using the configured storage (defined by `PREFECT_LOCAL_STORAGE_PATH` in this case).
    * `PREFECT_LOGGING_LOG_PRINTS=true`: Configures the Prefect logger to capture output from `print()` statements within tasks.
    * `OPENAI_API_KEY=${OPENAI_API_KEY}`: Passes secrets needed by the task code from the host environment (via a `.env` file loaded by Docker Compose) into the container's environment.

  - **`api`**: Runs the FastAPI web application.
    * `build`: Uses the `api` stage from the `Dockerfile`.
    * `depends_on`: Waits for the `prefect-server` (required for submitting tasks and checking status) and optionally the `task` worker.
    * `PREFECT_API_URL`: Tells the FastAPI application where to send `.delay()` calls and status check requests.
    * `PREFECT_LOCAL_STORAGE_PATH`: May be needed if the API itself needs to directly read result files (though typically fetching results via `task_run.state.result()` is preferred).

  - **`volumes`**: Defines named volumes (`prefect-data`, `task-storage`) to persist data generated by the containers.
</Accordion>

## Running this example

Assuming you have obtained the code (either by cloning the repository or using `uv init` as described previously) and are in the project directory:

1. **Prerequisites:** Ensure Docker Desktop (or equivalent) with `docker compose` support is running.

2. **Build and Run Services:**
   This example's task uses [marvin](https://github.com/PrefectHQ/marvin), which (by default) requires an OpenAI API key. Provide it as an environment variable when starting the services:

   ```bash
   OPENAI_API_KEY=<your-openai-api-key> docker compose up --build --watch
   ```

   This command will:

   * `--build`: Build the container images if they don't exist or if the Dockerfile/context has changed.
   * `--watch`: Watch for changes in the project source code and automatically sync/rebuild services (useful for development).
   * Add `--detach` or `-d` to run the containers in the background.

3. **Access Services:**
   * If you cloned the existing example, check out the basic [htmx](https://htmx.org/) UI at [http://localhost:8000](http://localhost:8000)
   * FastAPI docs: [http://localhost:8000/docs](http://localhost:8000/docs)
   * Prefect UI (for observing task runs): [http://localhost:4200](http://localhost:4200)

### Cleaning up

```bash
docker compose down

# also remove the named volumes
docker compose down -v
```

## Next Steps

This example provides a repeatable pattern for integrating Prefect-managed background tasks with any python web application. You can:

* Explore the [background tasks examples repository](https://github.com/PrefectHQ/prefect-background-task-examples) for more examples.
* Adapt `src/**/*.py` to define and submit your specific web app and background tasks.
* Configure Prefect settings (environment variables in `compose.yaml`) further, for example, using different result storage or logging levels.
* Deploy these services to cloud infrastructure using managed container services.


# How to customize caching behavior
Source: https://docs-3.prefect.io/v3/advanced/caching



### Separate cache key storage from result storage

To store cache records separately from the cached value, you can configure a cache policy to use a custom storage location.

Here's an example of a cache policy configured to store cache records in a local directory:

```python
from prefect import task
from prefect.cache_policies import TASK_SOURCE, INPUTS

cache_policy = (TASK_SOURCE + INPUTS).configure(key_storage="/path/to/cache/storage")

@task(cache_policy=cache_policy)
def my_cached_task(x: int):
    return x + 42
```

Cache records will be stored in the specified directory while the persisted results will continue to be stored in `~/prefect/storage`.

To store cache records in a remote object store such as S3, pass a storage block instead:

```python
from prefect import task
from prefect.cache_policies import TASK_SOURCE, INPUTS

from prefect_aws import S3Bucket, AwsCredentials

s3_bucket = S3Bucket(
    credentials=AwsCredentials(
        aws_access_key_id="my-access-key-id",
        aws_secret_access_key="my-secret-access-key",
    ),
    bucket_name="my-bucket",
)
# save the block to ensure it is available across machines
s3_bucket.save("my-cache-records-bucket")

cache_policy = (TASK_SOURCE + INPUTS).configure(key_storage=s3_bucket)

@task(cache_policy=cache_policy)
def my_cached_task(x: int):
    return x + 42
```

Storing cache records in a remote object store allows you to share cache records across multiple machines.

### Isolate cache access

You can control concurrent access to cache records by setting the `isolation_level` parameter on the cache policy. Prefect supports two isolation levels: `READ_COMMITTED` and `SERIALIZABLE`.

By default, cache records operate with a `READ_COMMITTED` isolation level. This guarantees that reading a cache record will see the latest committed cache value,
but allows multiple executions of the same task to occur simultaneously.

Consider the following example:

```python
from prefect import task
from prefect.cache_policies import INPUTS
import threading


cache_policy = INPUTS

@task(cache_policy=cache_policy)
def my_task_version_1(x: int):
    print("my_task_version_1 running")
    return x + 42

@task(cache_policy=cache_policy)
def my_task_version_2(x: int):
    print("my_task_version_2 running")
    return x + 43

if __name__ == "__main__":
    thread_1 = threading.Thread(target=my_task_version_1, args=(1,))
    thread_2 = threading.Thread(target=my_task_version_2, args=(1,))

    thread_1.start()
    thread_2.start()

    thread_1.join()
    thread_2.join()
```

When running this script, both tasks will execute in parallel and perform work despite both tasks using the same cache key.

For stricter isolation, you can use the `SERIALIZABLE` isolation level. This ensures that only one execution of a task occurs at a time for a given cache
record via a locking mechanism.

When setting `isolation_level` to `SERIALIZABLE`, you must also provide a `lock_manager` that implements locking logic for your system.

Here's an updated version of the previous example that uses `SERIALIZABLE` isolation:

```python
import threading

from prefect import task
from prefect.cache_policies import INPUTS
from prefect.locking.memory import MemoryLockManager
from prefect.transactions import IsolationLevel

cache_policy = INPUTS.configure(
    isolation_level=IsolationLevel.SERIALIZABLE,
    lock_manager=MemoryLockManager(),
)


@task(cache_policy=cache_policy)
def my_task_version_1(x: int):
    print("my_task_version_1 running")
    return x + 42


@task(cache_policy=cache_policy)
def my_task_version_2(x: int):
    print("my_task_version_2 running")
    return x + 43


if __name__ == "__main__":
    thread_1 = threading.Thread(target=my_task_version_1, args=(2,))
    thread_2 = threading.Thread(target=my_task_version_2, args=(2,))

    thread_1.start()
    thread_2.start()

    thread_1.join()
    thread_2.join()
```

In this example, only one of the tasks will run and the other will use the cached value.

<Note>
  **Locking in a distributed setting**

  To manage locks in a distributed setting, you will need to use a storage system for locks that is accessible by all of your execution infrastructure.

  We recommend using the `RedisLockManager` provided by `prefect-redis` in conjunction with a shared Redis instance:

  ```python
  from prefect import task
  from prefect.cache_policies import TASK_SOURCE, INPUTS
  from prefect.transactions import IsolationLevel

  from prefect_redis import RedisLockManager

  cache_policy = (INPUTS + TASK_SOURCE).configure(
      isolation_level=IsolationLevel.SERIALIZABLE,
      lock_manager=RedisLockManager(host="my-redis-host"),
  )

  @task(cache_policy=cache_policy)
  def my_cached_task(x: int):
      return x + 42
  ```
</Note>

### Coordinate caching across multiple tasks

To coordinate cache writes across tasks, you can run multiple tasks within a single [*transaction*](/v3/develop/transactions).

```python
from prefect import task, flow
from prefect.transactions import transaction


@task(cache_key_fn=lambda *args, **kwargs: "static-key-1")
def load_data():
    return "some-data"


@task(cache_key_fn=lambda *args, **kwargs: "static-key-2")
def process_data(data, fail):
    if fail:
        raise RuntimeError("Error! Abort!")

    return len(data)


@flow
def multi_task_cache(fail: bool = True):
    with transaction():
        data = load_data()
        process_data(data=data, fail=fail)
```

When this flow is run with the default parameter values it will fail on the `process_data` task after the `load_data` task has succeeded.

However, because caches are only written to when a transaction is *committed*, the `load_data` task will *not* write a result to its cache key location until
the `process_data` task succeeds as well.

On a subsequent run with `fail=False`, both tasks will be re-executed and the results will be cached.

### Handling Non-Serializable Objects

You may have task inputs that can't (or shouldn't) be serialized as part of the cache key. There are two direct approaches to handle this, both of which based on the same idea.

You can **adjust the serialization logic** to only serialize certain properties of an input:

1. Using a custom cache key function:

```python
from prefect import flow, task
from prefect.cache_policies import CacheKeyFnPolicy, RUN_ID
from prefect.context import TaskRunContext
from pydantic import BaseModel, ConfigDict

class NotSerializable:
    def __getstate__(self):
        raise TypeError("NooOoOOo! I will not be serialized!")

class ContainsNonSerializableObject(BaseModel):
    model_config = ConfigDict(arbitrary_types_allowed=True)

    name: str
    bad_object: NotSerializable

def custom_cache_key_fn(context: TaskRunContext, parameters: dict) -> str:
    return parameters["some_object"].name

@task(cache_policy=CacheKeyFnPolicy(cache_key_fn=custom_cache_key_fn) + RUN_ID)
def use_object(some_object: ContainsNonSerializableObject) -> str:
    return f"Used {some_object.name}"


@flow
def demo_flow():
    obj = ContainsNonSerializableObject(name="test", bad_object=NotSerializable())
    state = use_object(obj, return_state=True) # Not cached!
    assert state.name == "Completed"
    other_state = use_object(obj, return_state=True) # Cached!
    assert other_state.name == "Cached"
    assert state.result() == other_state.result()
```

2. Using Pydantic's [custom serialization](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers) on your input types:

```python
from pydantic import BaseModel, ConfigDict, model_serializer
from prefect import flow, task
from prefect.cache_policies import INPUTS, RUN_ID

class NotSerializable:
    def __getstate__(self):
        raise TypeError("NooOoOOo! I will not be serialized!")

class ContainsNonSerializableObject(BaseModel):
    model_config = ConfigDict(arbitrary_types_allowed=True)

    name: str
    bad_object: NotSerializable

    @model_serializer
    def ser_model(self) -> dict:
        """Only serialize the name, not the problematic object"""
        return {"name": self.name}

@task(cache_policy=INPUTS + RUN_ID)
def use_object(some_object: ContainsNonSerializableObject) -> str:
    return f"Used {some_object.name}"

@flow
def demo_flow():
    some_object = ContainsNonSerializableObject(
        name="test",
        bad_object=NotSerializable()
    )
    state = use_object(some_object, return_state=True) # Not cached!
    assert state.name == "Completed"
    other_state = use_object(some_object, return_state=True) # Cached!
    assert other_state.name == "Cached"
    assert state.result() == other_state.result()
```

Choose the approach that best fits your needs:

* Use Pydantic models when you want consistent serialization across your application
* Use custom cache key functions when you need different caching logic for different tasks


# How to cancel running workflows
Source: https://docs-3.prefect.io/v3/advanced/cancel-workflows



You can cancel a scheduled or in-progress flow run from the CLI, UI, REST API, or Python client.

{/*
  <!-- vale off -->
  */}

When requesting cancellation, the flow run moves to a "Cancelling" state.
If the deployment is associated with a work pool, then the worker monitors
the state of flow runs and detects that cancellation is requested.
The worker then sends a signal to the flow run infrastructure, requesting termination of the run.
If the run does not terminate after a grace period (default of 30 seconds), the infrastructure is killed, ensuring the flow run exits.

{/*
  <!-- vale on -->
  */}

<Warning>
  **A deployment is required**

  Flow run cancellation requires that the flow run is associated with a deployment.
  A monitoring process must be running to enforce the cancellation.

  Inline nested flow runs (those created without `run_deployment`), cannot be cancelled without cancelling the parent flow run.
  To cancel a nested flow run independent of its parent flow run, we recommend deploying it separately
  and starting it using the [run\_deployment](/v3/deploy/index)
  function.
</Warning>

Cancellation is resilient to restarts of Prefect workers.
To enable this, we attach metadata about the created infrastructure to the flow run.
Internally, this is referred to as the `infrastructure_pid` or infrastructure identifier.
Generally, this is composed of two parts:

* Scope: identifying where the infrastructure is running.
* ID: a unique identifier for the infrastructure within the scope.

{/*
  <!-- vale off -->
  */}

The scope ensures that Prefect does not kill the wrong infrastructure.
For example, workers running on multiple machines may have overlapping process IDs but should not have a matching scope.

{/*
  <!-- vale on -->
  */}

The identifiers for infrastructure types are:

* Processes: The machine hostname and the PID.
* Docker Containers: The Docker API URL and container ID.
* Kubernetes Jobs: The Kubernetes cluster name and the job name.

While the cancellation process is robust, there are a few issues than can occur:

* If the infrastructure for the flow run does not support cancellation, cancellation will not work.
* If the identifier scope does not match when attempting to cancel a flow run, the worker cannot cancel the flow run.
  Another worker may attempt cancellation.
* If the infrastructure associated with the run cannot be found or has already been killed, the worker marks the flow run as cancelled.
* If the `infrastructre_pid` is missing, the flow run is marked as cancelled but cancellation cannot be enforced.
* If the worker runs into an unexpected error during cancellation, the flow run may or may not be cancelled
  depending on where the error occurred. The worker will try again to cancel the flow run. Another worker may attempt cancellation.

### Cancel through the CLI

From the command line in your execution environment, you can cancel a flow run by using the
`prefect flow-run cancel` CLI command, passing the ID of the flow run.

```bash
prefect flow-run cancel 'a55a4804-9e3c-4042-8b59-b3b6b7618736'
```

### Cancel through the UI

Navigate to the flow run's detail page and click `Cancel` in the upper right corner.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/flow-run-cancellation-ui.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=6e692111f666595d04889e2e26186ebb" alt="Prefect UI" data-og-width="2484" width="2484" data-og-height="619" height="619" data-path="v3/img/ui/flow-run-cancellation-ui.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/flow-run-cancellation-ui.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=da4cf5fef78b5f9f3ab144f0ae6b56a8 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/flow-run-cancellation-ui.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=917aba861a600e28071bbeff920d168f 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/flow-run-cancellation-ui.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=98251b34c529c3598a1124bcdd359788 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/flow-run-cancellation-ui.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=d99273805a2a9391839f2c44fb5ed6a4 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/flow-run-cancellation-ui.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=78e0cb692fc0219ab3318dc1bac96754 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/flow-run-cancellation-ui.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=ee4a0d68779a919dc8c25399861c8ec0 2500w" data-optimize="true" data-opv="2" />


# How to create custom blocks
Source: https://docs-3.prefect.io/v3/advanced/custom-blocks



### Create a new block type

To create a custom block type, define a class that subclasses `Block`. The `Block` base class builds
on Pydantic's `BaseModel`, so you can declare custom fields just like a [Pydantic model](https://pydantic-docs.helpmanual.io/usage/models/#basic-model-usage).

We've already seen an example of a `Cube` block that represents a cube and holds information about the length of each edge in inches:

{/* pmd-metadata: notest */}

```python
from prefect.blocks.core import Block

class Cube(Block):
    edge_length_inches: float


Cube.register_type_and_schema()
```

### Register custom blocks

In addition to the `register_type_and_schema` method shown above, you can register blocks from a Python module with a CLI command:

```bash
prefect block register --module prefect_aws.credentials
```

This command is useful for registering all blocks found within a module in a [Prefect Integration library](/integrations/).

Alternatively, if a custom block was created in a `.py` file, you can register the block with the CLI command:

```bash
prefect block register --file my_block.py
```

Block documents can now be created with the registered block schema.

### Secret fields

All block values are encrypted before being stored.
If you have values that you would not like visible in the UI or in logs,
use the `SecretStr` field type provided by Pydantic to automatically obfuscate those values.
You can use this capability for fields that store credentials such as passwords and API tokens.

Here's an example of an `AwsCredentials` block that uses `SecretStr`:

```python
from typing import Optional

from prefect.blocks.core import Block
from pydantic import SecretStr

class AwsCredentials(Block):
    aws_access_key_id: Optional[str] = None
    aws_secret_access_key: Optional[SecretStr] = None
    aws_session_token: Optional[str] = None
    profile_name: Optional[str] = None
    region_name: Optional[str] = None
```

Since `aws_secret_access_key` has the `SecretStr` type hint assigned to it,
the value of that field is not exposed if the object is logged:

{/* pmd-metadata: notest */}

```python
aws_credentials_block = AwsCredentials(
    aws_access_key_id="AKIAJKLJKLJKLJKLJKLJK",
    aws_secret_access_key="secret_access_key"
)

print(aws_credentials_block)
# aws_access_key_id='AKIAJKLJKLJKLJKLJKLJK' aws_secret_access_key=SecretStr('**********') aws_session_token=None profile_name=None region_name=None
```

Prefect's `SecretDict` field type allows you to add a dictionary field to your block
that automatically obfuscates values at all levels in the UI or in logs.
This capability is useful for blocks where typing or structure of secret fields is not known until configuration time.

Here's an example of a block that uses `SecretDict`:

```python
from prefect.blocks.core import Block
from prefect.blocks.fields import SecretDict


class SystemConfiguration(Block):
    system_secrets: SecretDict
    system_variables: dict


system_configuration_block = SystemConfiguration(
    system_secrets={
        "password": "p@ssw0rd",
        "api_token": "token_123456789",
        "private_key": "<private key here>",
    },
    system_variables={
        "self_destruct_countdown_seconds": 60,
        "self_destruct_countdown_stop_time": 7,
    },
)
```

`system_secrets` is obfuscated when `system_configuration_block` is displayed, but `system_variables` show up in plain-text:

{/* pmd-metadata: notest */}

```python
print(system_configuration_block)
# SystemConfiguration(
#   system_secrets=SecretDict('{'password': '**********', 'api_token': '**********', 'private_key': '**********'}'), 
#   system_variables={'self_destruct_countdown_seconds': 60, 'self_destruct_countdown_stop_time': 7}
# )
```

### Customize a block's display

You can set metadata fields on a block type's subclass to control how a block displays.

Available metadata fields include:

| Property           | Description                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `_block_type_name` | Display name of the block in the UI. Defaults to the class name.                                                                              |
| `_block_type_slug` | Unique slug used to reference the block type in the API. Defaults to a lowercase, dash-delimited version of the block type name.              |
| `_logo_url`        | URL pointing to an image that should be displayed for the block type in the UI. Default to `None`.                                            |
| `_description`     | Short description of block type. Defaults to docstring, if provided.                                                                          |
| `_code_example`    | Short code snippet shown in UI for how to load/use block type. Defaults to first example provided in the docstring of the class, if provided. |

### Update custom `Block` types

Here's an example of how to add a `bucket_folder` field to your custom `S3Bucket` block; it represents the default path to
read and write objects from (this field exists on [our implementation](https://github.com/PrefectHQ/prefect/blob/main/src/integrations/prefect-aws/prefect_aws/s3.py)).

Add the new field to the class definition:

{/* pmd-metadata: notest */}

```python
from typing import Optional

from prefect.blocks.core import Block


class S3Bucket(Block):
    bucket_name: str
    credentials: AwsCredentials
    bucket_folder: Optional[str] = None
    ...
```

Then [register the updated block type](#register-blocks) with either your Prefect Cloud account or your self-hosted Prefect server instance.

If you have any existing blocks of this type that were created before the update and
you'd prefer to not re-create them, migrate them to the new version of your block type by adding the missing values:

{/* pmd-metadata: notest */}

```python
# Bypass Pydantic validation to allow your local Block class to load the old block version
my_s3_bucket_block = S3Bucket.load("my-s3-bucket", validate=False)

# Set the new field to an appropriate value
my_s3_bucket_block.bucket_path = "my-default-bucket-path"

# Overwrite the old block values and update the expected fields on the block
my_s3_bucket_block.save("my-s3-bucket", overwrite=True)
```


# How to daemonize worker processes
Source: https://docs-3.prefect.io/v3/advanced/daemonize-processes

Learn how Prefect flow deployments enable configuring flows for scheduled and remote execution with workers.

When running workflow applications, it's helpful to create long-running processes that
run at startup and are resilient to failure.

This guide shows you how to set up a systemd service to create long-running Prefect processes
that poll for scheduled flow runs, including how to:

* create a Linux user
* install and configure Prefect
* set up a systemd service for the Prefect worker or `.serve` process

## Prerequisites

* An environment with a linux operating system with [systemd](https://systemd.io/) and Python 3.9
  or later.
* A superuser account that can run `sudo` commands.
* A Prefect Cloud account, or an instance of a Prefect server running on your network.

If using an [AWS t2-micro EC2 instance](https://aws.amazon.com/ec2/instance-types/t2/) with an
AWS Linux image, you can install Python and pip with `sudo yum install -y python3 python3-pip`.

## Steps

A systemd service is ideal for running a long-lived process on a Linux VM or physical Linux server.
You will use systemd and learn how to automatically start a
[Prefect worker](/v3/deploy/infrastructure-concepts/workers/) or
long-lived [`serve` process](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes) when Linux starts.
This approach provides resilience by automatically restarting the process if it crashes.

### Step 1: Add a user

Create a user account on your Linux system for the Prefect process.
You can run a worker or serve process as root, but it's best practice to create a dedicated user.

In a terminal, run:

```bash
sudo useradd -m prefect
sudo passwd prefect
```

When prompted, enter a password for the `prefect` account.

Next, log in to the `prefect` account by running:

```bash
sudo su prefect
```

### Step 2: Install Prefect

Run:

```bash
pip3 install prefect
```

This guide assumes you are installing Prefect globally, rather than a virtual environment.
If running a systemd service in a virtual environment, change the ExecPath.
For example, if using [venv](https://docs.python.org/3/library/venv.html), change the ExecPath
to target the `prefect` application in the `bin` subdirectory of your virtual environment.

Next, set up your environment so the Prefect client knows which server to connect to.

If connecting to Prefect Cloud, follow [the instructions](v3/how-to-guides/cloud/connect-to-cloud)
to obtain an API key, and then run the following:

```bash
prefect cloud login -k YOUR_API_KEY
```

When prompted, choose the Prefect workspace to log in to.

If connecting to a self-hosted Prefect server instance instead of a Prefect Cloud account, run the following command, substituting the IP address of your server:

```bash
prefect config set PREFECT_API_URL=http://your-prefect-server-IP:4200
```

Run the `exit` command to sign out of the `prefect` Linux account.
This command switches you back to your sudo-enabled account where you can run the commands in the
next section.

### Step 3: Set up a systemd service

See the section below if you are setting up a Prefect worker.
Skip to the [next section](#setting-up-a-systemd-service-for-serve) if you are setting up a
Prefect `.serve` process.

#### Setting up a systemd service for a Prefect worker

Move into the `/etc/systemd/system` folder and open a file for editing.
We use the Vim text editor below.

```bash
cd /etc/systemd/system
sudo vim my-prefect-service.service
```

```txt my-prefect-service.service
[Unit]
Description=Prefect worker

[Service]
User=prefect
WorkingDirectory=/home
ExecStart=prefect worker start --pool YOUR_WORK_POOL_NAME
Restart=always

[Install]
WantedBy=multi-user.target
```

Make sure you substitute your own work pool name.

#### Setting up a systemd service for `.serve`

Copy your flow entrypoint Python file and any other files needed for your flow to run into the
`/home` directory (or the directory of your choice).

Here's a basic example flow:

```python my_file.py
from prefect import flow


@flow(log_prints=True)
def say_hi():
    print("Hello!")

if __name__=="__main__":
    say_hi.serve(name="served and daemonized deployment")
```

To make changes to your flow code without restarting your process, push your
code to git-based cloud storage (GitHub, BitBucket, GitLab) and use `flow.from_source().serve()`,
as in the example below.

```python my_remote_flow_code_file.py
if __name__ == "__main__":
    flow.from_source(
        source="https://github.com/org/repo.git",
        entrypoint="path/to/my_remote_flow_code_file.py:say_hi",
    ).serve(name="deployment-with-github-storage")
```

Make sure you substitute your own flow code entrypoint path.

If you change the flow entrypoint parameters, you must restart the process.

Move into the `/etc/systemd/system` folder and open a file for editing.
This example below uses Vim.

```bash
cd /etc/systemd/system
sudo vim my-prefect-service.service
```

```txt my-prefect-service.service
[Unit]
Description=Prefect serve

[Service]
User=prefect
WorkingDirectory=/home
ExecStart=python3 my_file.py
Restart=always

[Install]
WantedBy=multi-user.target
```

### Step 4: Save, enable, and start the service

To save the file and exit Vim, hit the escape key, type `:wq!`, then press the return key.

Next, make systemd aware of your new service by running:

```bash
sudo systemctl daemon-reload
```

Then, enable the service by running:

```bash
sudo systemctl enable my-prefect-service
```

This command ensures it runs when your system boots.

Next, start the service:

```bash
sudo systemctl start my-prefect-service
```

Run your deployment from the UI and check the logs on the **Flow Runs** page.

You can see if your daemonized Prefect worker or serve process is running, and the
Prefect logs with `systemctl status my-prefect-service`.

You now have a systemd service that starts when your system boots, which will restart if it ever crashes.


# How to maintain your Prefect database
Source: https://docs-3.prefect.io/v3/advanced/database-maintenance

Monitor and maintain your PostgreSQL database for self-hosted Prefect deployments

Self-hosted Prefect deployments require database maintenance to ensure optimal performance and manage disk usage. This guide provides monitoring queries and maintenance strategies for PostgreSQL databases.

<Warning>
  This guide is for advanced users managing production deployments. Always test maintenance operations in a non-production environment first, if possible.

  Exact numbers included in this guide will vary based on your workload and installation.
</Warning>

## Quick reference

**Daily tasks:**

* Check disk space and table sizes
* Monitor bloat levels (> 50% requires action)
* Run retention policies for old flow runs

**Weekly tasks:**

* Review autovacuum performance
* Check index usage and bloat
* Analyze high-traffic tables

**Red flags requiring immediate action:**

* Disk usage > 80%
* Table bloat > 100%
* Connection count approaching limit
* Autovacuum hasn't run in 24+ hours

## Database growth monitoring

Prefect stores entities like events, flow runs, task runs, and logs that accumulate over time. Monitor your database regularly to understand growth patterns specific to your usage.

### Check table sizes

```sql
-- Total database size
SELECT pg_size_pretty(pg_database_size('prefect')) AS database_size;

-- Table sizes with row counts
SELECT 
    schemaname,
    relname AS tablename,
    pg_size_pretty(pg_total_relation_size(schemaname||'.'||relname)) AS total_size,
    to_char(n_live_tup, 'FM999,999,999') AS row_count
FROM pg_stat_user_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||relname) DESC
LIMIT 20;
```

### Monitor disk space

Track overall disk usage to prevent outages:

```sql
-- Check database disk usage
SELECT 
    current_setting('data_directory') AS data_directory,
    pg_size_pretty(pg_database_size('prefect')) AS database_size,
    pg_size_pretty(pg_total_relation_size('public.events')) AS events_table_size,
    pg_size_pretty(pg_total_relation_size('public.log')) AS log_table_size;

-- Check available disk space (requires pg_stat_disk extension or shell access)
-- Run from shell: df -h /path/to/postgresql/data
```

Common large tables in Prefect databases:

* `events` - Automatically generated for all state changes (often the largest table)
* `log` - Flow and task run logs
* `flow_run` and `task_run` - Execution records
* `flow_run_state` and `task_run_state` - State history

### Monitor table bloat

PostgreSQL tables can accumulate "dead tuples" from updates and deletes. Monitor bloat percentage to identify tables needing maintenance:

```sql
SELECT
    schemaname,
    relname AS tablename,
    n_live_tup AS live_tuples,
    n_dead_tup AS dead_tuples,
    CASE WHEN n_live_tup > 0 
        THEN round(100.0 * n_dead_tup / n_live_tup, 2)
        ELSE 0
    END AS bloat_percent,
    last_vacuum,
    last_autovacuum
FROM pg_stat_user_tables
WHERE schemaname = 'public' 
    AND n_dead_tup > 1000
ORDER BY bloat_percent DESC;
```

### Monitor index bloat

Indexes can also bloat and impact performance:

```sql
-- Check index sizes and bloat
SELECT 
    schemaname,
    relname AS tablename,
    indexrelname AS indexname,
    pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
    idx_scan AS index_scans,
    idx_tup_read AS tuples_read,
    idx_tup_fetch AS tuples_fetched
FROM pg_stat_user_indexes
WHERE schemaname = 'public'
ORDER BY pg_relation_size(indexrelid) DESC
LIMIT 20;
```

## PostgreSQL VACUUM

VACUUM reclaims storage occupied by dead tuples. While PostgreSQL runs autovacuum automatically, you may need manual intervention for heavily updated tables.

### Manual VACUUM

For tables with high bloat percentages:

```sql
-- Standard VACUUM (doesn't lock table)
VACUUM ANALYZE flow_run;
VACUUM ANALYZE task_run;
VACUUM ANALYZE log;

-- VACUUM FULL (rebuilds table, requires exclusive lock)
-- WARNING: This COMPLETELY LOCKS the table - no reads or writes!
-- Can take HOURS on large tables. Only use as last resort.
VACUUM FULL flow_run;

-- Better alternative: pg_repack (if installed)
-- Rebuilds tables online without blocking
-- pg_repack -t flow_run -d prefect
```

### Monitor autovacuum

Check if autovacuum is keeping up with your workload:

```sql
-- Show autovacuum settings
SHOW autovacuum;
SHOW autovacuum_vacuum_scale_factor;
SHOW autovacuum_vacuum_threshold;

-- Check when tables were last vacuumed
SELECT 
    schemaname,
    relname AS tablename,
    last_vacuum,
    last_autovacuum,
    vacuum_count,
    autovacuum_count
FROM pg_stat_user_tables
WHERE schemaname = 'public'
ORDER BY last_autovacuum NULLS FIRST;
```

### Tune autovacuum for Prefect workloads

Depending on your workload, your write patterns may require more aggressive autovacuum settings than defaults:

```sql
-- For high-volume events table (INSERT/DELETE heavy)
ALTER TABLE events SET (
    autovacuum_vacuum_scale_factor = 0.05,  -- Default is 0.2
    autovacuum_vacuum_threshold = 1000,
    autovacuum_analyze_scale_factor = 0.02  -- Keep stats current
);

-- For state tables (INSERT-heavy)
ALTER TABLE flow_run_state SET (
    autovacuum_vacuum_scale_factor = 0.1,
    autovacuum_analyze_scale_factor = 0.05
);

-- For frequently updated tables
ALTER TABLE flow_run SET (
    autovacuum_vacuum_scale_factor = 0.1,
    autovacuum_vacuum_threshold = 500
);
```

### When to take action

**Bloat thresholds:**

* **\< 20% bloat**: Normal, autovacuum should handle
* **20-50% bloat**: Monitor closely, consider manual VACUUM
* **> 50% bloat**: Manual VACUUM recommended
* **> 100% bloat**: Significant performance impact, urgent action needed

**Warning signs:**

* Autovacuum hasn't run in > 24 hours on active tables
* Query performance degrading over time
* Disk space usage growing faster than data volume

## Data retention

Implement data retention policies to manage database growth. The following example shows a Prefect flow that safely deletes old flow runs using the Prefect API:

<Note>
  Using the Prefect API ensures proper cleanup of all related data, including logs and artifacts. The API handles cascade deletions and triggers necessary background tasks.
</Note>

{/* pmd-metadata: notest */}

```python
import asyncio
from datetime import datetime, timedelta, timezone
from prefect import flow, task, get_run_logger
from prefect.client.orchestration import get_client
from prefect.client.schemas.filters import FlowRunFilter, FlowRunFilterState, FlowRunFilterStateType, FlowRunFilterStartTime
from prefect.client.schemas.objects import StateType

@task
async def delete_old_flow_runs(
    days_to_keep: int = 30,
    batch_size: int = 100
):
    """Delete completed flow runs older than specified days."""
    logger = get_run_logger()
    
    async with get_client() as client:
        cutoff = datetime.now(timezone.utc) - timedelta(days=days_to_keep)
        
        # Create filter for old completed flow runs
        # Note: Using start_time because created time filtering is not available
        flow_run_filter = FlowRunFilter(
            start_time=FlowRunFilterStartTime(before_=cutoff),
            state=FlowRunFilterState(
                type=FlowRunFilterStateType(
                    any_=[StateType.COMPLETED, StateType.FAILED, StateType.CANCELLED]
                )
            )
        )
        
        # Get flow runs to delete
        flow_runs = await client.read_flow_runs(
            flow_run_filter=flow_run_filter,
            limit=batch_size
        )
        
        deleted_total = 0
        
        while flow_runs:
            batch_deleted = 0
            failed_deletes = []
            
            # Delete each flow run through the API
            for flow_run in flow_runs:
                try:
                    await client.delete_flow_run(flow_run.id)
                    deleted_total += 1
                    batch_deleted += 1
                except Exception as e:
                    logger.warning(f"Failed to delete flow run {flow_run.id}: {e}")
                    failed_deletes.append(flow_run.id)
                    
                # Rate limiting - adjust based on your API capacity
                if batch_deleted % 10 == 0:
                    await asyncio.sleep(0.5)
                    
            logger.info(f"Deleted {batch_deleted}/{len(flow_runs)} flow runs (total: {deleted_total})")
            if failed_deletes:
                logger.warning(f"Failed to delete {len(failed_deletes)} flow runs")
            
            # Get next batch
            flow_runs = await client.read_flow_runs(
                flow_run_filter=flow_run_filter,
                limit=batch_size
            )
            
            # Delay between batches to avoid overwhelming the API
            await asyncio.sleep(1.0)
        
        logger.info(f"Retention complete. Total deleted: {deleted_total}")

@flow(name="database-retention")
async def retention_flow():
    """Run database retention tasks."""
    await delete_old_flow_runs(
        days_to_keep=30,
        batch_size=100
    )
```

### Direct SQL approach

In some cases, you may need to use direct SQL for performance reasons or when the API is unavailable. Be aware that direct deletion bypasses application-level cascade logic:

{/* pmd-metadata: notest */}

```python
# Direct SQL only deletes what's defined by database foreign keys
# Logs and artifacts may be orphaned without proper cleanup
async with asyncpg.connect(connection_url) as conn:
    await conn.execute("""
        DELETE FROM flow_run 
        WHERE created < $1 
        AND state_type IN ('COMPLETED', 'FAILED', 'CANCELLED')
    """, cutoff)
```

### Important considerations

1. **Filtering limitation**: The current API filters by `start_time` (when the flow run began execution), not `created` time (when the flow run was created in the database). This means flows that were created but never started won't be deleted.

2. **Test first**: Run with `SELECT` instead of `DELETE` to preview what will be removed

3. **Start conservative**: Begin with longer retention periods and adjust based on needs

4. **Monitor performance**: Large deletes can impact database performance

5. **Backup**: Always backup before major cleanup operations

## Event retention

Events are automatically generated for all state changes in Prefect and can quickly become the largest table in your database. Prefect includes built-in event retention that automatically removes old events.

### Configure event retention

The default retention period is 7 days. For high-volume deployments, consider reducing this:

```bash
# Set retention to 2 days (as environment variable)
export PREFECT_EVENTS_RETENTION_PERIOD="2d"

# Or in your prefect configuration
prefect config set PREFECT_EVENTS_RETENTION_PERIOD="2d"
```

### Check event table size

Monitor your event table growth:

```sql
-- Event table size and row count
SELECT 
    pg_size_pretty(pg_total_relation_size('public.events')) AS total_size,
    to_char(count(*), 'FM999,999,999') AS row_count,
    min(occurred) AS oldest_event,
    max(occurred) AS newest_event
FROM events;
```

<Note>
  Events are used for automations and triggers. Ensure your retention period keeps events long enough for your automation needs.
</Note>

## Connection monitoring

Monitor connection usage to prevent exhaustion:

```sql
SELECT 
    count(*) AS total_connections,
    count(*) FILTER (WHERE state = 'active') AS active,
    count(*) FILTER (WHERE state = 'idle') AS idle,
    (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections
FROM pg_stat_activity;
```

## Automating database maintenance

### Schedule maintenance tasks

Schedule the retention flow to run automatically. See [how to create deployments](/v3/how-to-guides/deployments/create-deployments) for creating scheduled deployments.

For example, you could run the retention flow daily at 2 AM to clean up old flow runs.

### Recommended maintenance schedule

* **Hourly**: Monitor disk space and connection count
* **Daily**: Run retention policies, check bloat levels
* **Weekly**: Analyze tables, review autovacuum performance
* **Monthly**: REINDEX heavily used indexes, full database backup

## Troubleshooting common issues

### "VACUUM is taking forever"

* Check for long-running transactions blocking VACUUM:
  ```sql
  SELECT pid, age(clock_timestamp(), query_start), usename, query 
  FROM pg_stat_activity 
  WHERE state <> 'idle' AND query NOT ILIKE '%vacuum%' 
  ORDER BY age DESC;
  ```
* Consider using `pg_repack` instead of `VACUUM FULL`
* Run during low-traffic periods

### "Database is growing despite retention policies"

* Verify event retention is configured: `prefect config view | grep EVENTS_RETENTION`
* Check if autovacuum is running on the events table
* Ensure retention flow is actually executing (check flow run history)

### "Queries are getting slower over time"

* Update table statistics: `ANALYZE;`
* Check for missing indexes using `pg_stat_user_tables`
* Review query plans with `EXPLAIN ANALYZE`

### "Connection limit reached"

* Implement connection pooling immediately
* Check for connection leaks: connections in 'idle' state for hours
* Reduce Prefect worker/agent connection counts

## Further reading

* [PostgreSQL documentation on VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html)
* [PostgreSQL routine maintenance](https://www.postgresql.org/docs/current/routine-vacuuming.html)
* [Monitoring PostgreSQL](https://www.postgresql.org/docs/current/monitoring-stats.html)
* [pg\_repack extension](https://github.com/reorg/pg_repack)


# How to build deployments via CI/CD
Source: https://docs-3.prefect.io/v3/advanced/deploy-ci-cd

CI/CD resources for working with Prefect.

export const home = {
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/guides/getting-started",
  cli: "https://docs.prefect.io/v3/api-ref/cli/index",
  api: "https://app.prefect.cloud/api/docs",
  helm: "https://github.com/PrefectHQ/prefect-helm/tree/main/charts"
};

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

Many organizations deploy Prefect workflows through their CI/CD process.
Each organization has their own unique CI/CD setup, but a common pattern is to use CI/CD to manage
Prefect [deployments](/v3/concepts/deployments).
Combining Prefect's deployment features with CI/CD tools enables efficient management of flow code
updates, scheduling changes, and container builds.
This guide uses [GitHub Actions](https://docs.github.com/en/actions) to implement a CI/CD process,
but these concepts are generally applicable across many CI/CD tools.

Note that Prefect's primary ways for creating deployments, a `.deploy` flow method or a `prefect.yaml`
configuration file, are both designed for building and pushing images to a Docker registry.

## Get started with GitHub Actions and Prefect

In this example, you'll write a GitHub Actions workflow that runs each time you push to your repository's
`main` branch. This workflow builds and pushes a Docker image containing your flow code to Docker Hub, then deploys the flow to Prefect Cloud.

### Repository secrets

Your CI/CD process must be able to authenticate with Prefect to deploy flows.

Deploy flows securely and non-interactively in your CI/CD process by saving your `PREFECT_API_URL` and
`PREFECT_API_KEY` [as secrets in your repository's settings](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). This allows them to be accessed in your CI/CD runner's environment without exposing them in any scripts or configuration files.

In this scenario, deploying flows involves building and pushing Docker images, so add `DOCKER_USERNAME`
and `DOCKER_PASSWORD` as secrets to your repository as well.

Create secrets for GitHub Actions in your repository under
**Settings -> Secrets and variables -> Actions -> New repository secret**:

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-secrets.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=9c199882e6a271c5f2bc53e0b0e93c79" alt="Creating a GitHub Actions secret" data-og-width="1371" width="1371" data-og-height="913" height="913" data-path="v3/img/guides/github-secrets.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-secrets.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=bddd9852db03e557328fc7ecd6a4c800 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-secrets.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6d11d1041d5e4eb8fb3f628e3eedbafa 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-secrets.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6c23a0008c532b9ba97b3ee31bd8f7ad 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-secrets.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=eff31a6b7c3c2a6055955aca8ad6cab2 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-secrets.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=b78f26f760326592c5aea8c79cfa113f 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-secrets.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=dd3a00c3ac73adb0ea664140fd3fddc3 2500w" data-optimize="true" data-opv="2" />

### Write a GitHub workflow

To deploy your flow through GitHub Actions, you need a workflow YAML file. GitHub looks for workflow
YAML files in the `.github/workflows/` directory in the root of your repository. In their simplest form,
GitHub workflow files are made up of triggers and jobs.

The `on:` trigger is set to run the workflow each time a push occurs on the `main` branch of the repository.

The `deploy` job is comprised of four `steps`:

* **`Checkout`** clones your repository into the GitHub Actions runner so you can reference files or
  run scripts from your repository in later steps.
* **`Log in to Docker Hub`** authenticates to DockerHub so your image can be pushed to the Docker
  registry in your DockerHub account. [docker/login-action](https://github.com/docker/login-action) is an
  existing GitHub action maintained by Docker. `with:` passes values into the Action, similar to passing
  parameters to a function.
* **`Setup Python`** installs your selected version of Python.
* **`Prefect Deploy`** installs the dependencies used in your flow, then deploys your flow. `env:` makes
  the `PREFECT_API_KEY` and `PREFECT_API_URL` secrets from your repository available as environment variables during this step's execution.

For reference, the examples below live in their respective branches of
[this repository](https://github.com/prefecthq/cicd-example).

<Tabs>
  <Tab title=".deploy">
    ```
    .
    | -- .github/
    |   |-- workflows/
    |       |-- deploy-prefect-flow.yaml
    |-- flow.py
    |-- requirements.txt
    ```

    `flow.py`

    ```python
    from prefect import flow

    @flow(log_prints=True)
    def hello():
      print("Hello!")

    if __name__ == "__main__":
        hello.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image="my_registry/my_image:my_image_tag",
        )
    ```

    `.github/workflows/deploy-prefect-flow.yaml`

    ```yaml
    name: Deploy Prefect flow

    on:
      push:
        branches:
          - main

    jobs:
      deploy:
        name: Deploy
        runs-on: ubuntu-latest

        steps:
          - name: Checkout
            uses: actions/checkout@v4

          - name: Log in to Docker Hub
            uses: docker/login-action@v3
            with:
              username: ${{ secrets.DOCKER_USERNAME }}
              password: ${{ secrets.DOCKER_PASSWORD }}

          - name: Setup Python
            uses: actions/setup-python@v5
            with:
              python-version: "3.12"

          - name: Prefect Deploy
            env:
              PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}
              PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}
            run: |
              pip install -r requirements.txt
              python flow.py
    ```
  </Tab>

  <Tab title="prefect.yaml">
    ```
    .
    |-- .github/
    |   |-- workflows/
    |       |-- deploy-prefect-flow.yaml
    |-- flow.py
    |-- prefect.yaml
    |-- requirements.txt
    ```

    `flow.py`

    ```python
    from prefect import flow

    @flow(log_prints=True)
    def hello():
      print("Hello!")
    ```

    `prefect.yaml`

    ```yaml
    name: cicd-example
    prefect-version: 3.0.0

    build:
      - prefect_docker.deployments.steps.build_docker_image:
          id: build-image
          requires: prefect-docker>=0.3.1
          image_name: my_registry/my_image
          tag: my_image_tag
          dockerfile: auto

    push:
      - prefect_docker.deployments.steps.push_docker_image:
          requires: prefect-docker>=0.3.1
          image_name: "{{ build-image.image_name }}"
          tag: "{{ build-image.tag }}"

    pull: null

    deployments:
      - name: my-deployment
        entrypoint: flow.py:hello
        work_pool:
          name: my-work-pool
          work_queue_name: default
          job_variables:
            image: "{{ build-image.image }}"
    ```

    `.github/workflows/deploy-prefect-flow.yaml`

    ```yaml
    name: Deploy Prefect flow

    on:
      push:
        branches:
          - main

    jobs:
      deploy:
        name: Deploy
        runs-on: ubuntu-latest

        steps:
          - name: Checkout
            uses: actions/checkout@v4

          - name: Log in to Docker Hub
            uses: docker/login-action@v3
            with:
              username: ${{ secrets.DOCKER_USERNAME }}
              password: ${{ secrets.DOCKER_PASSWORD }}

          - name: Setup Python
            uses: actions/setup-python@v5
            with:
              python-version: "3.12"

          - name: Prefect Deploy
            env:
              PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}
              PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}
            run: |
              pip install -r requirements.txt
              prefect deploy -n my-deployment
    ```
  </Tab>
</Tabs>

### Run a GitHub workflow

After pushing commits to your repository, GitHub automatically triggers a run of your workflow.
Monitor the status of running and completed workflows from the **Actions** tab of your repository.

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-actions-trigger.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=4fd92d92c5163118467f66fd058d6c7e" alt="A GitHub Action triggered via push" data-og-width="1032" width="1032" data-og-height="575" height="575" data-path="v3/img/guides/github-actions-trigger.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-actions-trigger.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=7bd6e6b168958f01d33b1a5148d4f684 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-actions-trigger.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=04e46192e4192e5a3f2668168c51bd80 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-actions-trigger.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=141771bde52862880279aa61ea6674b5 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-actions-trigger.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=3280c601ce39a98d58a735a98cf31258 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-actions-trigger.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=2db36865dd44e09997f96e8f6c2804cc 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/github-actions-trigger.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=9a710f395b98db2a4a52575661a0c556 2500w" data-optimize="true" data-opv="2" />

View the logs from each workflow step as they run. The `Prefect Deploy` step includes output about
your image build and push, and the creation/update of your deployment.

```bash
Successfully built image '***/cicd-example:latest'

Successfully pushed image '***/cicd-example:latest'

Successfully created/updated all deployments!

                Deployments
|-----------------------------------------|
| Name                | Status    Details |
|---------------------|---------|---------|
| hello/my-deployment | applied |         |
|-----------------------------------------|

```

## Advanced example

In more complex scenarios, CI/CD processes often need to accommodate several additional
considerations to enable a smooth development workflow:

* Making code available in different environments as it advances through stages of development
* Handling independent deployment of distinct groupings of work, as in a monorepo
* Efficiently using build time to avoid repeated work

This [example repository](https://github.com/prefecthq/cicd-example-workspaces) addresses each of these
considerations with a combination of Prefect's and GitHub's capabilities.

### Deploy to multiple workspaces

The deployment processes to run are automatically selected when changes are pushed, depending on
two conditions:

```yaml
on:
  push:
    branches:
      - stg
      - main
    paths:
      - "project_1/**"
```

* **`branches:`** - which branch has changed. This ultimately selects which Prefect workspace a
  deployment is created or updated in. In this example, changes on the `stg` branch deploy flows to a
  staging workspace, and changes on the `main` branch deploy flows to a production workspace.
* **`paths:`** - which project folders' files have changed. Since each project folder contains its own flows,
  dependencies, and `prefect.yaml`, it represents a complete set of logic and configuration that can deploy
  independently. Each project in this repository gets its own GitHub Actions workflow YAML file.

The `prefect.yaml` file in each project folder depends on environment variables dictated by the
selected job in each CI/CD workflow; enabling external code storage for Prefect deployments that is clearly
separated across projects and environments.

```
  .
  |--- cicd-example-workspaces-prod  # production bucket
  |   |--- project_1
  |   |---project_2
  |---cicd-example-workspaces-stg  # staging bucket
      |--- project_1
      |---project_2
```

Deployments in this example use S3 for code storage. So it's important that push steps place flow files
in separate locations depending upon their respective environment and project—so no deployment overwrites another
deployment's files.

### Caching build dependencies

Since building Docker images and installing Python dependencies are essential parts of the deployment process,
it's useful to rely on caching to skip repeated build steps.

The `setup-python` action offers [caching options](https://github.com/actions/setup-python#caching-packages-dependencies)
so Python packages do not have to be downloaded on repeat workflow runs.

```yaml
- name: Setup Python
  uses: actions/setup-python@v5
  with:
    python-version: "3.12"
    cache: "pip"
```

The `build-push-action` for building Docker images also offers
[caching options for GitHub Actions](https://docs.docker.com/build/cache/backends/gha/).
If you are not using GitHub, other remote [cache backends](https://docs.docker.com/build/cache/backends/)
are available as well.

```yaml
- name: Build and push
  id: build-docker-image
  env:
      GITHUB_SHA: ${{ steps.get-commit-hash.outputs.COMMIT_HASH }}
  uses: docker/build-push-action@v5
  with:
    context: ${{ env.PROJECT_NAME }}/
    push: true
    tags: ${{ secrets.DOCKER_USERNAME }}/${{ env.PROJECT_NAME }}:${{ env.GITHUB_SHA }}-stg
    cache-from: type=gha
    cache-to: type=gha,mode=max
```

```
importing cache manifest from gha:***
DONE 0.1s

[internal] load build context
transferring context: 70B done
DONE 0.0s

[2/3] COPY requirements.txt requirements.txt
CACHED

[3/3] RUN pip install -r requirements.txt
CACHED
```

## Prefect GitHub Actions

Prefect provides its own GitHub Actions for [authentication](https://github.com/PrefectHQ/actions-prefect-auth)
and [deployment creation](https://github.com/PrefectHQ/actions-prefect-deploy).
These actions simplify deploying with CI/CD when using `prefect.yaml`,
especially in cases where a repository contains flows used in multiple deployments across multiple
Prefect Cloud workspaces.

Here's an example of integrating these actions into the workflow above:

```yaml
name: Deploy Prefect flow

on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Prefect Auth
        uses: PrefectHQ/actions-prefect-auth@v1
        with:
          prefect-api-key: ${{ secrets.PREFECT_API_KEY }}
          prefect-workspace: ${{ secrets.PREFECT_WORKSPACE }}

      - name: Run Prefect Deploy
        uses: PrefectHQ/actions-prefect-deploy@v4
        with:
          deployment-names: my-deployment
          requirements-file-paths: requirements.txt
```

## Authenticate to other Docker image registries

The `docker/login-action` GitHub Action supports pushing images to a wide variety of image registries.

For example, if you are storing Docker images in AWS Elastic Container Registry, you can add your ECR
registry URL to the `registry` key in the `with:` part of the action and use an `AWS_ACCESS_KEY_ID` and
`AWS_SECRET_ACCESS_KEY` as your `username` and `password`.

```yaml
- name: Login to ECR
  uses: docker/login-action@v3
  with:
    registry: <aws-account-number>.dkr.ecr.<region>.amazonaws.com
    username: ${{ secrets.AWS_ACCESS_KEY_ID }}
    password: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
```

## Further reading

<TF name="resources" href={home.tf} />


# How to detect and respond to zombie flows
Source: https://docs-3.prefect.io/v3/advanced/detect-zombie-flows

Learn how to detect and respond to zombie flows.

Sudden infrastructure failures (like machine crashes or container evictions) can cause flow runs to become unresponsive and appear stuck in a `Running` state.

To mitigate this, flow runs triggered by deployments can emit heartbeats to drive Automations that detect and respond to these "zombie" flow runs, ensuring they are marked as `Crashed` if they stop reporting heartbeats.

### Enable flow run heartbeat events

You will need to ensure you're running Prefect version 3.1.8 or greater and set `PREFECT_RUNNER_HEARTBEAT_FREQUENCY`
to an integer greater than 30 to emit flow run heartbeat events.

### Create the automation

To create an automation that marks zombie flow runs as crashed, run this script:

```python
from datetime import timedelta

from prefect.automations import Automation
from prefect.client.schemas.objects import StateType
from prefect.events.actions import ChangeFlowRunState
from prefect.events.schemas.automations import EventTrigger, Posture
from prefect.events.schemas.events import ResourceSpecification


my_automation = Automation(
    name="Crash zombie flows",
    trigger=EventTrigger(
        after={"prefect.flow-run.heartbeat"},
        expect={
            "prefect.flow-run.heartbeat",
            "prefect.flow-run.Completed",
            "prefect.flow-run.Failed",
            "prefect.flow-run.Cancelled",
            "prefect.flow-run.Crashed",
        },
        match=ResourceSpecification({"prefect.resource.id": ["prefect.flow-run.*"]}),
        for_each={"prefect.resource.id"},
        posture=Posture.Proactive,
        threshold=1,
        within=timedelta(seconds=90),
    ),
    actions=[
        ChangeFlowRunState(
            state=StateType.CRASHED,
            message="Flow run marked as crashed due to missing heartbeats.",
        )
    ],
)

if __name__ == "__main__":
    my_automation.create()
```

The trigger definition says that `after` each heartbeat event for a flow run we `expect` to see another heartbeat event or a
terminal state event for that same flow run `within` 90 seconds of a heartbeat event.

### Adjusting behavior with settings

If `PREFECT_RUNNER_HEARTBEAT_FREQUENCY` is set to `30`, the automation will trigger only after 3 heartbeats have been missed.
You can adjust `within` in the trigger definition and `PREFECT_RUNNER_HEARTBEAT_FREQUENCY` to change how quickly the automation
will fire after the server stops receiving flow run heartbeats.

You can also add additional actions to your automation to send a notification when zombie runs are detected.


# How to develop a custom worker
Source: https://docs-3.prefect.io/v3/advanced/developing-a-custom-worker

Learn how to create a Prefect worker to run your flows.

Prefect workers are responsible for setting up execution infrastructure and starting flow runs on that infrastructure.

A list of available workers can be found in the [workers documentation](/v3/concepts/workers#worker-types). What if you want to execute your flow runs on infrastructure that doesn't have an available worker type? This tutorial will walk you through creating a custom worker that can run your flows on your chosen infrastructure.

## Worker Configuration

When setting up an execution environment for a flow run, a worker receives configuration for the infrastructure it is designed to work with. Examples of configuration values include memory allocation, CPU allocation, credentials, image name, etc. The worker then uses this configuration to create the execution environment and start the flow run.

!!! tip "How are the configuration values populated?"
The work pool that a worker polls for flow runs has a [base job template](/v3/how-to-guides/deployment_infra/manage-work-pools#base-job-template) associated with it. The template is the contract for how configuration values populate for each flow run.

The keys in the `job_configuration` section of this base job template match the worker's configuration class attributes. The values in the `job_configuration` section of the base job template are used to populate the attributes of the worker's configuration class.

The work pool creator gets to decide how they want to populate the values in the `job_configuration` section of the base job template. The values can be hard-coded, templated using placeholders, or a mix of these two approaches. Because you, as the worker developer, don't know how the work pool creator will populate the values, you should set sensible defaults for your configuration class attributes as a matter of best practice.

### Implementing a `BaseJobConfiguration` Subclass

A worker developer defines their worker's configuration to function with a class extending [`BaseJobConfiguration`](/v3/api-ref/python/prefect-workers-base#basejobconfiguration).

`BaseJobConfiguration` has attributes that are common to all workers:

| Attribute | Description                                                                     |
| --------- | ------------------------------------------------------------------------------- |
| `name`    | The name to assign to the created execution environment.                        |
| `env`     | Environment variables to set in the created execution environment.              |
| `labels`  | The labels assigned to the created execution environment for metadata purposes. |
| `command` | The command to use when starting a flow run.                                    |

Prefect sets values for each attribute before giving the configuration to the worker. If you want to customize the values of these attributes, use the [`prepare_for_flow_run`](/v3/api-ref/python/prefect-workers-base#prepare-for-flow-run) method.

Here's an example `prepare_for_flow_run` method that adds a label to the execution environment:

```python
def prepare_for_flow_run(
    self, flow_run, deployment = None, flow = None, work_pool = None, worker_name = None
):
    super().prepare_for_flow_run(flow_run, deployment, flow, work_pool, worker_name)
    self.labels.append("my-custom-label")
```

A worker configuration class is a [Pydantic model](https://docs.pydantic.dev/usage/models/), so you can add additional attributes to your configuration class as Pydantic fields. For example, if you want to allow memory and CPU requests for your worker, you can do so like this:

```python
from pydantic import Field
from prefect.workers.base import BaseJobConfiguration

class MyWorkerConfiguration(BaseJobConfiguration):
    memory: int = Field(
        default=1024,
        description="Memory allocation for the execution environment."
    )
    cpu: int = Field(
        default=500,
        description="CPU allocation for the execution environment."
    )
```

This configuration class will populate the `job_configuration` section of the resulting base job template.

For this example, the base job template would look like this:

```yaml
job_configuration:
    name: "{{ name }}"
    env: "{{ env }}"
    labels: "{{ labels }}"
    command: "{{ command }}"
    memory: "{{ memory }}"
    cpu: "{{ cpu }}"
variables:
    type: object
    properties:
        name:
          title: Name
          description: Name given to infrastructure created by a worker.
          type: string
        env:
          title: Environment Variables
          description: Environment variables to set when starting a flow run.
          type: object
          additionalProperties:
            type: string
        labels:
          title: Labels
          description: Labels applied to infrastructure created by a worker.
          type: object
          additionalProperties:
            type: string
        command:
          title: Command
          description: The command to use when starting a flow run. In most cases,
            this should be left blank and the command will be automatically generated
            by the worker.
          type: string
        memory:
            title: Memory
            description: Memory allocation for the execution environment.
            type: integer
            default: 1024
        cpu:
            title: CPU
            description: CPU allocation for the execution environment.
            type: integer
            default: 500
```

This base job template defines what values can be provided by deployment creators on a per-deployment basis and how those provided values will be translated into the configuration values that the worker will use to create the execution environment.

Notice that each attribute for the class was added in the `job_configuration` section with placeholders whose name matches the attribute name. The `variables` section was also populated with the OpenAPI schema for each attribute. If a configuration class is used without explicitly declaring any template variables, the template variables will be inferred from the configuration class attributes.

### Customizing Configuration Attribute Templates

You can customize the template for each attribute for situations where the configuration values should use more sophisticated templating. For example, if you want to add units for the `memory` attribute, you can do so like this:

```python
from pydantic import Field
from prefect.workers.base import BaseJobConfiguration

class MyWorkerConfiguration(BaseJobConfiguration):
    memory: str = Field(
        default="1024Mi",
        description="Memory allocation for the execution environment.",
        json_schema_extra=dict(template="{{ memory_request }}Mi")
    )
    cpu: str = Field(
        default="500m",
        description="CPU allocation for the execution environment.",
        json_schema_extra=dict(template="{{ cpu_request }}m")
    )
```

Notice that we changed the type of each attribute to `str` to accommodate the units, and we added a new `json_schema_extra` attribute to each attribute. The `template` key in `json_schema_extra` is used to populate the `job_configuration` section of the resulting base job template.

For this example, the `job_configuration` section of the resulting base job template would look like this:

```yaml
job_configuration:
    name: "{{ name }}"
    env: "{{ env }}"
    labels: "{{ labels }}"
    command: "{{ command }}"
    memory: "{{ memory_request }}Mi"
    cpu: "{{ cpu_request }}m"
```

Note that to use custom templates, you will need to declare the template variables used in the template because the names of those variables can no longer be inferred from the configuration class attributes. We will cover how to declare the default variable schema in the [Worker Template Variables](#worker-template-variables) section.

### Rules for Template Variable Interpolation

When defining a job configuration model, it's useful to understand how template variables are interpolated into the job configuration. The templating engine follows a few simple rules:

1. If a template variable is the only value for a key in the `job_configuration` section, the key will be replaced with the value template variable.
2. If a template variable is part of a string (i.e., there is text before or after the template variable), the value of the template variable will be interpolated into the string.
3. If a template variable is the only value for a key in the `job_configuration` section and no value is provided for the template variable, the key will be removed from the `job_configuration` section.

These rules allow worker developers and work pool maintainers to define template variables that can be complex types like dictionaries and lists. These rules also mean that worker developers should give reasonable default values to job configuration fields whenever possible because values are not guaranteed to be provided if template variables are unset.

### Template Variable Usage Strategies

Template variables define the interface that deployment creators interact with to configure the execution environments of their deployments. The complexity of this interface can be controlled via the template variables that are defined for a base job template. This control allows work pool maintainers to find a point along the spectrum of flexibility and simplicity appropriate for their organization.

There are two patterns that are represented in current worker implementations:

#### Pass-Through

In the pass-through pattern, template variables are passed through to the job configuration with little change. This pattern exposes complete control to deployment creators but also requires them to understand the details of the execution environment.

This pattern is useful when the execution environment is simple, and the deployment creators are expected to have high technical knowledge.

The [Docker worker](https://prefecthq.github.io/prefect-docker/worker/) is an example of a worker that uses this pattern.

#### Infrastructure as Code Templating

Depending on the infrastructure they interact with, workers can sometimes employ a declarative infrastructure syntax (i.e., infrastructure as code) to create execution environments (e.g., a Kubernetes manifest or an ECS task definition).

In the IaC pattern, it's often useful to use template variables to template portions of the declarative syntax which then can be used to generate the declarative syntax into a final form.

This approach allows work pool creators to provide a simpler interface to deployment creators while also controlling which portions of infrastructure are configurable by deployment creators.

The [Kubernetes worker](https://prefecthq.github.io/prefect-kubernetes/worker/) is an example of a worker that uses this pattern.

### Configuring Credentials

When executing flow runs within cloud services, workers will often need credentials to authenticate with those services. For example, a worker that executes flow runs in AWS Fargate will need AWS credentials. As a worker developer, you can use blocks to accept credentials configuration from the user.

For example, if you want to allow the user to configure AWS credentials, you can do so like this:

```python
from prefect.workers.base import BaseJobConfiguration
from prefect_aws import AwsCredentials
from pydantic import Field

class MyWorkerConfiguration(BaseJobConfiguration):
    aws_credentials: AwsCredentials | None = Field(
        default=None,
        description="AWS credentials to use when creating AWS resources."
    )
```

Users can create and assign a block to the `aws_credentials` attribute in the UI and the worker will use these credentials when interacting with AWS resources.

## Worker Template Variables

Providing template variables for a base job template defines the fields that deployment creators can override per deployment. The work pool creator ultimately defines the template variables for a base job template, but the worker developer is able to define default template variables for the worker to make it easier to use.

Default template variables for a worker are defined by implementing the `BaseVariables` class. Like the `BaseJobConfiguration` class, the `BaseVariables` class has attributes that are common to all workers:

| Attribute | Description                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| `name`    | The name to assign to the created execution environment.                     |
| `env`     | Environment variables to set in the created execution environment.           |
| `labels`  | The labels assigned the created execution environment for metadata purposes. |
| `command` | The command to use when starting a flow run.                                 |

Additional attributes can be added to the `BaseVariables` class to define additional template variables. For example, if you want to allow memory and CPU requests for your worker, you can do so like this:

```python
from pydantic import Field
from prefect.workers.base import BaseVariables

class MyWorkerTemplateVariables(BaseVariables):
    memory_request: int = Field(
        default=1024,
        description="Memory allocation for the execution environment."
    )
    cpu_request: int = Field(
        default=500,
        description="CPU allocation for the execution environment."
    )
```

When `MyWorkerTemplateVariables` is used in conjunction with `MyWorkerConfiguration` from the [Customizing Configuration Attribute Templates](#customizing-configuration-attribute-templates) section, the resulting base job template will look like this:

```yaml
job_configuration:
    name: "{{ name }}"
    env: "{{ env }}"
    labels: "{{ labels }}"
    command: "{{ command }}"
    memory: "{{ memory_request }}Mi"
    cpu: "{{ cpu_request }}m"
variables:
    type: object
    properties:
        name:
          title: Name
          description: Name given to infrastructure created by a worker.
          type: string
        env:
          title: Environment Variables
          description: Environment variables to set when starting a flow run.
          type: object
          additionalProperties:
            type: string
        labels:
          title: Labels
          description: Labels applied to infrastructure created by a worker.
          type: object
          additionalProperties:
            type: string
        command:
          title: Command
          description: The command to use when starting a flow run. In most cases,
            this should be left blank and the command will be automatically generated
            by the worker.
          type: string
        memory_request:
            title: Memory Request
            description: Memory allocation for the execution environment.
            type: integer
            default: 1024
        cpu_request:
            title: CPU Request
            description: CPU allocation for the execution environment.
            type: integer
            default: 500
```

Note that template variable classes are never used directly. Instead, they are used to generate a schema that is used to populate the `variables` section of a base job template and validate the template variables provided by the user.

We don't recommend using template variable classes within your worker implementation for validation purposes because the work pool creator ultimately defines the template variables. The configuration class should handle any necessary run-time validation.

## Worker Implementation

Workers set up execution environments using provided configuration. Workers also observe the execution environment as the flow run executes and report any crashes to the Prefect API.

### Attributes

To implement a worker, you must implement the `BaseWorker` class and provide it with the following attributes:

| Attribute                     | Description                                  | Required |
| ----------------------------- | -------------------------------------------- | -------- |
| `type`                        | The type of the worker.                      | Yes      |
| `job_configuration`           | The configuration class for the worker.      | Yes      |
| `job_configuration_variables` | The template variables class for the worker. | No       |
| `_documentation_url`          | Link to documentation for the worker.        | No       |
| `_logo_url`                   | Link to a logo for the worker.               | No       |
| `_description`                | A description of the worker.                 | No       |

### Methods

#### `run`

In addition to the attributes above, you must also implement a `run` method. The `run` method is called for each flow run the worker receives for execution from the work pool.

The `run` method has the following signature:

```python
import anyio
import anyio.abc
from prefect.client.schemas.objects import FlowRun
from prefect.workers.base import BaseWorkerResult, BaseJobConfiguration


async def run(
    self,
    flow_run: FlowRun,
    configuration: BaseJobConfiguration,
    task_status: anyio.abc.TaskStatus = anyio.TASK_STATUS_IGNORED,
) -> BaseWorkerResult: ...
```

The `run` method is passed: the flow run to execute, the execution environment configuration for the flow run, and a task status object that allows the worker to track whether the flow run was submitted successfully.

The `run` method must also return a `BaseWorkerResult` object. The `BaseWorkerResult` object returned contains information about the flow run execution. For the most part, you can implement the `BaseWorkerResult` with no modifications like so:

```python
from prefect.workers.base import BaseWorkerResult

class MyWorkerResult(BaseWorkerResult):
    """Result returned by the MyWorker."""
```

If you would like to return more information about a flow run, then additional attributes can be added to the `BaseWorkerResult` class.

### Worker Implementation Example

Below is an example of a worker implementation. This example is not intended to be a complete implementation but to illustrate the aforementioned concepts.

```python
import anyio
import anyio.abc
from prefect.client.schemas.objects import FlowRun
from prefect.workers.base import BaseWorker, BaseWorkerResult, BaseJobConfiguration, BaseVariables
from pydantic import Field

class MyWorkerConfiguration(BaseJobConfiguration):
    memory: str = Field(
        default="1024Mi",
        description="Memory allocation for the execution environment.",
        json_schema_extra=dict(template="{{ memory_request }}Mi")
    )
    cpu: str = Field(
        default="500m",
        description="CPU allocation for the execution environment.",
        json_schema_extra=dict(template="{{ cpu_request }}m")
    )

class MyWorkerTemplateVariables(BaseVariables):
    memory_request: int = Field(
        default=1024,
        description="Memory allocation for the execution environment."
    )
    cpu_request: int = Field(
        default=500,
        description="CPU allocation for the execution environment."
    )

class MyWorkerResult(BaseWorkerResult):
    """Result returned by the MyWorker."""

class MyWorker(BaseWorker):
    type = "my-worker"
    job_configuration = MyWorkerConfiguration
    job_configuration_variables = MyWorkerTemplateVariables
    _documentation_url = "https://example.com/docs"
    _logo_url = "https://example.com/logo"
    _description = "My worker description."

    async def run(
        self, flow_run: FlowRun, configuration: BaseJobConfiguration, task_status: anyio.abc.TaskStatus = anyio.TASK_STATUS_IGNORED,
    ) -> BaseWorkerResult:
        # Create the execution environment and start execution
        job = await self._create_and_start_job(configuration)

        # Use a unique ID to mark the run as started. This ID is later used to tear down infrastructure
        # if the flow run is cancelled.
        task_status.started(job.id)

        # Monitor the execution
        job_status = await self._watch_job(job, configuration)

        exit_code = job_status.exit_code if job_status else -1 # Get result of execution for reporting
        return MyWorkerResult(
            status_code=exit_code,
            identifier=job.id,
        )
```

Most of the execution logic is omitted from the example above, but it shows that the typical order of operations in the `run` method is:

1. Create the execution environment and start the flow run execution
2. Mark the flow run as started via the passed `task_status` object
3. Monitor the execution
4. Get the execution's final status from the infrastructure and return a `BaseWorkerResult` object

To see other examples of worker implementations, see the [`ProcessWorker`](/v3/api-ref/python/prefect-workers-process) and [`KubernetesWorker`](https://prefecthq.github.io/prefect-kubernetes/worker/) implementations.

### Integrating with the Prefect CLI

Workers can be started via the Prefect CLI by providing the `--type` option to the `prefect worker start` CLI command. To make your worker type available via the CLI, it must be available at import time.

If your worker is in a package, you can add an entry point to your setup file in the following format:

```python
entry_points={
    "prefect.collections": [
        "my_package_name = my_worker_module",
    ]
},
```

Prefect will discover this entry point and load your work module in the specified module. The entry point will allow the worker to be available via the CLI.


# Configure UI forms for validating workflow inputs
Source: https://docs-3.prefect.io/v3/advanced/form-building

Learn how to craft validated and user-friendly input forms for workflows.

Parameterizing workflows is a critical part of orchestration. It allows you to create contracts between modular workflows in your organization and empower less-technical users to interact with your workflows intuitively.

[Pydantic](https://docs.pydantic.dev/) is a powerful library for data validation using Python type annotations, which is used by Prefect to build a parameter schema for your workflow.

This allows you to:

* check runtime parameter values against the schema (from the UI or the SDK)
* build a user-friendly form in the Prefect UI
* easily reuse parameter types in similar workflows

In this tutorial, we'll craft a workflow signature that the Prefect UI will render as a self-documenting form.

## Motivation

Let's say you have a workflow that triggers a marketing email blast which looks like:

{/* pmd-metadata: notest */}

```python
@flow
def send_marketing_email(
    mailing_lists: list[str],
    subject: str,
    body: str,
    test_mode: bool = False,
    attachments: list[str] | None = None
):
    """
    Send a marketing email blast to the given lists.

    Args:
        mailing_lists: A list of lists to email.
        subject: The subject of the email.
        body: The body of the email.
        test_mode: Whether to send a test email.
        attachments: A list of attachments to include in the email.
    """
    ...
```

When you deploy this flow, Prefect will automatically inspect your function signature and generate a form for you:

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/0.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7c92fd96cd09e30e1b850f6522ef98b6" alt="initial form" data-og-width="686" width="686" data-og-height="862" height="862" data-path="v3/img/tutorials/parameters/0.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/0.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=f66a8062b45f16b3ef0a7ce041031660 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/0.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=181a0878ab32e7d4cb763e43565a2749 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/0.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=a51b4de930926c80d1cbc362f7fa006a 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/0.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=87099b7096fd0406808866cc7e18043a 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/0.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=b73f65eb8fe717846b55bc66fafabeaa 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/0.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=2dce889c924085aa91f0b0ebc1ecf0e0 2500w" data-optimize="true" data-opv="2" />

This is good enough for many cases, but consider these additional constraints that could arise from business needs or tech stack restrictions:

* there are only a few valid values for `mailing_lists`
* the `subject` must not exceed 30 characters
* no more than 5 `attachments` are allowed

You *can* simply check these constraints in the body of your flow function:

{/* pmd-metadata: notest */}

```python
@flow
def send_marketing_email(...):
    if len(subject) > 30:
        raise ValueError("Subject must be less than 30 characters")
    if mailing_lists not in ["newsletter", "customers", "beta-testers"]:
        raise ValueError("Invalid list to email")
    if len(attachments) > 5:
        raise ValueError("Too many attachments")
    
    # etc...
```

but there are several downsides to this:

* you have to spin up the infrastructure associated with your flow in order to check the constraints, which is wasteful if it turns out that bad parameters were provided
* this might get duplicative, especially if you have similarly constrained parameters for different workflows

To improve on this, we will use `pydantic` to build a convenient, self-documenting, and reusable flow signature that the Prefect UI can build a better form from.

## Building a convenient flow signature

Let's address the constraints on `mailing_lists`, `subject`, and `attachments`.

### Using `Literal` to restrict valid values

> there are only a few valid values for `mailing_lists`

Say our valid mailing lists are: `["newsletter", "customers", "beta-testers"]`

We can define a `Literal` to specify the valid values for the `mailing_lists` parameter.

```python
from typing import Literal

MailingList = Literal["newsletter", "customers", "beta-testers"]
```

<Tip>
  You can use an `Enum` to achieve the same effect.

  ```python
  from enum import Enum

  class MailingList(Enum):
      NEWSLETTER = "newsletter"
      CUSTOMERS = "customers"
      BETA_TESTERS = "beta-testers"
  ```
</Tip>

### Using a `BaseModel` subclass to group and constrain parameters

Both the `subject` and `attachments` parameters have constraints that we want to enforce.

> the `subject` must not exceed 30 characters

> the `attachments` must not exceed 5 items

Additionally, the `subject`, `body`, and `attachments` parameters are all related to the same thing: the content of the email.

We can define a `BaseModel` subclass to group these parameters together and apply these constraints.

{/* pmd-metadata: notest */}

```python
from pydantic import BaseModel, Field

class EmailContent(BaseModel):
    subject: str = Field(max_length=30)
    body: str = Field(default=...)
    attachments: list[str] = Field(default_factory=list, max_length=5)
```

<Tip>
  `pydantic.Field` accepts a `description` kwarg that is displayed in the form above the field input.

  {/* pmd-metadata: notest */}

  ```python
  subject: str = Field(description="The subject of the email", max_length=30)
  ```

    <img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/4.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=4f6dd6381c3b6914c345b705f018ccee" alt="field description" data-og-width="744" width="744" data-og-height="508" height="508" data-path="v3/img/tutorials/parameters/4.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/4.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=393616922fdb4aebb093a799372afe77 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/4.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=bf6ed5373ea36473262dcf3e9c2c2684 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/4.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=20af37a0e21acbb60546e1c7d3b06291 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/4.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=d84a0066995d61fb4b95145adc0c009e 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/4.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=bbb632cba04fac9550e4585872819884 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/4.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=aab7efd9db8c8973aeb4b03265463810 2500w" data-optimize="true" data-opv="2" />

  Similarly, you can:

  * pass `title` to `Field` to override the field name in the form
  * define a docstring for `EmailContent` to add a description to this group of parameters in the form
</Tip>

### Rewriting the flow signature

Now that we have defined the `MailingList` and `EmailContent` types, we can use them in our flow signature:

{/* pmd-metadata: notest */}

```python
@flow
def send_marketing_email(
    mailing_lists: list[MailingList],
    content: EmailContent,
    test_mode: bool = False,
):
    ...
```

The resulting form looks like this:

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/1.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7378d09271c35786333c540982e903b5" alt="improved form" data-og-width="722" width="722" data-og-height="822" height="822" data-path="v3/img/tutorials/parameters/1.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/1.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=5c65107ac68ff1ab202c2aa6776399d2 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/1.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=2a197afcd11913e979e6cbf50ea3c719 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/1.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=4f1a69addb8672c14fa7f977694a3daa 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/1.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1f0412200e0700343565b18559ef32ef 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/1.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=558bb80a173d464234e408de15493460 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/1.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=cdf4e81a66ebf6ea1a01600d798a4373 2500w" data-optimize="true" data-opv="2" />

where the `mailing_lists` parameter renders as a multi-select dropdown that only allows the `Literal` values from our `MailingList` type.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/2.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=cf9e0c0a7e4e6818411efaa114da5adb" alt="multi-select" data-og-width="693" width="693" data-og-height="253" height="253" data-path="v3/img/tutorials/parameters/2.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/2.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1a2337550ede880b171ee6c519bb8485 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/2.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=981bd31a831eec31fbb18edaedae9c7a 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/2.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=5c47b06c87dfaf20ea942eae9bfcf24b 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/2.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=0c0a88c1cfcc6a6a6b1ff30c72a966a9 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/2.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=b9cfca6d8bc00b004a5f685f80bd9725 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/2.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=dd100bfa60e163fccedee7af8f32dda7 2500w" data-optimize="true" data-opv="2" />

and any constraints you've defined on the `EmailContent` fields will be enforced before the run is submitted.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/3.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=619992061424d3e38d65d109833228b0" alt="early validation failure toast" data-og-width="802" width="802" data-og-height="723" height="723" data-path="v3/img/tutorials/parameters/3.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/3.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=c57abee81485808772fe109716bac888 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/3.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=c434b7a4b9a3de27845a0d3c97e56f79 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/3.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=235a862eed24addf855bd60a8d6bfa98 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/3.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=40aa62dcf5463963501131c023743c9e 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/3.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=9a7e8c8b3cbd26809cb8ec016fc58f2c 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/3.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=2d7bfe3d6e25cc46c598a2a4c098c071 2500w" data-optimize="true" data-opv="2" />

<Accordion title="Full example code so far">
  {/* pmd-metadata: notest */}

  ```python
  from typing import Literal

  from prefect import flow
  from pydantic import BaseModel, Field

  MailingList = Literal["newsletter", "customers", "beta-testers"]


  class EmailContent(BaseModel):
      subject: str = Field(max_length=30)
      body: str = Field(default=...)
      attachments: list[str] = Field(default_factory=list, max_length=5)


  @flow
  def send_marketing_email(
      mailing_list: list[MailingList],
      content: EmailContent,
      test_mode: bool = False,
  ):
      pass


  if __name__ == "__main__":
      send_marketing_email.serve()
  ```
</Accordion>

### Using `json_schema_extra` to order fields in the form

By default, your flow parameters are rendered in the order defined by your `@flow` function signature.

Within a given `BaseModel` subclass, parameters are rendered in the following order:

* parameters with a `default` value are rendered first, alphabetically
* parameters without a `default` value are rendered next, alphabetically

You can control the order of the parameters within a `BaseModel` subclass by passing `json_schema_extra` to the `Field` constructor with a `position` key.

Taking our `EmailContent` model from the previous example, let's enforce that `subject` should be displayed first, then `body`, then `attachments`.

{/* pmd-metadata: notest */}

```python
class EmailContent(BaseModel):
    subject: str = Field(
        max_length=30,
        description="The subject of the email",
        json_schema_extra=dict(position=0),
    )
    body: str = Field(default=..., json_schema_extra=dict(position=1))
    attachments: list[str] = Field(
        default_factory=list,
        max_length=5,
        json_schema_extra=dict(position=2),
    )
```

The resulting form looks like this:

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/5.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=08276130d5cb26e10a7db49f63585fa3" alt="custom form layout" data-og-width="1179" width="1179" data-og-height="798" height="798" data-path="v3/img/tutorials/parameters/5.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/5.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=12bbe57439e7b0400f5adbd1fef20e01 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/5.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=887f879ef153536b31491736a5001f8b 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/5.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=12418d45fbf6e940c228f636763a7dbd 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/5.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=f1481962f15706a545a18a20228feb5d 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/5.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=b6efba36727a53956136757507cbf219 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/parameters/5.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=edb9490edaf9d072dd8abce587cb7cc5 2500w" data-optimize="true" data-opv="2" />

## Recap

We have now embedded the constraints on our parameters in the types that describe our flow signature, which means:

* the UI can enforce these constraints before the run is submitted - **less wasted infra cycles**
* workflow inputs are **self-documenting**, both in the UI and in the code defining your workflow
* the types used in this signature can be **easily reused** for other similar workflows

## Debugging and related resources

As you craft a schema for your flow signature, you may want to inspect the raw OpenAPI schema that `pydantic` generates, as it is what the Prefect UI uses to build the form.

Call `model_json_schema()` on your `BaseModel` subclass to inspect the raw schema.

{/* pmd-metadata: notest */}

```python
from rich import print as pprint
from pydantic import BaseModel, Field

class EmailContent(BaseModel):
    subject: str = Field(max_length=30)
    body: str = Field(default=...)
    attachments: list[str] = Field(default_factory=list, max_length=5)

pprint(EmailContent.model_json_schema())
```

```
{
    'properties': {
        'subject': {'maxLength': 30, 'title': 'Subject', 'type': 'string'},
        'body': {'title': 'Body', 'type': 'string'},
        'attachments': {'items': {'type': 'string'}, 'maxItems': 5, 'title': 'Attachments', 'type': 'array'}
    },
    'required': ['subject', 'body'],
    'title': 'EmailContent',
    'type': 'object'
}
```

For more on constrained types and validation features available in `pydantic`, see their documentation on [models](https://docs.pydantic.dev/latest/concepts/models/) and [types](https://docs.pydantic.dev/latest/concepts/types/).


# Advanced
Source: https://docs-3.prefect.io/v3/advanced/index



## Sections

<CardGroup cols={3}>
  <Card title="Workflows" icon="play" href="/v3/advanced/caching">
    Learn advanced workflow patterns and optimization techniques.
  </Card>

  <Card title="Automations" icon="robot" href="/v3/advanced/use-custom-event-grammar">
    Learn advanced patterns for working with events, triggers, and automations.
  </Card>

  <Card title="Workflow Infrastructure" icon="city" href="/v3/advanced/daemonize-processes">
    Learn advanced infrastructure management and deployment strategies.
  </Card>

  <Card title="Platform" icon="server" href="/v3/advanced/infrastructure-as-code">
    Learn advanced strategies for managing your data platform.
  </Card>

  <Card title="Scaling" icon="square-caret-up" href="/v3/advanced/self-hosted">
    Learn how to scale self-hosted Prefect deployments for high availability.
  </Card>

  <Card title="Extensibility" icon="code" href="/v3/advanced/api-client">
    Learn how to extend Prefect with custom blocks and API integrations.
  </Card>
</CardGroup>


# How to manage Prefect resources with Terraform and Helm
Source: https://docs-3.prefect.io/v3/advanced/infrastructure-as-code

Declaratively manage Prefect resources with additional tools

export const HELM = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect Helm charts</a>.</p>;

export const home = {
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/guides/getting-started",
  cli: "https://docs.prefect.io/v3/api-ref/cli/index",
  api: "https://app.prefect.cloud/api/docs",
  helm: "https://github.com/PrefectHQ/prefect-helm/tree/main/charts"
};

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

You can manage many Prefect resources with tools like
[Terraform](https://www.terraform.io/) and [Helm](https://helm.sh/).  These
options are a viable alternative to Prefect's CLI and UI.

## Terraform

<TF name="resources" href={home.tf} />

This documentation represents all Prefect resources that are supported by Terraform.
This Terraform provider is maintained by the Prefect team, and is undergoing active development
to reach [parity with the Prefect API](https://github.com/PrefectHQ/terraform-provider-prefect/milestone/1).

The Prefect team welcomes contributions, feature requests, and bug reports
via our [issue tracker](https://github.com/PrefectHQ/terraform-provider-prefect/issues).

## Helm

<HELM name="resources" href={home.helm} />

Each Helm chart subdirectory contains usage documentation. There are two main charts:

* The `prefect-server` chart is used to a deploy a Prefect server. This is an alternative to using
  [Prefect Cloud](https://app.prefect.cloud/).
* The `prefect-worker` chart is used to deploy a [Prefect worker](/v3/deploy/infrastructure-concepts/workers).

Finally, there is a `prefect-prometheus-exporter` chart that is used to deploy a Prometheus exporter,
exposing Prefect metrics for monitoring and alerting.


# How to write interactive workflows
Source: https://docs-3.prefect.io/v3/advanced/interactive



Flows can pause or suspend execution and automatically resume when they receive type-checked input in Prefect's UI.
Flows can also send and receive type-checked input at any time while running—without pausing or suspending.

This guide explains how to use these features to build *interactive workflows*.

## Pause or suspend a flow until it receives input

You can pause or suspend a flow until it receives input from a user in Prefect's UI. This is useful when you need to ask for
additional information or feedback before resuming a flow. These workflows are often called
[human-in-the-loop](https://hai.stanford.edu/news/humans-loop-design-interactive-ai-systems) (HITL) systems.

<Note>
  **Human-in-the-loop interactivity**
  Approval workflows that pause to ask a human to confirm whether a workflow should continue are very common in the business world.
  Certain types of [machine learning training](https://link.springer.com/article/10.1007/s10462-022-10246-w) and artificial intelligence
  workflows benefit from incorporating HITL design.
</Note>

### Wait for input

To receive input while paused or suspended use the `wait_for_input` parameter in the `pause_flow_run` or `suspend_flow_run` functions.
This parameter accepts one of the following:

* A built-in type like `int` or `str`, or a built-in collection like `List[int]`
* A `pydantic.BaseModel` subclass
* A subclass of `prefect.input.RunInput`

<Tip>
  When to use a `RunModel` or `BaseModel` instead of a built-in type"
  There are a few reasons to use a `RunModel` or `BaseModel`. The first is that when you let Prefect automatically create one of these
  classes for your input type, the field that users see in Prefect's UI when they click "Resume" on a flow run is named `value` and
  has no help text to suggest what the field is. If you create a `RunInput` or `BaseModel`, you can change details like the field name,
  help text, and default value, and users see those reflected in the "Resume" form.
</Tip>

The simplest way to pause or suspend and wait for input is to pass a built-in type:

```python
from prefect import flow
from prefect.flow_runs import pause_flow_run
from prefect.logging import get_run_logger

@flow
def greet_user():
    logger = get_run_logger()

    user = pause_flow_run(wait_for_input=str)

    logger.info(f"Hello, {user}!")
```

In this example, the flow run pauses until a user clicks the Resume button in the Prefect UI, enters a name, and submits the form.

<Note>
  **Types can you pass for `wait_for_input`**

  When you pass a built-in type such as `int` as an argument for the `wait_for_input` parameter to `pause_flow_run` or `suspend_flow_run`,
  Prefect automatically creates a Pydantic model containing one field annotated with the type you specified. This means you can use
  [any type annotation that Pydantic accepts for model fields](https://docs.pydantic.dev/1.10/usage/types/) with these functions.
</Note>

Instead of a built-in type, you can pass in a `pydantic.BaseModel` class. This is useful if you already have a `BaseModel` you want to use:

```python
from prefect import flow
from prefect.flow_runs import pause_flow_run
from prefect.logging import get_run_logger
from pydantic import BaseModel


class User(BaseModel):
    name: str
    age: int


@flow
async def greet_user():
    logger = get_run_logger()

    user = await pause_flow_run(wait_for_input=User)

    logger.info(f"Hello, {user.name}!")
```

<Note>
  **`BaseModel` classes are upgraded to `RunInput` classes automatically**

  When you pass a `pydantic.BaseModel` class as the `wait_for_input` argument to `pause_flow_run` or `suspend_flow_run`, Prefect
  automatically creates a `RunInput` class with the same behavior as your `BaseModel` and uses that instead.

  `RunInput` classes contain extra logic that allows flows to send and receive them at runtime. You shouldn't notice any difference.
</Note>

For advanced use cases such as overriding how Prefect stores flow run inputs, create a `RunInput` class:

```python
from prefect import flow
from prefect.logging import get_run_logger
from prefect.input import RunInput

class UserInput(RunInput):
    name: str
    age: int

    # Imagine overridden methods here.
    def override_something(self, *args, **kwargs):
        super().override_something(*args, **kwargs)

@flow
async def greet_user():
    logger = get_run_logger()

    user = await pause_flow_run(wait_for_input=UserInput)

    logger.info(f"Hello, {user.name}!")
```

### Provide initial data

Set default values for fields in your model with the `with_initial_data` method. This is useful for providing default values
for the fields in your own `RunInput` class.

Expanding on the example above, you can make the `name` field default to "anonymous":

```python
from prefect import flow
from prefect.logging import get_run_logger
from prefect.input import RunInput

class UserInput(RunInput):
    name: str
    age: int

@flow
async def greet_user():
    logger = get_run_logger()

    user_input = await pause_flow_run(
        wait_for_input=UserInput.with_initial_data(name="anonymous")
    )

    if user_input.name == "anonymous":
        logger.info("Hello, stranger!")
    else:
        logger.info(f"Hello, {user_input.name}!")
```

When a user sees the form for this input, the name field contains "anonymous" as the default.

### Provide a description with runtime data

You can provide a dynamic, Markdown description that appears in the Prefect UI when the flow run pauses.
This feature enables context-specific prompts, enhancing clarity and user interaction. Building on the example above:

```python
from datetime import datetime
from prefect import flow
from prefect.flow_runs import pause_flow_run
from prefect.logging import get_run_logger
from prefect.input import RunInput


class UserInput(RunInput):
    name: str
    age: int


@flow
async def greet_user():
    logger = get_run_logger()
    current_date = datetime.now().strftime("%B %d, %Y")

    description_md = f"""
**Welcome to the User Greeting Flow!**
Today's Date: {current_date}

Please enter your details below:
- **Name**: What should we call you?
- **Age**: Just a number, nothing more.
"""

    user_input = await pause_flow_run(
        wait_for_input=UserInput.with_initial_data(
            description=description_md, name="anonymous"
        )
    )

    if user_input.name == "anonymous":
        logger.info("Hello, stranger!")
    else:
        logger.info(f"Hello, {user_input.name}!")
```

When a user sees the form for this input, the given Markdown appears above the input fields.

### Handle custom validation

Prefect uses the fields and type hints on your `RunInput` or `BaseModel` class to validate the general structure of input your flow receives.
If you require more complex validation, use Pydantic [model\_validators](https://docs.pydantic.dev/latest/concepts/validators/#model-validators).

<Warning>
  **Calling custom validation runs after the flow resumes**

  Prefect transforms the type annotations in your `RunInput` or `BaseModel` class to a JSON schema and uses that schema in
  the UI for client-side validation. However, custom validation requires running *Python* logic defined in your `RunInput` class.
  Because of this, validation happens *after the flow resumes*, so you should handle it explicitly in your flow.
  Continue reading for an example best practice.
</Warning>

The following is an example `RunInput` class that uses a custom `model_validator`:

```python
from typing import Literal

import pydantic

from prefect.input import RunInput


class ShirtOrder(RunInput):
    size: Literal["small", "medium", "large", "xlarge"]
    color: Literal["red", "green", "black"]

    @pydantic.model_validator(mode="after")
    def validate_age(self):
        if self.color == "green" and self.size == "small":
            raise ValueError(
                "Green is only in-stock for medium, large, and XL sizes."
            )

        return self
```

In the example, we use Pydantic's `model_validator` decorator to define custom validation for our `ShirtOrder` class.
You can use it in a flow like this:

```python
from typing import Literal

import pydantic

from prefect import flow, pause_flow_run
from prefect.input import RunInput


class ShirtOrder(RunInput):
    size: Literal["small", "medium", "large", "xlarge"]
    color: Literal["red", "green", "black"]

    @pydantic.model_validator(mode="after")
    def validate_age(self):
        if self.color == "green" and self.size == "small":
            raise ValueError(
                "Green is only in-stock for medium, large, and XL sizes."
            )

        return self


@flow
def get_shirt_order():
    shirt_order = pause_flow_run(wait_for_input=ShirtOrder)
```

If a user chooses any size and color combination other than `small` and `green`, the flow run resumes successfully.
However, if the user chooses size `small` and color `green`, the flow run will resume, and `pause_flow_run` raises a
`ValidationError` exception. This causes the flow run to fail and log the error.

To avoid a flow run failure, use a `while` loop and pause again if the `ValidationError` exception is raised:

```python
from typing import Literal

import pydantic
from prefect import flow
from prefect.flow_runs import pause_flow_run
from prefect.logging import get_run_logger
from prefect.input import RunInput


class ShirtOrder(RunInput):
    size: Literal["small", "medium", "large", "xlarge"]
    color: Literal["red", "green", "black"]

    @pydantic.model_validator(mode="after")
    def validate_age(self):
        if self.color == "green" and self.size == "small":
            raise ValueError(
                "Green is only in-stock for medium, large, and XL sizes."
            )

        return self


@flow
def get_shirt_order():
    logger = get_run_logger()
    shirt_order = None

    while shirt_order is None:
        try:
            shirt_order = pause_flow_run(wait_for_input=ShirtOrder)
        except pydantic.ValidationError as exc:
            logger.error(f"Invalid size and color combination: {exc}")

    logger.info(
        f"Shirt order: {shirt_order.size}, {shirt_order.color}"
    )
```

This code causes the flow run to continually pause until the user enters a valid age.

As an additional step, you can use an [automation](/v3/automate/events/automations-triggers) to alert the user to the error.

## Send and receive input at runtime

Use the `send_input` and `receive_input` functions to send input to a flow or receive input from a flow at runtime.
You don't need to pause or suspend the flow to send or receive input.

<Note>
  **Reasons to send or receive input without pausing or suspending**

  You might want to send or receive input without pausing or suspending in scenarios where the flow run is designed to handle
  real-time data. For example, in a live monitoring system, you might need to update certain parameters based on the incoming
  data without interrupting the flow. Another example is having a long-running flow that continually responds to runtime input with
  low latency. For example, if you're building a chatbot, you could have a flow that starts a GPT Assistant and manages a conversation thread.
</Note>

The most important parameter to the `send_input` and `receive_input` functions is `run_type`, which should be one of the following:

* A built-in type such as `int` or `str`
* A `pydantic.BaseModel` class
* A `prefect.input.RunInput` class

<Tip>
  **When to use a `BaseModel` or `RunInput` instead of a built-in type**

  Most built-in types and collections of built-in types should work with `send_input` and `receive_input`, but there is a caveat with
  nested collection types, such as lists of tuples. For example, `List[Tuple[str, float]])`. In this case, validation may happen after
  your flow receives the data, so calling `receive_input` may raise a `ValidationError`. You can plan to catch this exception, and
  consider placing the field in an explicit `BaseModel` or `RunInput` so your flow only receives exact type matches.

  See examples below of `receive_input`, `send_input`, and the two functions working together.
</Tip>

### Receiving input

The following flow uses `receive_input` to continually receive names and print a personalized greeting for each name it receives:

```python
from prefect import flow
from prefect.input.run_input import receive_input


@flow
async def greeter_flow():
    async for name_input in receive_input(str, timeout=None):
        # Prints "Hello, andrew!" if another flow sent "andrew"
        print(f"Hello, {name_input}!")
```

When you pass a type such as `str` into `receive_input`, Prefect creates a `RunInput` class to manage your
input automatically. When a flow sends input of this type, Prefect uses the `RunInput` class to validate the input.
If the validation succeeds, your flow receives the input in the type you specified. In this example, if the flow received a
valid string as input, the variable `name_input` contains the string value.

If, instead, you pass a `BaseModel`, Prefect upgrades your `BaseModel` to a `RunInput` class, and the variable your flow sees
(in this case, `name_input`), is a `RunInput` instance that behaves like a `BaseModel`. If you pass in a `RunInput` class,
no upgrade is needed and you'll get a `RunInput` instance.

A simpler approach is to pass types such as `str` into `receive_input` . If you need access to the generated
`RunInput` that contains the received value, pass `with_metadata=True` to `receive_input`:

```python
from prefect import flow
from prefect.input.run_input import receive_input


@flow
async def greeter_flow():
    async for name_input in receive_input(
        str,
        timeout=None,
        with_metadata=True
    ):
        # Input will always be in the field "value" on this object.
        print(f"Hello, {name_input.value}!")

```

<Tip>
  **When to use `with_metadata=True`**

  The primary uses of accessing the `RunInput` object for a receive input are to respond to the sender with the `RunInput.respond()`
  function, or to access the unique key for an input.
</Tip>

Notice that the printing of `name_input.value`. When Prefect generates a `RunInput` for you from a built-in type,
the `RunInput` class has a single field, `value`, that uses a type annotation matching the type you specified.
So if you call `receive_input` like this: `receive_input(str, with_metadata=True)`, it's equivalent to manually
creating the following `RunInput` class and `receive_input` call:

```python
from prefect import flow
from prefect.input.run_input import RunInput

class GreeterInput(RunInput):
    value: str

@flow
async def greeter_flow():
    async for name_input in receive_input(GreeterInput, timeout=None):
        print(f"Hello, {name_input.value}!")
```

<Warning>
  **The type used in `receive_input` and `send_input` must match**

  For a flow to receive input, the sender must use the same type that the receiver is receiving.
  This means that if the receiver is receiving `GreeterInput`, the sender must send `GreeterInput`. If the receiver is
  receiving `GreeterInput` and the sender sends the `str` input that Prefect automatically upgrades to a `RunInput` class,
  the types won't match; which means the receiving flow run won't receive the input. However, the input will wait for if the flow ever
  calls `receive_input(str)`.
</Warning>

### Keep track of inputs you've already seen

By default, each time you call `receive_input`, you get an iterator that iterates over all known inputs to a specific flow run,
starting with the first received. The iterator keeps track of your current position as you iterate over it, or you can call `next()`
to explicitly get the next input. If you're using the iterator in a loop, you should assign it to a variable:

```python
from prefect import flow, get_client
from prefect.deployments import run_deployment
from prefect.input.run_input import receive_input, send_input

EXIT_SIGNAL = "__EXIT__"


@flow
async def sender():
    greeter_flow_run = await run_deployment(
        "greeter/send-receive", timeout=0, as_subflow=False
    )
    client = get_client()

    # Assigning the `receive_input` iterator to a variable
    # outside of the the `while True` loop allows us to continue
    # iterating over inputs in subsequent passes through the
    # while loop without losing our position.
    receiver = receive_input(
        str,
        with_metadata=True,
        timeout=None,
        poll_interval=0.1
    )

    while True:
        name = input("What is your name? ")
        if not name:
            continue

        if name == "q" or name == "quit":
            await send_input(
                EXIT_SIGNAL,
                flow_run_id=greeter_flow_run.id
            )
            print("Goodbye!")
            break

        await send_input(name, flow_run_id=greeter_flow_run.id)

        # Saving the iterator outside of the while loop and
        # calling next() on each iteration of the loop ensures
        # that we're always getting the newest greeting. If we
        # had instead called `receive_input` here, we would
        # always get the _first_ greeting this flow received,
        # print it, and then ask for a new name.
        greeting = await receiver.next()
        print(greeting)
```

An iterator helps keep track of the inputs your flow has already received. If you want your flow to suspend and then resume later,
save the keys of the inputs you've seen so the flow can read them back out when it resumes.
Consider using a [block](/v3/develop/blocks/), such as a `JSONBlock`.

The following flow receives input for 30 seconds then suspends itself, which exits the flow and tears down infrastructure:

```python
from prefect import flow
from prefect.logging import get_run_logger
from prefect.flow_runs import suspend_flow_run
from prefect.blocks.system import JSON
from prefect.context import get_run_context
from prefect.input.run_input import receive_input


EXIT_SIGNAL = "__EXIT__"


@flow
async def greeter():
    logger = get_run_logger()
    run_context = get_run_context()
    assert run_context.flow_run, "Could not see my flow run ID"

    block_name = f"{run_context.flow_run.id}-seen-ids"

    try:
        seen_keys_block = await JSON.load(block_name)
    except ValueError:
        seen_keys_block = JSON(
            value=[],
        )

    try:
        async for name_input in receive_input(
            str,
            with_metadata=True,
            poll_interval=0.1,
            timeout=30,
            exclude_keys=seen_keys_block.value
        ):
            if name_input.value == EXIT_SIGNAL:
                print("Goodbye!")
                return
            await name_input.respond(f"Hello, {name_input.value}!")

            seen_keys_block.value.append(name_input.metadata.key)
            await seen_keys_block.save(
                name=block_name,
                overwrite=True
            )
    except TimeoutError:
        logger.info("Suspending greeter after 30 seconds of idle time")
        await suspend_flow_run(timeout=10000)
```

As this flow processes name input, it adds the *key* of the flow run input to the `seen_keys_block`.
When the flow later suspends and then resumes, it reads the keys it has already seen out of the JSON block and
passes them as the `exlude_keys` parameter to `receive_input`.

### Respond to the input's sender

When your flow receives input from another flow, Prefect knows the sending flow run ID, so the receiving flow can
respond by calling the `respond` method on the `RunInput` instance the flow received. There are a couple of requirements:

* Pass in a `BaseModel` or `RunInput`, or use `with_metadata=True`.
* The flow you are responding to must receive the same type of input you send to see it.

The `respond` method is equivalent to calling `send_input(..., flow_run_id=sending_flow_run.id)`. But with `respond`,
your flow doesn't need to know the sending flow run's ID.

Next, make the `greeter_flow` respond to name inputs instead of printing them:

```python
from prefect import flow
from prefect.input.run_input import receive_input


@flow
async def greeter():
    async for name_input in receive_input(
        str,
        with_metadata=True,
        timeout=None
    ):
        await name_input.respond(f"Hello, {name_input.value}!")
```

However, this flow runs forever unless there's a signal that it should exit.
Here's how to make it to look for a special string:

```python
from prefect import flow
from prefect.input.run_input import receive_input



EXIT_SIGNAL = "__EXIT__"


@flow
async def greeter():
    async for name_input in receive_input(
        str,
        with_metadata=True,
        poll_interval=0.1,
        timeout=None
    ):
        if name_input.value == EXIT_SIGNAL:
            print("Goodbye!")
            return
        await name_input.respond(f"Hello, {name_input.value}!")
```

With a `greeter` flow in place, create the flow that sends `greeter` names.

### Send input

Send input to a flow with the `send_input` function. This works similarly to `receive_input` and, like that function,
accepts the same `run_input` argument. This can be a built-in type such as `str`, or else a `BaseModel` or `RunInput` subclass.

<Note>
  **When to send input to a flow run**

  Send input to a flow run as soon as you have the flow run's ID. The flow does not have to be receiving input for you to send input.
  If you send a flow input before it is receiving, it will see your input when it calls `receive_input`
  (as long as the types in the `send_input` and `receive_input` calls match).
</Note>

Next, create a `sender` flow that starts a `greeter` flow run and then enters a loop—continuously
getting input from the terminal and sending it to the greeter flow:

```python
from prefect import flow
from prefect.deployments import run_deployment

@flow
async def sender():
    greeter_flow_run = await run_deployment(
        "greeter/send-receive", timeout=0, as_subflow=False
    )
    receiver = receive_input(str, timeout=None, poll_interval=0.1)
    client = get_client()

    while True:
        flow_run = await client.read_flow_run(greeter_flow_run.id)

        if not flow_run.state or not flow_run.state.is_running():
            continue

        name = input("What is your name? ")
        if not name:
            continue

        if name == "q" or name == "quit":
            await send_input(
                EXIT_SIGNAL,
                flow_run_id=greeter_flow_run.id
            )
            print("Goodbye!")
            break

        await send_input(name, flow_run_id=greeter_flow_run.id)
        greeting = await receiver.next()
        print(greeting)
```

First, `run_deployment` starts a `greeter` flow run. This requires a deployed flow running in a process.
That process begins running `greeter` while `sender` continues to execute. Calling `run_deployment(..., timeout=0)`
ensures that `sender` won't wait for the `greeter` flow run to complete, because it's running a loop and only exits when sending `EXIT_SIGNAL`.

Next, the iterator returned by `receive_input` as `receiver` is captured. This flow works by entering a loop. On each iteration of the loop,
the flow asks for terminal input, sends that to the `greeter` flow, and then runs `receiver.next()` to wait until it receives the response from `greeter`.

Next, the terminal user who ran this flow is allowed to exit by entering the string `q` or `quit`.
When that happens, the `greeter` flow is sent an exit signal to shut down, too.

Finally, the new name is sent to `greeter`. `greeter` sends back a greeting as a string.
When you receive the greeting, print it and continue the loop that gets terminal input.

### A complete example

For a complete example of using `send_input` and `receive_input`, here is what the `greeter` and `sender` flows look like together:

```python
import asyncio
import sys
from prefect import flow, get_client
from prefect.blocks.system import JSON
from prefect.context import get_run_context
from prefect.deployments import run_deployment
from prefect.input.run_input import receive_input, send_input


EXIT_SIGNAL = "__EXIT__"


@flow
async def greeter():
    run_context = get_run_context()
    assert run_context.flow_run, "Could not see my flow run ID"

    block_name = f"{run_context.flow_run.id}-seen-ids"

    try:
        seen_keys_block = await JSON.load(block_name)
    except ValueError:
        seen_keys_block = JSON(
            value=[],
        )

    async for name_input in receive_input(
        str,
        with_metadata=True,
        poll_interval=0.1,
        timeout=None
    ):
        if name_input.value == EXIT_SIGNAL:
            print("Goodbye!")
            return
        await name_input.respond(f"Hello, {name_input.value}!")

        seen_keys_block.value.append(name_input.metadata.key)
        await seen_keys_block.save(
            name=block_name,
            overwrite=True
        )


@flow
async def sender():
    greeter_flow_run = await run_deployment(
        "greeter/send-receive", timeout=0, as_subflow=False
    )
    receiver = receive_input(str, timeout=None, poll_interval=0.1)
    client = get_client()

    while True:
        flow_run = await client.read_flow_run(greeter_flow_run.id)

        if not flow_run.state or not flow_run.state.is_running():
            continue

        name = input("What is your name? ")
        if not name:
            continue

        if name == "q" or name == "quit":
            await send_input(
                EXIT_SIGNAL,
                flow_run_id=greeter_flow_run.id
            )
            print("Goodbye!")
            break

        await send_input(name, flow_run_id=greeter_flow_run.id)
        greeting = await receiver.next()
        print(greeting)


if __name__ == "__main__":
    if sys.argv[1] == "greeter":
        asyncio.run(greeter.serve(name="send-receive"))
    elif sys.argv[1] == "sender":
        asyncio.run(sender())
```

To run the example, you need a Python environment with Prefect installed, pointed at either a Prefect Cloud account or a self-hosted Prefect server instance.

With your environment set up, start a flow runner in one terminal with the following command:

```bash
python my_file_name greeter
```

For example, with Prefect Cloud, you should see output like this:

```bash
______________________________________________________________________
| Your flow 'greeter' is being served and polling for scheduled runs |
|                                                                    |
| To trigger a run for this flow, use the following command:         |
|                                                                    |
|         $ prefect deployment run 'greeter/send-receive'            |
|                                                                    |
| You can also run your flow via the Prefect UI:                     |
| https://app.prefect.cloud/account/...(a URL for your account)      |
|                                                                    |
______________________________________________________________________
```

Then start the greeter process in another terminal:

```bash
python my_file_name sender
```

You should see output like this:

```bash
11:38:41.800 | INFO    | prefect.engine - Created flow run 'gregarious-owl' for flow 'sender'
11:38:41.802 | INFO    | Flow run 'gregarious-owl' - View at https://app.prefect.cloud/account/...
What is your name?
```

Type a name and press the enter key to see a greeting to see sending and receiving in action:

```bash
What is your name? andrew
Hello, andrew!
```


# How to customize Prefect's logging configuration
Source: https://docs-3.prefect.io/v3/advanced/logging-customization



Prefect relies on [the standard Python implementation of logging configuration](https://docs.python.org/3/library/logging.config.html).
The full specification of the default logging configuration for any version of Prefect can always be inspected [here](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/logging.yml).
The default logging level is `INFO`.

### Customize logging configuration

Prefect provides several settings to configure the logging level and individual loggers.

Any value in [Prefect's logging configuration file](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/logging.yml) can be overridden through
a Prefect setting of the form `PREFECT_LOGGING_[PATH]_[TO]_[KEY]=value` corresponding to the nested address of the field you are configuring.

For example, to change the default logging level for flow runs but not task runs, update your profile with:

```bash
prefect config set PREFECT_LOGGING_LOGGERS_PREFECT_FLOW_RUNS_LEVEL="ERROR"
```

or set the corresponding environment variable:

```bash
export PREFECT_LOGGING_LOGGERS_PREFECT_FLOW_RUNS_LEVEL="ERROR"
```

You can also configure the "root" Python logger. The root logger receives logs from all loggers unless they
explicitly opt out by disabling propagation. By default, the root logger is configured to output `WARNING` level logs
to the console. As with other logging settings, you can override this from the environment or in the logging configuration
file. For example, you can change the level with the `PREFECT_LOGGING_ROOT_LEVEL` environment variable.

In some situations you may want to completely overhaul the Prefect logging configuration by providing your own `logging.yml` file.
You can create your own version of `logging.yml` in one of two ways:

1. Create a `logging.yml` file in your `PREFECT_HOME` directory (default is `~/.prefect`).
2. Specify a custom path to your `logging.yml` file using the `PREFECT_LOGGING_SETTINGS_PATH` setting.

If Prefect cannot find the `logging.yml` file at the specified location, it will fall back to using the default logging configuration.

See the Python [Logging configuration](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig)
documentation for more information about the configuration options and syntax used by `logging.yml`.

<Note>
  As with all Prefect settings, logging settings are loaded at runtime.
  This means that to customize Prefect logging in a remote environment requires setting the appropriate environment variables and/or profile in that environment.
</Note>

### Formatters

Prefect log formatters specify the format of log messages.
The default formatting for task and flow run records is
`"%(asctime)s.%(msecs)03d | %(levelname)-7s | Task run %(task_run_name)r - %(message)s"` for tasks and
similarly `"%(asctime)s.%(msecs)03d | %(levelname)-7s | Flow run %(flow_run_name)r - %(message)s"` for flows.

The variables available to interpolate in log messages vary by logger.
In addition to the run context, message string,
and any keyword arguments, flow and task run loggers have access to additional variables.

The flow run logger has the following variables available for formatting:

* `flow_run_name`
* `flow_run_id`
* `flow_name`

The task run logger has the following variables available for formatting:

* `task_run_id`
* `flow_run_id`
* `task_run_name`
* `task_name`
* `flow_run_name`
* `flow_name`

You can specify custom formatting by setting the relevant environment variable or by modifying the formatter in a custom `logging.yml` file as
described earlier.
For example, the following changes the formatting for the flow runs formatter:

```bash
PREFECT_LOGGING_FORMATTERS_STANDARD_FLOW_RUN_FMT="%(asctime)s.%(msecs)03d | %(levelname)-7s | %(flow_run_id)s - %(message)s"
```

The resulting messages, using the flow run ID instead of name, look like this:

```bash
10:40:01.211 | INFO    | e43a5a80-417a-41c4-a39e-2ef7421ee1fc - Created task run
'othertask-1c085beb-3' for task 'othertask'
```

### Styles

By default, Prefect highlights specific keywords in the console logs with a variety of colors.
You can toggle highlighting on/off with the `PREFECT_LOGGING_COLORS` setting:

```bash
PREFECT_LOGGING_COLORS=False
```

You can also change what gets highlighted and even adjust the colors by updating the styles - see the `styles`
section of [the Prefect logging configuration file](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/logging.yml) for available keys.

<Note>
  Note that these style settings only impact the display within a terminal, not the Prefect UI.
</Note>

You can even build your own handler with a [custom highlighter](https://rich.readthedocs.io/en/stable/highlighting.html#custom-highlighters).
For example, to additionally highlight emails:

1. Copy and paste the following code into  `my_package_or_module.py` (rename as needed) in the same directory as the flow run
   script; or ideally as part of a Python package so it's available in `site-packages` and accessible anywhere within your environment.

```python
import logging
from typing import Dict, Union

from rich.highlighter import Highlighter

from prefect.logging.handlers import PrefectConsoleHandler
from prefect.logging.highlighters import PrefectConsoleHighlighter

class CustomConsoleHighlighter(PrefectConsoleHighlighter):
    base_style = "log."
    highlights = PrefectConsoleHighlighter.highlights + [
        # ?P<email> is naming this expression as `email`
        r"(?P<email>[\w-]+@([\w-]+\.)+[\w-]+)",
    ]

class CustomConsoleHandler(PrefectConsoleHandler):
    def __init__(
        self,
        highlighter: Highlighter = CustomConsoleHighlighter,
        styles: Dict[str, str] = None,
        level: Union[int, str] = logging.NOTSET,
   ):
        super().__init__(highlighter=highlighter, styles=styles, level=level)
```

2. Update `~/.prefect/logging.yml` to use `my_package_or_module.CustomConsoleHandler` and additionally reference the
   base\_style and named expression: `log.email`.

```yaml
    console_flow_runs:
        level: 0
        class: my_package_or_module.CustomConsoleHandler
        formatter: flow_runs
        styles:
            log.email: magenta
            # other styles can be appended here, e.g.
            # log.completed_state: green
```

3. On your next flow run, text that looks like an email is highlighted. For example, `my@email.com` is colored in
   magenta below:

```python
from prefect import flow
from prefect.logging import get_run_logger

@flow
def log_email_flow():
    logger = get_run_logger()
    logger.info("my@email.com")

log_email_flow()
```

### Apply markup in logs

To use [Rich's markup](https://rich.readthedocs.io/en/stable/markup.html#console-markup) in Prefect logs, first
configure `PREFECT_LOGGING_MARKUP`:

```bash
PREFECT_LOGGING_MARKUP=True
```

The following will highlight "fancy" in red:

```python
from prefect import flow
from prefect.logging import get_run_logger

@flow
def my_flow():
    logger = get_run_logger()
    logger.info("This is [bold red]fancy[/]")

my_flow()
```

<Warning>
  **Inaccurate logs could result**

  If enabled, strings that contain square brackets may be
  inaccurately interpreted and lead to incomplete output. For example, `DROP TABLE [dbo].[SomeTable];"` outputs
  `DROP TABLE .[SomeTable];`.
</Warning>

## Include logs from other libraries

By default, Prefect won't capture log statements from libraries that your flows
and tasks use. You can tell Prefect to include logs from these libraries with
the `PREFECT_LOGGING_EXTRA_LOGGERS` setting.

To use this setting, specify one or more Python library names to include,
separated by commas. For example, if you want Prefect to capture Dask
and SciPy logging statements with your flow and task run logs, use:

`PREFECT_LOGGING_EXTRA_LOGGERS=dask,scipy`

Configure this setting as an environment variable or in a profile. See
[Settings](/v3/develop/settings-and-profiles/) for more details about how to use settings.


# How to persist workflow results
Source: https://docs-3.prefect.io/v3/advanced/results

Results represent the data returned by a flow or a task and enable features such as caching.

Results are the bedrock of many Prefect features - most notably [transactions](/v3/develop/transactions)
and [caching](/v3/concepts/caching) - and are foundational to the resilient execution paradigm that Prefect enables.
Any return value from a task or a flow is a result.
By default these results are not persisted and no reference to them is maintained in the API.

Enabling result persistence allows you to fully benefit from Prefect's orchestration features.

<Tip>
  **Turn on persistence globally by default**

  The simplest way to turn on result persistence globally is through the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` setting:

  ```bash
  prefect config set PREFECT_RESULTS_PERSIST_BY_DEFAULT=true
  ```

  See [settings](/v3/develop/settings-and-profiles) for more information on how settings are managed.
</Tip>

## Configuring result persistence

There are four categories of configuration for result persistence:

* [whether to persist results at all](#enabling-result-persistence): this is configured through
  various keyword arguments, the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` setting, and the `PREFECT_TASKS_DEFAULT_PERSIST_RESULT` setting for tasks specifically.
* [what filesystem to persist results to](#result-storage): this is configured through the `result_storage`
  keyword and the `PREFECT_DEFAULT_RESULT_STORAGE_BLOCK` setting.
* [how to serialize and deserialize results](#result-serialization): this is configured through
  the `result_serializer` keyword and the `PREFECT_RESULTS_DEFAULT_SERIALIZER` setting.
* [what filename to use](#result-filenames): this is configured through one of
  `result_storage_key`, `cache_policy`, or `cache_key_fn`.

### Default persistence configuration

Once result persistence is enabled - whether through the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` setting or
through any of the mechanisms [described below](#enabling-result-persistence) - Prefect's default
result storage configuration is activated.

If you enable result persistence and don't specify a filesystem block, your results will be stored locally.
By default, results are persisted to `~/.prefect/storage/`.

You can configure the location of these results through the `PREFECT_LOCAL_STORAGE_PATH` setting.

```bash
prefect config set PREFECT_LOCAL_STORAGE_PATH='~/.my-results/'
```

### Enabling result persistence

In addition to the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` and `PREFECT_TASKS_DEFAULT_PERSIST_RESULT` settings,
result persistence can also be enabled or disabled on both individual flows and individual tasks.
Specifying a non-null value for any of the following keywords on the task decorator will enable result
persistence for that task:

* `persist_result`: a boolean that allows you to explicitly enable or disable result persistence.
* `result_storage`: accepts either a string reference to a storage block or a storage block class that
  specifies where results should be stored.
* `result_storage_key`: a string that specifies the filename of the result within the task's result storage.
* `result_serializer`: a string or serializer that configures how the data should be serialized and deserialized.
* `cache_policy`: a [cache policy](/v3/concepts/caching#cache-policies) specifying the behavior of the task's cache.
* `cache_key_fn`: [a function](/v3/concepts/caching#cache-key-functions) that configures a custom cache policy.

Similarly, setting `persist_result=True`, `result_storage`, or `result_serializer` on a flow will enable
persistence for that flow.

<Note>
  **Enabling persistence on a flow enables persistence by default for its tasks**

  Enabling result persistence on a flow through any of the above keywords will also enable it for all
  tasks called within that flow by default.

  Any settings *explicitly* set on a task take precedence over the flow settings.

  Additionally, the `PREFECT_TASKS_DEFAULT_PERSIST_RESULT` environment variable can be used to globally control the default persistence behavior for tasks, overriding the default behavior set by a parent flow or task.
</Note>

### Result storage

You can configure the system of record for your results through the `result_storage` keyword argument.
This keyword accepts an instantiated [filesystem block](/v3/develop/blocks/), or a block slug. Find your blocks' slugs with `prefect block ls`.
Note that if you want your tasks to share a common cache, your result storage should be accessible by
the infrastructure in which those tasks run. [Integrations](/integrations/integrations) have cloud-specific storage blocks.
For example, a common distributed filesystem for result storage is AWS S3.

Additionally, you can control the default persistence behavior for task results using the `default_persist_result` setting. This setting allows you to specify whether results should be persisted by default for all tasks. You can set this to `True` to enable persistence by default, or `False` to disable it. This setting can be overridden at the individual task or flow level.

```python
from prefect import flow, task
from prefect_aws.s3 import S3Bucket

test_block = S3Bucket(bucket_name='test-bucket')
test_block.save('test-block', overwrite=True)

# define three tasks
# with different result persistence configuration

@task
def my_task():
    return 42

unpersisted_task = my_task.with_options(persist_result=False)
other_storage_task = my_task.with_options(result_storage=test_block)


@flow(result_storage='s3-bucket/my-dev-block')
def my_flow():

    # this task will use the flow's result storage
    my_task()

    # this task will not persist results at all
    unpersisted_task()

    # this task will persist results to its own bucket using a different S3 block
    other_storage_task()
```

#### Specifying a default filesystem

Alternatively, you can specify a different filesystem through the `PREFECT_DEFAULT_RESULT_STORAGE_BLOCK` setting.
Specifying a block document slug here will enable result persistence using that filesystem as the default.

For example:

```bash
prefect config set PREFECT_DEFAULT_RESULT_STORAGE_BLOCK='s3-bucket/my-prod-block'
```

<Info>
  Note that any explicit configuration of `result_storage` on either a flow or task will override this default.
</Info>

#### Result filenames

By default, the filename of a task's result is computed based on the task's cache policy,
which is typically a hash of various pieces of data and metadata.
For flows, the filename is a random UUID.

You can configure the filename of the result file within result storage using either:

* `result_storage_key`: a templated string that can use any of the fields within `prefect.runtime` and
  the task's individual parameter values. These templated values will be populated at runtime.
* `cache_key_fn`: a function that accepts the task run context and its runtime parameters and returns
  a string. See [task caching documentation](/v3/concepts/caching#cache-key-functions) for more information.

<Warning>
  If both `result_storage_key` and `cache_key_fn` are provided, only the `result_storage_key` will be used.
</Warning>

The following example writes three different result files based on the `name` parameter passed to the task:

```python
from prefect import flow, task


@task(result_storage_key="hello-{parameters[name]}.pickle")
def hello_world(name: str = "world"):
    return f"hello {name}"


@flow
def my_flow():
    hello_world()
    hello_world(name="foo")
    hello_world(name="bar")
```

If a result exists at a given storage key in the storage location, the task will load it without running.
To learn more about caching mechanics in Prefect, see the [caching documentation](/v3/concepts/caching).

### Result serialization

You can configure how results are serialized to storage using result serializers.
These can be set using the `result_serializer` keyword on both tasks and flows.
A default value can be set using the `PREFECT_RESULTS_DEFAULT_SERIALIZER` setting, which defaults to `pickle`.
Current built-in options include `"pickle"`, `"json"`, `"compressed/pickle"` and `"compressed/json"`.

The `result_serializer` accepts both a string identifier or an instance of a `ResultSerializer` class, allowing
you to customize serialization behavior.

## Caching results in memory

When running workflows, Prefect keeps the results of all tasks and flows in memory
so they can be passed downstream. In some cases, it is desirable to override this behavior.
For example, if you are returning a large amount of data from a task, it can be costly to
keep it in memory for the entire duration of the flow run.

Flows and tasks both include an option to drop the result from memory once the
result has been committed with `cache_result_in_memory`:

```python
from prefect import flow, task

@flow(cache_result_in_memory=False)
def foo():
    return "pretend this is large data"

@task(cache_result_in_memory=False)
def bar():
    return "pretend this is biiiig data"
```


# How to secure a self-hosted Prefect server
Source: https://docs-3.prefect.io/v3/advanced/security-settings

Learn about the Prefect settings that add security to your self-hosted server.

Prefect provides a number of [settings](/v3/concepts/settings-and-profiles) that help secure a self-hosted Prefect server.

## Basic Authentication

Self-hosted Prefect servers can be equipped with Basic Authentication through two settings:

* **`server.api.auth_string="admin:pass"`**: this setting should be set with an administrator / password combination, separated by a colon, on any process that hosts the Prefect webserver (for example `prefect server start`).
* **`api.auth_string="admin:pass"`**: this setting should be set with the same administrator / password combination as the server on any client process that needs to communicate with the Prefect API (for example, any process that runs a workflow).

With these settings, the UI will prompt for the full authentication string `"admin:pass"` (no quotes) upon first load. It is recommended to store this information in a secure way, such as a Kubernetes Secret or in a private `.env` file.

<Warning>
  **Note on API keys**

  API keys are only used for [authenticating with Prefect Cloud](/v3/how-to-guides/cloud/manage-users/api-keys).

  If both `PREFECT_API_KEY` and `PREFECT_API_AUTH_STRING` are set on the client, `PREFECT_API_KEY` will take precedence. If you plan to use a
  self-hosted Prefect server, make sure `PREFECT_API_KEY` is not set in your active profile or as
  an environment variable, otherwise authentication will fail (`HTTP 401 Unauthorized`).
</Warning>

Example `.env` file:

```bash .env
PREFECT_SERVER_API_AUTH_STRING="admin:pass"
PREFECT_API_AUTH_STRING="admin:pass"
```

## Host the UI behind a reverse proxy

When using a reverse proxy (such as [Nginx](https://nginx.org) or [Traefik](https://traefik.io)) to proxy traffic to a
hosted Prefect UI instance, you must also configure the self-hosted Prefect server instance to connect to the API.
The [`ui.api_url`](/v3/develop/settings-ref/#api_url) setting should be set to the external proxy URL.

For example, if your external URL is `https://prefect-server.example.com` then you can configure a `prefect.toml` file for your server like this:

```toml prefect.toml
[ui]
api_url = "https://prefect-server.example.com/api"
```

If you do not set `ui.api_url`, then `api.url` will be used as a fallback.

## CSRF protection settings

If using self-hosted Prefect server, you can configure CSRF protection settings.

* [`server.api.csrf_protection_enabled`](/v3/develop/settings-ref/#csrf-protection-enabled): activates CSRF protection on the server,
  requiring valid CSRF tokens for applicable requests. Recommended for production to prevent CSRF attacks.
  Defaults to `False`.
* [`server.api.csrf_token_expiration`](/v3/develop/settings-ref/#csrf-token-expiration): sets the expiration duration for server-issued CSRF tokens,
  influencing how often tokens need to be refreshed. The default is 1 hour.
* [`client.csrf_support_enabled`](/v3/develop/settings-ref/#csrf-support-enabled): enables or disables CSRF token handling in the Prefect client.
  When enabled, the client manages CSRF tokens for state-changing API requests. Defaults to `True`.

By default clients expect that CSRF protection is enabled on the server. If you are running a server without CSRF protection,
you can disable CSRF support in the client.

## CORS settings

If using self-hosted Prefect server, you can configure CORS settings to control which origins are allowed to make cross-origin requests to your server.

* [`server.api.cors_allowed_origins`](/v3/develop/settings-ref/#cors-allowed-origins): a list of origins that are allowed to make cross-origin requests.
* [`server.api.cors_allowed_methods`](/v3/develop/settings-ref/#cors-allowed-methods): a list of HTTP methods that are allowed to be used during cross-origin requests.
* [`server.api.cors_allowed_headers`](/v3/develop/settings-ref/#cors-allowed-headers): a list of headers that are allowed to be used during cross-origin requests.

## Custom client headers

The [`client.custom_headers`](/v3/develop/settings-ref/#custom-headers) setting allows you to configure custom HTTP headers that are included with every API request. This is particularly useful for authentication with proxies, CDNs, or security services that protect your Prefect server.

<CodeGroup>
  ```bash Environment variable
  export PREFECT_CLIENT_CUSTOM_HEADERS='{
    "Proxy-Authorization": "Bearer your-proxy-token",
    "X-Corporate-ID": "your-corp-identifier"
  }'
  ```

  ```bash CLI
  prefect config set PREFECT_CLIENT_CUSTOM_HEADERS='{"Proxy-Authorization": "Bearer your-proxy-token", "X-Corporate-ID": "your-corp-ID"}'
  ```

  ```toml prefect.toml
  [client]
  custom_headers = '''{
    "Proxy-Authorization": "Bearer your-proxy-token",
    "X-Corporate-ID": "your-corp-identifier"
  }'''
  ```
</CodeGroup>

Certain headers are protected and cannot be overridden for security reasons:

* **`User-Agent`**: Managed by Prefect to identify client version and capabilities
* **`Prefect-Csrf-Token`**: Used for CSRF protection when enabled
* **`Prefect-Csrf-Client`**: Used for CSRF client identification

If you attempt to override these protected headers, Prefect will log a warning and ignore the custom value to maintain security.

<Warning>
  **Store credentials securely**

  When using custom headers for authentication, ensure that sensitive values like API keys and tokens are stored securely using environment variables, secrets management systems, or encrypted configuration files. Avoid hardcoding credentials in your source code.
</Warning>


# How to scale self-hosted Prefect
Source: https://docs-3.prefect.io/v3/advanced/self-hosted

Learn how to run multiple Prefect server instances for high availability and load distribution

Running multiple Prefect server instances enables high availability and distributes load across your infrastructure. This guide covers configuration and deployment patterns for scaling self-hosted Prefect.

## Requirements

Multi-server deployments require:

* PostgreSQL database version 14.9 or higher (SQLite does not support multi-server synchronization)
* Redis for event messaging
* Load balancer for API traffic distribution

## Architecture

A scaled Prefect deployment typically includes:

* **Multiple API server instances** - Handle UI and API requests
* **Background services** - Runs the scheduler, automation triggers, and other loop services
* **[PostgreSQL](https://www.postgresql.org/) database** - Stores all persistent data and synchronizes state across servers
* **[Redis](https://redis.io/)** - Distributes events between services
* **Load balancer** - Routes traffic to healthy API instances (e.g. [NGINX](https://www.f5.com/go/product/welcome-to-nginx) or [Traefik](https://doc.traefik.io/traefik/))

```mermaid
%%{
  init: {
    'theme': 'neutral',
    'flowchart': {
      'curve' : 'linear',
      'rankSpacing': 120,
      'nodeSpacing': 80
    }
  }
}%%

flowchart TB
    %% Style definitions
    classDef userClass fill:#ede7f6db,stroke:#4527a0db,stroke-width:2px
    classDef lbClass fill:#e3f2fddb,stroke:#1565c0db,stroke-width:2px
    classDef apiClass fill:#1860f2db,stroke:#1860f2db,stroke-width:2px
    classDef bgClass fill:#7c3aeddb,stroke:#7c3aeddb,stroke-width:2px
    classDef dataClass fill:#16a34adb,stroke:#16a34adb,stroke-width:2px
    classDef workerClass fill:#f59e0bdb,stroke:#f59e0bdb,stroke-width:2px

    %% Nodes
    subgraph clients[Client Side]
        direction TB
        Users[Users / UI / API Clients]:::userClass
        Workers[Workers poll any available API server<br/>Process / K8s / Docker / Serverless]:::workerClass
    end

    LB[Load Balancer<br/>NGINX / HAProxy / ALB<br/>Port 4200]:::lbClass

    subgraph servers[Prefect Server Components]
        direction TB
        subgraph api[API Servers - Horizontal Scaling]
            direction LR
            API1[API Server 1<br/>--no-services]:::apiClass
            API2[API Server 2<br/>--no-services]:::apiClass
            API3[API Server N...<br/>--no-services]:::apiClass
        end

        BG[Background Services<br/>prefect server services start<br/><br/>• Event Processing<br/>• Automation Triggers<br/>• Schedule Management]:::bgClass
    end

    subgraph data[Data Layer]
        direction LR
        PG[(PostgreSQL<br/>• Flow/Task State<br/>• Configuration<br/>• History)]:::dataClass
        Redis[(Redis<br/>• Events<br/>• Automations<br/>• Real-time Updates)]:::dataClass
    end

    %% Connections
    Users --> |HTTPS| LB
    LB --> |Round Robin| api

    api --> |Read/Write| PG
    api --> |Publish| Redis

    BG --> |Read/Write| PG
    BG --> |Subscribe| Redis

    Workers -.-> |Poll Work| api
```

## Configuration

### Database setup

Configure PostgreSQL as your database backend:

```bash
export PREFECT_API_DATABASE_CONNECTION_URL="postgresql+asyncpg://user:password@host:5432/prefect"
```

<Warning>
  PostgreSQL version 14.9 or higher is required for multi-server deployments. SQLite does not support the features needed for state synchronization across multiple servers.
</Warning>

### Redis setup

Configure Redis as your server's message broker, cache, and lease storage:

```bash
export PREFECT_MESSAGING_BROKER="prefect_redis.messaging"
export PREFECT_MESSAGING_CACHE="prefect_redis.messaging"
export PREFECT_SERVER_EVENTS_CAUSAL_ORDERING="prefect_redis.ordering"
export PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE="prefect_redis.lease_storage"
export PREFECT_REDIS_MESSAGING_HOST="redis-host"
export PREFECT_REDIS_MESSAGING_PORT="6379"
export PREFECT_REDIS_MESSAGING_DB="0"
```

If your Redis instance requires authentication, you may configure a username and password:

```bash
export PREFECT_REDIS_MESSAGING_USERNAME="marvin"
export PREFECT_REDIS_MESSAGING_PASSWORD="dontpanic!"
```

For Redis instances that require an encrypted connection, you can enable SSL/TLS:

```bash
export PREFECT_REDIS_MESSAGING_SSL="true"
```

### Service separation

For optimal performance, run API servers and background services separately:

**API servers** (multiple instances):

```bash
prefect server start --host 0.0.0.0 --port 4200 --no-services
```

**Background services**:

```bash
prefect server services start
```

### Database migrations

Disable automatic migrations in multi-server deployments:

```bash
export PREFECT_API_DATABASE_MIGRATE_ON_START="false"
```

Run migrations separately before deployment:

```bash
prefect server database upgrade -y
```

### Load balancer configuration

Configure health checks for your load balancer:

* **Health endpoint**: `/api/health`
* **Expected response**: HTTP 200 with JSON `{"status": "healthy"}`
* **Check interval**: 5-10 seconds

Example NGINX configuration:

```nginx
upstream prefect_api {
    least_conn;
    server prefect-api-1:4200 max_fails=3 fail_timeout=30s;
    server prefect-api-2:4200 max_fails=3 fail_timeout=30s;
    server prefect-api-3:4200 max_fails=3 fail_timeout=30s;
}

server {
    listen 4200;

    location /api/health {
        proxy_pass http://prefect_api;
        proxy_connect_timeout 1s;
        proxy_read_timeout 1s;
    }

    location / {
        proxy_pass http://prefect_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Reverse proxy configuration

When hosting Prefect behind a reverse proxy, ensure proper header forwarding:

```nginx
server {
    listen 80;
    server_name prefect.example.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name prefect.example.com;

    ssl_certificate /path/to/ssl/certificate.pem;
    ssl_certificate_key /path/to/ssl/certificate_key.pem;

    location /api {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;

        # WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Authentication headers
        proxy_set_header Authorization $http_authorization;
        proxy_pass_header Authorization;

        proxy_pass http://prefect_api;
    }

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://prefect_api;
    }
}
```

#### UI proxy settings

When self-hosting the UI behind a proxy:

* `PREFECT_UI_API_URL`: Connection URL from UI to API
* `PREFECT_UI_SERVE_BASE`: Base URL path to serve the UI
* `PREFECT_UI_URL`: URL for clients to access the UI

#### SSL certificates

For self-signed certificates:

1. Add certificate to system bundle and set:
   ```bash
   export SSL_CERT_FILE=/path/to/certificate.pem
   ```

2. Or disable verification (testing only):
   ```bash
   export PREFECT_API_TLS_INSECURE_SKIP_VERIFY=True
   ```

#### Environment proxy settings

Prefect respects standard proxy environment variables:

```bash
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal
```

## Deployment examples

### Docker Compose

<Accordion title="3 servers, 1 background service, postgres, redis">
  ```yaml
  services:
    postgres:
      image: postgres:15
      environment:
        POSTGRES_USER: prefect
        POSTGRES_PASSWORD: prefect
        POSTGRES_DB: prefect
      volumes:
        - postgres_data:/var/lib/postgresql/data
      healthcheck:
        test: pg_isready -h localhost -U $$POSTGRES_USER
        interval: 2s
        timeout: 5s
        retries: 15

    redis:
      image: redis:7

    migrate:
      image: prefecthq/prefect:3-latest
      depends_on:
        postgres:
          condition: service_healthy
      command: prefect server database upgrade -y
      environment:
        PREFECT_API_DATABASE_CONNECTION_URL: postgresql+asyncpg://prefect:prefect@postgres:5432/prefect

    prefect-api:
      image: prefecthq/prefect:3-latest
      depends_on:
        migrate:
          condition: service_completed_successfully
        postgres:
          condition: service_healthy
        redis:
          condition: service_started
      deploy:
        replicas: 3
      command: prefect server start --host 0.0.0.0 --no-services
      environment:
        PREFECT_API_DATABASE_CONNECTION_URL: postgresql+asyncpg://prefect:prefect@postgres:5432/prefect
        PREFECT_API_DATABASE_MIGRATE_ON_START: "false"
        PREFECT_MESSAGING_BROKER: prefect_redis.messaging
        PREFECT_MESSAGING_CACHE: prefect_redis.messaging
        PREFECT_SERVER_EVENTS_CAUSAL_ORDERING: prefect_redis.ordering
        PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE: prefect_redis.lease_storage
        PREFECT_REDIS_MESSAGING_HOST: redis
        PREFECT_REDIS_MESSAGING_PORT: "6379"
      ports:
        - "4200-4202:4200"  # Maps to different ports for each replica

    prefect-background:
      image: prefecthq/prefect:3-latest
      depends_on:
        migrate:
          condition: service_completed_successfully
        postgres:
          condition: service_healthy
        redis:
          condition: service_started
      command: prefect server services start
      environment:
        PREFECT_API_DATABASE_CONNECTION_URL: postgresql+asyncpg://prefect:prefect@postgres:5432/prefect
        PREFECT_API_DATABASE_MIGRATE_ON_START: "false"
        PREFECT_MESSAGING_BROKER: prefect_redis.messaging
        PREFECT_MESSAGING_CACHE: prefect_redis.messaging
        PREFECT_SERVER_EVENTS_CAUSAL_ORDERING: prefect_redis.ordering
        PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE: prefect_redis.lease_storage
        PREFECT_REDIS_MESSAGING_HOST: redis
        PREFECT_REDIS_MESSAGING_PORT: "6379"

  volumes:
    postgres_data:
  ```
</Accordion>

<Tip>
  Deploying Prefect self-hosted somehow else? Consider [opening a PR](/contribute/docs-contribute) to add your deployment pattern to this guide.
</Tip>

## Operations

### Migration considerations

#### Handling large databases

When running migrations on large database instances (especially where tables like `events`, `flow_runs`, or `task_runs` can reach millions of rows), the default database timeout of 10 seconds may not be sufficient for creating indexes.

If you encounter a `TimeoutError` during migrations, increase the database timeout:

```bash
# Set timeout to 10 minutes (adjust based on your database size)
export PREFECT_API_DATABASE_TIMEOUT=600

# Then run the migration
prefect server database upgrade -y
```

For Docker deployments:

```bash
docker run -e PREFECT_API_DATABASE_TIMEOUT=600 prefecthq/prefect:latest prefect server database upgrade -y
```

<Note>
  Index creation time scales with table size. A database with millions of events may require 30+ minutes for some migrations. If a migration fails due to timeout, you may need to manually clean up any partially created indexes before retrying.
</Note>

#### Recovering from failed migrations

If a migration times out while creating indexes, you may need to manually complete it. For example, if migration `7a73514ca2d6` fails:

1. First, check which indexes were partially created:
   ```sql
   SELECT indexname FROM pg_indexes WHERE tablename = 'events' AND indexname LIKE 'ix_events%';
   ```

2. Manually create the missing indexes using `CONCURRENTLY` to avoid blocking:
   ```sql
   -- Drop any partial indexes from the failed migration
   DROP INDEX IF EXISTS ix_events__event_related_occurred;
   DROP INDEX IF EXISTS ix_events__related_resource_ids;

   -- Create the new indexes
   CREATE INDEX CONCURRENTLY ix_events__related_gin ON events USING gin(related);
   CREATE INDEX CONCURRENTLY ix_events__event_occurred ON events (event, occurred);
   CREATE INDEX CONCURRENTLY ix_events__related_resource_ids_gin ON events USING gin(related_resource_ids);
   ```

3. Mark the migration as complete:
   ```sql
   UPDATE alembic_version SET version_num = '7a73514ca2d6';
   ```

<Warning>
  Only use manual recovery if increasing the timeout and retrying the migration doesn't work. Always verify the correct migration version and index definitions from the migration files.
</Warning>

### Monitoring

Monitor your multi-server deployment:

* **Database connections**: Watch for connection pool exhaustion
* **Redis memory**: Ensure adequate memory for message queues
* **API response times**: Track latency across different endpoints
* **Background service lag**: Monitor time between event creation and processing

### Best practices

1. **Start with 2-3 API instances** and scale based on load
2. **Use connection pooling** to manage database connections efficiently
3. **Monitor extensively** before scaling further (e.g. [Prometheus](https://prometheus.io/) + [Grafana](https://grafana.com/) or [Logfire](https://logfire.pydantic.dev/docs/why/))
4. **Test failover scenarios** regularly

## Further reading

* [Server concepts](/v3/concepts/server)
* Deploy [Helm charts](/v3/advanced/server-helm) for Kubernetes


# How to self-host the Prefect Server with Helm
Source: https://docs-3.prefect.io/v3/advanced/server-helm

Self-host your own Prefect server and connect a Prefect worker to it with Helm.

You can use Helm to manage a [self-hosted Prefect server](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-server) and a [worker](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker).

## Prerequisites

* A Kubernetes cluster
* Install the [Helm CLI](https://helm.sh/docs/intro/install/)

## Deploy a server with Helm

<Warning>
  Configuring ingress or publicly exposing Prefect from the cluster is business dependent and not covered in this tutorial.
  For details on Ingress configuration, consult the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/).
</Warning>

### Add the Prefect Helm repository:

```bash
helm repo add prefect https://prefecthq.github.io/prefect-helm
helm repo update
```

### Create a namespace

Create a new namespace for this tutorial (all commands will use this namespace):

```bash
kubectl create namespace prefect
kubectl config set-context --current --namespace=prefect
```

### Deploy the server

<Expandable title="Deploy with default values">
  For a simple deployment using only the default values defined in the chart:

  ```bash
  helm install prefect-server prefect/prefect-server --namespace prefect
  ```
</Expandable>

<Expandable title="Deploy with customized values to configure basic authentication">
  For a customized deployment, first create a `server-values.yaml` file for the server (see [values.yaml template](https://github.com/PrefectHQ/prefect-helm/blob/main/charts/prefect-server/values.yaml)):

  ```yaml
  server:
    basicAuth:
      enabled: true
      existingSecret: server-auth-secret
  ```

  #### Create a secret for the API basic authentication username and password:

  ```bash
  kubectl create secret generic server-auth-secret \
    --namespace prefect --from-literal auth-string='admin:password123'
  ```

  #### Install the server:

  ```bash
  helm install prefect-server prefect/prefect-server \
    --namespace prefect \
    -f server-values.yaml
  ```
</Expandable>

Expected output:

```
NAME: prefect-server
LAST DEPLOYED: Tue Mar  4 09:08:07 2025
NAMESPACE: prefect
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Run the following command to port-forward the UI to your localhost:
$ kubectl --namespace prefect port-forward svc/prefect-server 4200:4200

Visit http://localhost:4200 to use Prefect!
```

### Access the Prefect UI:

```bash
kubectl --namespace prefect port-forward svc/prefect-server 4200:4200
```

Open `localhost:4200` in your browser. If using basic authentication, sign in with `admin:password123`.

## Deploy a worker with Helm

To connect a worker to your self-hosted Prefect server in the same cluster:

<Expandable title="Deploy with the minimum required values">
  Create a `worker-values.yaml` file for the worker (see [values.yaml template](https://github.com/PrefectHQ/prefect-helm/blob/main/charts/prefect-worker/values.yaml)):

  ```yaml
  worker:
    apiConfig: selfHostedServer
    config:
      workPool: kube-test
    selfHostedServerApiConfig:
      apiUrl: http://prefect-server.prefect.svc.cluster.local:4200/api
  ```

  #### Install the worker:

  ```bash
  helm install prefect-worker prefect/prefect-worker \
    --namespace prefect \
    -f worker-values.yaml
  ```
</Expandable>

<Expandable title="Deploy with customized values to configure basic authentication">
  Create a `worker-values.yaml` file for the worker (see [values.yaml template](https://github.com/PrefectHQ/prefect-helm/blob/main/charts/prefect-worker/values.yaml)):

  ```yaml
  worker:
    apiConfig: selfHostedServer
    config:
      workPool: kube-test
    selfHostedServerApiConfig:
      apiUrl: http://prefect-server.prefect.svc.cluster.local:4200/api
      basicAuth:
        enabled: true
        existingSecret: worker-auth-secret
  ```

  #### Create a secret for the API basic authentication username and password:

  ```bash
  kubectl create secret generic worker-auth-secret \
    --namespace prefect --from-literal auth-string='admin:password123'
  ```

  #### Install the worker:

  ```bash
  helm install prefect-worker prefect/prefect-worker \
    --namespace prefect \
    -f worker-values.yaml
  ```
</Expandable>

Expected output:

```
Release "prefect-worker" has been installed. Happy Helming!
NAME: prefect-worker
LAST DEPLOYED: Tue Mar  4 11:26:21 2025
NAMESPACE: prefect
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
```

## Cleanup

To uninstall the self-hosted Prefect server and Prefect worker:

```bash
helm uninstall prefect-worker
helm uninstall prefect-server
```

## Troubleshooting

<Expandable title="Container creation error">
  If you see this error:

  ```
  Error from server (BadRequest): container "prefect-server" in pod "prefect-server-7c87b7f7cf-sgqj2" is waiting to start: CreateContainerConfigError
  ```

  Run `kubectl events` and confirm that the `authString` is correct.
</Expandable>

<Expandable title="Authentication error">
  If you see this error:

  ```
  prefect.exceptions.PrefectHTTPStatusError: Client error '401 Unauthorized' for url 'http://prefect-server.prefect.svc.cluster.local:4200/api/work_pools/kube-test'
  Response: {'exception_message': 'Unauthorized'}
  For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
  An exception occurred.
  ```

  Ensure `basicAuth` is configured in the `worker-values.yaml` file.
</Expandable>

<Expandable title="Connection error">
  If you see this error:

  ```
  File "/usr/local/lib/python3.11/site-packages/httpcore/_backends/anyio.py", line 113, in connect_tcp
    with map_exceptions(exc_map):
  File "/usr/local/lib/python3.11/contextlib.py", line 158, in __exit__
    self.gen.throw(typ, value, traceback)
  File "/usr/local/lib/python3.11/site-packages/httpcore/_exceptions.py", line 14, in map_exceptions
    raise to_exc(exc) from exc
  httpcore.ConnectError: [Errno -2] Name or service not known
  ```

  Ensure the `PREFECT_API_URL` environment variable is properly templated by running the following command:

  ```bash
  helm template prefect-worker prefect/prefect-worker -f worker-values.yaml
  ```

  The URL format should look like the following:

  ```
  http://prefect-server.prefect.svc.cluster.local:4200/api
  ```

  <Note>
    If the worker is not in the same cluster and namespace, the precise format will vary.
  </Note>

  For additional troubleshooting and configuration, review the [Prefect Worker Helm Chart](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker).
</Expandable>


# How to submit flows directly to dynamic infrastructure
Source: https://docs-3.prefect.io/v3/advanced/submit-flows-directly-to-dynamic-infrastructure

Submit flows directly to different infrastructure types without a deployment

<Warning>
  **Beta Feature**

  This feature is currently in beta. While we encourage you to try it out and provide feedback, please be aware that the API may change in future releases, potentially including breaking changes.
</Warning>

Prefect allows you to submit workflows directly to different infrastructure types without requiring a deployment. This enables you to dynamically choose where your workflows run based on their requirements, such as:

* Training machine learning models that require GPUs
* Processing large datasets that need significant memory
* Running lightweight tasks that can use minimal resources

## Benefits

Submitting workflows directly to dynamic infrastructure provides several advantages:

* **Dynamic resource allocation**: Choose infrastructure based on workflow requirements at runtime
* **Cost efficiency**: Use expensive infrastructure only when needed
* **Consistency**: Ensure workflows always run on the appropriate infrastructure type
* **Simplified workflow management**: No need to create and maintain deployments for different infrastructure types

## Supported infrastructure

Direct submission of workflows is currently supported for the following infrastructures:

| Infrastructure            | Required Package     | Decorator                   |
| ------------------------- | -------------------- | --------------------------- |
| Docker                    | `prefect-docker`     | `@docker`                   |
| Kubernetes                | `prefect-kubernetes` | `@kubernetes`               |
| AWS ECS                   | `prefect-aws`        | `@ecs`                      |
| Google Cloud Run          | `prefect-gcp`        | `@cloud_run`                |
| Google Vertex AI          | `prefect-gcp`        | `@vertex_ai`                |
| Azure Container Instances | `prefect-azure`      | `@azure_container_instance` |

Each package can be installed using pip, for example:

```bash
pip install prefect-docker
```

## Prerequisites

Before submitting workflows to specific infrastructure, you'll need:

1. A work pool for each infrastructure type you want to use
2. Object storage to associate with your work pool(s)

## Setting up work pools and storage

### Creating a work pool

Create work pools for each infrastructure type using the Prefect CLI:

```bash
prefect work-pool create NAME --type WORK_POOL_TYPE
```

For detailed information on creating and configuring work pools, refer to the [work pools documentation](/v3/deploy/infrastructure-concepts/work-pools).

### Configuring work pool storage

To enable Prefect to run workflows in remote infrastructure, work pools need an associated storage location to store serialized versions of submitted workflows and results from workflow runs.

Configure storage for your work pools using one of the supported storage types:

<CodeGroup>
  ```bash S3
  prefect work-pool storage configure s3 WORK_POOL_NAME \
      --bucket BUCKET_NAME \
      --aws-credentials-block-name BLOCK_NAME
  ```

  ```bash Google Cloud Storage
  prefect work-pool storage configure gcs WORK_POOL_NAME \
      --bucket BUCKET_NAME \
      --gcp-credentials-block-name BLOCK_NAME
  ```

  ```base Azure Blob Storage
  prefect work-pool storage configure azure-blob-storage WORK_POOL_NAME \
      --container CONTAINER_NAME \
      --azure-blob-storage-credentials-block-name BLOCK_NAME
  ```
</CodeGroup>

To allow Prefect to upload and download serialized workflows, you can [create a block](/v3/develop/blocks) containing credentials with permission to access your configured storage location.

If a credentials block is not provided, Prefect will use the default credentials (e.g., a local profile or an IAM role) as determined by the corresponding cloud provider.

You can inspect your storage configuration using:

```bash
prefect work-pool storage inspect WORK_POOL_NAME
```

<Note>
  **Local storage for `@docker`**

  When using the `@docker` decorator with a local Docker engine, you can use volume mounts to share data between your Docker container and host machine.

  Here's an example:

  ```python
  from prefect import flow
  from prefect.filesystems import LocalFileSystem
  from prefect_docker.experimental import docker


  result_storage = LocalFileSystem(basepath="/tmp/results")
  result_storage.save("result-storage", overwrite=True)


  @docker(
      work_pool="above-ground",
      volumes=["/tmp/results:/tmp/results"],
  )
  @flow(result_storage=result_storage)
  def run_in_docker(name: str):
      return(f"Hello, {name}!")


  print(run_in_docker("world")) # prints "Hello, world!"
  ```

  To use local storage, ensure that:

  1. The volume mount path is identical on both the host and container side
  2. The `LocalFileSystem` block's `basepath` matches the path specified in the volume mount
</Note>

## Submitting workflows to specific infrastructure

To submit a flow to specific infrastructure, use the appropriate decorator for that infrastructure type.

Here's an example using `@kubernetes`:

```python
from prefect import flow
from prefect_kubernetes.experimental.decorators import kubernetes


# Submit `my_remote_flow` to run in a Kubernetes job
@kubernetes(work_pool="olympic")
@flow
def my_remote_flow(name: str):
    print(f"Hello {name}!")

@flow
def my_flow():
    my_remote_flow("Marvin")

# Run the flow
my_flow()
```

When you run this code on your machine, `my_flow` will execute locally, while `my_remote_flow` will be submitted to run in a Kubernetes job.

<Note>
  **Parameters must be serializable**

  Parameters passed to infrastructure-bound flows are serialized with `cloudpickle` to allow them to be transported to the destination infrastructure.

  Most Python objects can be serialized with `cloudpickle`, but objects like database connections cannot be serialized. For parameters that cannot be serialized, you'll need to create the object inside your infrastructure-bound workflow.
</Note>

## Customizing infrastructure configuration

You can override the default configuration by providing additional kwargs to the infrastructure decorator:

```python
from prefect import flow
from prefect_kubernetes.experimental.decorators import kubernetes


@kubernetes(
    work_pool="my-kubernetes-pool",
    namespace="custom-namespace"
)
@flow
def custom_namespace_flow():
    pass
```

Any kwargs passed to the infrastructure decorator will override the corresponding default value in the [base job template](/v3/how-to-guides/deployment_infra/manage-work-pools#base-job-template) for the specified work pool.

## Further reading

* [Work pools](/v3/concepts/work-pools) concept page


# How to write transactional workflows
Source: https://docs-3.prefect.io/v3/advanced/transactions



Prefect supports *transactional semantics* in your workflows that allow you to rollback on task failure
and configure groups of tasks that run as an atomic unit.

A *transaction* in Prefect corresponds to a job that needs to be done.
A transaction runs at most one time, and produces a result record upon completion at a unique address
specified by a dynamically computed cache key.
These records can be shared across tasks and flows.

Under the hood, every Prefect task run is governed by a transaction.
In the default mode of task execution, all you need to understand about transactions are [the policies
determining the task's cache key computation](/v3/concepts/caching).

<Tip>
  **Transactions and states**

  Transactions and states are similar but different in important ways.
  Transactions determine whether a task should or should not execute, whereas states enable visibility into
  code execution status.
</Tip>

## Write your first transaction

Tasks can be grouped into a common transaction using the `transaction` context manager:

```python
import os
from time import sleep

from prefect import task, flow
from prefect.transactions import transaction


@task
def write_file(contents: str):
    "Writes to a file."
    with open("side-effect.txt", "w") as f:
        f.write(contents)


@write_file.on_rollback
def del_file(transaction):
    "Deletes file."
    os.unlink("side-effect.txt")


@task
def quality_test():
    "Checks contents of file."
    with open("side-effect.txt", "r") as f:
        data = f.readlines()

    if len(data) < 2:
        raise ValueError("Not enough data!")


@flow
def pipeline(contents: str):
    with transaction():
        write_file(contents)
        sleep(2) # sleeping to give you a chance to see the file
        quality_test()


if __name__ == "__main__":
    pipeline(contents="hello world")
```

If you run this flow `pipeline(contents="hello world!")` it will fail.
Importantly, after the flow has exited, there is no `"side-effect.txt"` file in
your working directory.
This is because the `write_file` task's `on_rollback` hook was executed due to the transaction failing.

<Tip>
  **`on_rollback` hooks are different than `on_failure` hooks**

  Note that the `on_rollback` hook is executed when the `quality_test` task fails, not the `write_file`
  task that it is associated with it, which succeeded.
  This is because rollbacks occur whenever the transaction a task is participating in fails, even if that
  failure is outside the task's local scope.
  This behavior makes transactions a valuable pattern for managing pipeline failure.
</Tip>

## Transaction lifecycle

Every transaction goes through at most four lifecycle stages:

* **BEGIN**: in this phase, the transaction's key is computed and looked up. If a record already exists at
  the key location the transaction considers itself committed.
* **STAGE**: in this phase, the transaction stages a piece of data to be committed to its result location.
  Whether this data is committed or rolled back depends on the commit mode of the transaction.
* **ROLLBACK**: if the transaction encounters *any* error **after** staging, it rolls itself back and does
  not proceed to commit anything.
* **COMMIT**: in this final phase, the transaction writes its record to its configured location. At this point
  the transaction is complete.

It is important to note that rollbacks only occur *after* the transaction has been staged.
Revisiting our example from above, there are actually *three* transactions at play:

* the larger transaction that begins when `with transaction()` is executed; this transaction remains active
  throughout the duration of the subtransactions within it.
* the transaction associated with the `write_file` task. Upon completion of the `write_file` task, this
  transaction is now **STAGED**.
* the transaction associated with the `quality_test` task. This transaction fails before it can be staged,
  causing a rollback in its parent transaction which then rolls back any staged subtransactions. In particular,
  the staged `write_file`'s transaction is rolled back.

<Tip>
  **Tasks also have `on_commit` lifecycle hooks**

  In addition to the `on_rollback` hook, a task can also register `on_commit` hooks that execute whenever
  its transaction is committed.
  A task run persists its result only at transaction commit time, which could be significantly
  after the task's completion time if it is within a long running transaction.

  The signature for an `on_commit` hook is the same as that of an `on_rollback` hook:

  {/* pmd-metadata: continuation */}

  ```python
  @write_file.on_commit
  def confirmation(transaction):
      print("committing a record now using the task's cache key!")
  ```
</Tip>

## Idempotency

You can ensure sections of code are functionally idempotent by wrapping them in a transaction. By specifying a `key` for your transaction, you can ensure that
your code is executed only once.

For example, here's a flow that downloads some data from an API and writes it to a file:

```python
from prefect import task, flow
from prefect.transactions import transaction


@task
def download_data():
    """Imagine this downloads some data from an API"""
    return "some data"


@task
def write_data(data: str):
    """This writes the data to a file"""
    with open("data.txt", "w") as f:
        f.write(data)


@flow(log_prints=True)
def pipeline():
    with transaction(key="download-and-write-data") as txn:
        if txn.is_committed():
            print("Data file has already been written. Exiting early.")
            return
        data = download_data()
        write_data(data)


if __name__ == "__main__":
    pipeline()
```

If you run this flow, it will write data to a file the first time, but it will exit early on subsequent runs because the transaction has already been committed.

Giving the transaction a `key` will cause the transaction to write a record on commit signifying that the transaction has completed.
The call to `txn.is_committed()` will return `True` only if the persisted record exists.

### Handling race conditions

Persisting transaction records works well to ensure sequential executions are idempotent, but what about when about when multiple transactions with the same key run at
the same time?

By default, transactions have an isolation level of `READ_COMMITED` which means that they can see any previously committed records, but they are not prevented from overwriting
a record that was created by another transaction between the time they started and the time they committed.

To see this behavior in action in the following script:

```python
import threading

from prefect import flow, task
from prefect.transactions import transaction


@task
def download_data():
    return f"{threading.current_thread().name} is the winner!"


@task
def write_file(contents: str):
    "Writes to a file."
    with open("race-condition.txt", "w") as f:
        f.write(contents)


@flow
def pipeline(transaction_key: str):
    with transaction(key=transaction_key) as txn:
        if txn.is_committed():
            print("Data file has already been written. Exiting early.")
            return
        data = download_data()
        write_file(data)


if __name__ == "__main__":
    # Run the pipeline twice to see the race condition
    transaction_key = f"race-condition-{uuid.uuid4()}"
    thread_1 = threading.Thread(target=pipeline, name="Thread 1", args=(transaction_key,))
    thread_2 = threading.Thread(target=pipeline, name="Thread 2", args=(transaction_key,))

    thread_1.start()
    thread_2.start()

    thread_1.join()
    thread_2.join()
```

If you run this script, you will see that sometimes "Thread 1 is the winner!" is written to the file and sometimes "Thread 2 is the winner!" is written
**even though the transactions have the same key**. You can ensure subsequent runs don't exit early by changing the `key` argument between runs.

To prevent race conditions, you can set the `isolation_level` of a transaction to `SERIALIZABLE`. This will cause each transaction to take a lock on the
provided key. This will prevent other transactions from starting until the first transaction has completed.

Here's an updated example that uses `SERIALIZABLE` isolation:

```python
import threading
import uuid
from prefect import flow, task
from prefect.locking.filesystem import FileSystemLockManager
from prefect.results import ResultStore
from prefect.settings import PREFECT_HOME
from prefect.transactions import IsolationLevel, transaction


@task
def download_data():
    return f"{threading.current_thread().name} is the winner!"


@task
def write_file(contents: str):
    "Writes to a file."
    with open("race-condition.txt", "w") as f:
        f.write(contents)


@flow
def pipeline(transaction_key: str):
    with transaction(
        key=transaction_key,
        isolation_level=IsolationLevel.SERIALIZABLE,
        store=ResultStore(
            lock_manager=FileSystemLockManager(
                lock_files_directory=PREFECT_HOME.value() / "locks"
            )
        ),
    ) as txn:
        if txn.is_committed():
            print("Data file has already been written. Exiting early.")
            return
        data = download_data()
        write_file(data)


if __name__ == "__main__":
    transaction_key = f"race-condition-{uuid.uuid4()}"
    thread_1 = threading.Thread(target=pipeline, name="Thread 1", args=(transaction_key,))
    thread_2 = threading.Thread(target=pipeline, name="Thread 2", args=(transaction_key,))

    thread_1.start()
    thread_2.start()

    thread_1.join()
    thread_2.join()
```

To use a transaction with the `SERIALIZABLE` isolation level, you must also provide a `lock_manager` to the `transaction` context manager. The
lock manager is responsible for acquiring and releasing locks on the transaction key. In the example above, we use a `FileSystemLockManager` which
will manage locks as files on the current instance's filesystem.

Prefect offers several lock managers for different concurrency use cases:

| Lock Manager        | Storage        | Supports                                    | Module/Package               |
| ------------------- | -------------- | ------------------------------------------- | ---------------------------- |
| `MemoryLockManager` | In-memory      | Single-process workflows using threads      | `prefect.locking.memory`     |
| `FileLockManager`   | Filesystem     | Multi-process workflows on a single machine | `prefect.locking.filesystem` |
| `RedisLockManager`  | Redis database | Distributed workflows                       | `prefect-redis`              |

## Access data within transactions

Key-value pairs can be set within a transaction and accessed elsewhere within the transaction, including within the `on_rollback` hook.

The code below shows how to set a key-value pair within a transaction and access it within the `on_rollback` hook:

```python
import os
from time import sleep

from prefect import task, flow
from prefect.transactions import transaction


@task
def write_file(filename: str, contents: str):
    "Writes to a file."
    with open(filename, "w") as f:
        f.write(contents)


@write_file.on_rollback
def del_file(txn):
    "Deletes file."
    os.unlink(txn.get("filename"))


@task
def quality_test(filename):
    "Checks contents of file."
    with open(filename, "r") as f:
        data = f.readlines()

    if len(data) < 2:
        raise ValueError(f"Not enough data!")


@flow
def pipeline(filename: str, contents: str):
    with transaction() as txn:
        txn.set("filename", filename)
        write_file(filename, contents)
        sleep(2)  # sleeping to give you a chance to see the file
        quality_test(filename)


if __name__ == "__main__":
    pipeline(
        filename="side-effect.txt",
        contents="hello world",
    )
```

The value of `contents` is accessible within the `on_rollback` hook.

Use `get_transaction()` to access the transaction object and `txn.get("key")` to access the value of the key.


# How to emit and use custom events
Source: https://docs-3.prefect.io/v3/advanced/use-custom-event-grammar

Learn how to define specific trigger conditions based on custom event grammar.

## Motivating custom events

Imagine you are running an e-commerce platform and you want to trigger a deployment when a customer completes an order.

There might be a number of events that occur during an order on your platform, for example:

* `order.created`
* `order.item.added`
* `order.payment-method.confirmed`
* `order.shipping-method.added`
* `order.complete`

<Tip>
  **Event grammar**

  The above choices of event names are arbitrary. With Prefect events, you're free to select any event grammar that best
  represents your use case.
</Tip>

In this case, we want to trigger a deployment when a user completes an order, so our trigger should:

* `expect` an `order.complete` event
* `after` an `order.created` event
* evaluate these conditions `for_each` user id

Finally, it should pass the `user_id` as a parameter to the deployment.

### Define the trigger

Here's how this looks in code:

```python post_order_deployment.py
from prefect import flow
from prefect.events.schemas.deployment_triggers import DeploymentEventTrigger

order_complete = DeploymentEventTrigger(
    expect={"order.complete"},
    after={"order.created"},
    for_each={"prefect.resource.id"},
    parameters={"user_id": "{{ event.resource.id }}"},
)


@flow(log_prints=True)
def post_order_complete(user_id: str):
    print(f"User {user_id} has completed an order -- doing stuff now")


if __name__ == "__main__":
    post_order_complete.serve(triggers=[order_complete])
```

<Tip>
  **Specify multiple events or resources**

  The `expect` and `after` fields accept a `set` of event names, so you can specify multiple events for each condition.

  Similarly, the `for_each` field accepts a `set` of resource ids.
</Tip>

### Simulate events

To simulate users causing order status events, run the following in a Python shell or script:

```python simulate_events.py
import time
from prefect.events import emit_event

user_id_1, user_id_2 = "123", "456"
for event_name, user_id in [
    ("order.created", user_id_1),
    ("order.created", user_id_2), # other user
    ("order.complete", user_id_1),
]:
    event = emit_event(
        event=event_name,
        resource={"prefect.resource.id": user_id},
    )
    time.sleep(1)
    print(f"{user_id} emitted {event_name}")
```

In the above example:

* `user_id_1` creates and then completes an order, triggering a run of our deployment.
* `user_id_2` creates an order, but no completed event is emitted so no deployment is triggered.


# How to configure worker healthchecks
Source: https://docs-3.prefect.io/v3/advanced/worker-healthchecks

Learn how to monitor worker health and automatically restart workers when they become unresponsive.

Worker healthchecks provide a way to monitor whether your Prefect workers are functioning properly and polling for work as expected. This is particularly useful in production environments where you need to ensure workers are available to execute scheduled flow runs.

## Overview

Worker healthchecks work by:

1. **Tracking polling activity**: Workers record when they last polled for flow runs from their work pool
2. **Exposing a health endpoint**: When enabled, workers start an HTTP server that provides health status
3. **Detecting unresponsive workers**: The health endpoint returns an error status if the worker hasn't polled recently

This allows external monitoring systems, container orchestrators, or process managers to detect and restart unhealthy workers automatically.

## Enabling Healthchecks

Start a worker with healthchecks enabled using the `--with-healthcheck` flag:

```bash
prefect worker start --pool "my-pool" --with-healthcheck
```

This starts both the worker and a lightweight HTTP health server that exposes a `/health` endpoint.
When enabled, the worker exposes an HTTP endpoint at:

```
http://localhost:8080/health
```

For GET requests the endpoint returns:

* **200 OK** with `{"message": "OK"}` when the worker is healthy
* **503 Service Unavailable** with `{"message": "Worker may be unresponsive at this time"}` when the worker is unhealthy

### Configuring the Health Server

You can customize the health server's host and port using environment variables:

```bash
export PREFECT_WORKER_WEBSERVER_HOST=0.0.0.0
export PREFECT_WORKER_WEBSERVER_PORT=9090
prefect worker start --pool "my-pool" --with-healthcheck
```

## Health Detection Logic

A worker is considered unhealthy if it hasn't polled for flow runs within a specific timeframe defined by its configured polling interval. The health check algorithm works as follows:

If a worker hasn't made a successful poll within the time window of `PREFECT_WORKER_QUERY_SECONDS * 30` seconds, it is considered unhealthy
and its health endpoint will return 503 (Service Unavailable). With default settings, a worker is unhealthy if it hasn't polled in 450 seconds (7.5 minutes).

This generous threshold accounts for temporary network issues, API unavailability, or brief worker pauses without triggering false alarms.

## Production Deployment Patterns

### Docker with Health Checks

Use Docker's built-in health check functionality by including these lines in your Dockerfile:

```dockerfile
# Health check configuration
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD python -c "import urllib.request as u; u.urlopen('http://localhost:8080/health', timeout=1)"

# Start worker with healthcheck
CMD ["prefect", "worker", "start", "--pool", "my-pool", "--with-healthcheck"]
```

For more information see [Docker's reference guide](https://docs.docker.com/reference/dockerfile/#healthcheck).

### Kubernetes with Liveness Probes

Configure Kubernetes to automatically restart unhealthy worker pods by including this configuration in your worker deployment:

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 60
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3
```

This is enabled by default when using [Prefect's Helm Chart](v3/advanced/server-helm).

### Docker Compose with Health Checks

Use Docker Compose's built-in health check functionality by including these lines in your Docker compose file:

```yaml
version: '3.8'
services:
  prefect-worker:
    image: my-prefect-worker:latest
    command: ["prefect", "worker", "start", "--pool", "my-pool", "--with-healthcheck"]
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://localhost:8080/health', timeout=1)"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    restart: unless-stopped
```

For more information see [Docker Compose's reference guide](https://docs.docker.com/reference/compose-file/services/#healthcheck).

## Troubleshooting

### Health endpoint not accessible

* Verify the worker was started with `--with-healthcheck`
* Check that the configured host/port is accessible (default: `http://localhost:8080/health`)
* Ensure no firewall rules are blocking the health port
* Port 8080 may conflict with other services - change with `PREFECT_WORKER_WEBSERVER_PORT`
* Verify configuration: `prefect config view --show-defaults | grep WORKER`

### Worker appears healthy but not picking up flows

* Health checks only verify polling activity, not successful flow execution
* Check work pool and work queue configuration: ensure worker is polling the correct pool/queue
* Verify deployment configuration matches worker capabilities
* Review flow run states - flows may be stuck in PENDING due to concurrency limits
* Enable debug logging: set `PREFECT_LOGGING_LEVEL=DEBUG` on the worker to see detailed polling activity
* Increase polling frequency temporarily: `PREFECT_WORKER_QUERY_SECONDS=5`

### False positive health failures

* Increase `PREFECT_WORKER_QUERY_SECONDS` if your API has high latency
* Check for network connectivity issues between worker and Prefect API
* Review worker logs for authentication or authorization errors (API key issues)
* Verify `PREFECT_API_URL` is correctly configured and accessible
* Check for temporary API outages or [rate limiting](v3/concepts/rate-limits)

## Related Configuration

Relevant settings for worker health and polling behavior:

* `PREFECT_WORKER_HEARTBEAT_SECONDS`: How often workers send heartbeats to the API (default: 30)
* `PREFECT_WORKER_QUERY_SECONDS`: How often workers poll for new flow runs (default: 15)
* `PREFECT_WORKER_PREFETCH_SECONDS`: How far in advance to submit flow runs (default: 10)
* `PREFECT_WORKER_WEBSERVER_HOST`: Health server host (default: 127.0.0.1)
* `PREFECT_WORKER_WEBSERVER_PORT`: Health server port (default: 8080)

## Further Reading

For more information on worker configuration, see the [Workers concept guide](/v3/concepts/workers/).


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/artifact



# `prefect artifact`

```command
prefect artifact [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Inspect and delete artifacts.
</Info>

## `prefect artifact ls`

```command
prefect artifact ls [OPTIONS]
```

<Info>
  List artifacts.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--limit">
      The maximum number of artifacts to return.
    </ResponseField>

    <ResponseField name="--all">
      Whether or not to only return the latest version of each artifact.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect artifact inspect`

```command
prefect artifact inspect [OPTIONS] KEY
```

<Info>
  View details about an artifact.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="KEY" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--limit">
      The maximum number of artifacts to return.
    </ResponseField>

    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  `$ prefect artifact inspect "my-artifact"`

  ```json
  [
    {
      'id': 'ba1d67be-0bd7-452e-8110-247fe5e6d8cc',
      'created': '2023-03-21T21:40:09.895910+00:00',
      'updated': '2023-03-21T21:40:09.895910+00:00',
      'key': 'my-artifact',
      'type': 'markdown',
      'description': None,
      'data': 'my markdown',
      'metadata_': None,
      'flow_run_id': '8dc54b6f-6e24-4586-a05c-e98c6490cb98',
      'task_run_id': None
    },
    {
      'id': '57f235b5-2576-45a5-bd93-c829c2900966',
      'created': '2023-03-27T23:16:15.536434+00:00',
      'updated': '2023-03-27T23:16:15.536434+00:00',
      'key': 'my-artifact',
      'type': 'markdown',
      'description': 'my-artifact-description',
      'data': 'my markdown',
      'metadata_': None,
      'flow_run_id': 'ffa91051-f249-48c1-ae0f-4754fcb7eb29',
      'task_run_id': None
    }
  ]
  ```
</Note>

## `prefect artifact delete`

```command
prefect artifact delete [OPTIONS] [KEY]
```

<Info>
  Delete an artifact.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="KEY" type="string">
      The key of the artifact to delete.
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      The ID of the artifact to delete.
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  `$ prefect artifact delete "my-artifact"`
</Note>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/automation



# `prefect automation`

```command
prefect automation [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage automations.
</Info>

## `prefect automation ls`

```command
prefect automation ls [OPTIONS]
```

<Info>
  List all automations.
</Info>

## `prefect automation inspect`

```command
prefect automation inspect [OPTIONS] [NAME]
```

<Info>
  Inspect an automation.

  Arguments:

  name: the name of the automation to inspect

  id: the id of the automation to inspect

  yaml: output as YAML

  json: output as JSON

  Examples:

  `$ prefect automation inspect "my-automation"`

  `$ prefect automation inspect --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`

  `$ prefect automation inspect "my-automation" --yaml`

  `$ prefect automation inspect "my-automation" --output json`
  `$ prefect automation inspect "my-automation" --output yaml`
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      An automation's name
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      An automation's id
    </ResponseField>

    <ResponseField name="--yaml">
      Output as YAML
    </ResponseField>

    <ResponseField name="--json">
      Output as JSON
    </ResponseField>

    <ResponseField name="--output">
      Specify an output format. Currently supports: json, yaml
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect automation resume`

```command
prefect automation resume [OPTIONS] [NAME]
```

<Info>
  Resume an automation.

  Arguments:

  name: the name of the automation to resume

  id: the id of the automation to resume

  Examples:

  `$ prefect automation resume "my-automation"`

  `$ prefect automation resume --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      An automation's name
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      An automation's id
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect automation enable`

```command
prefect automation enable [OPTIONS] [NAME]
```

<Info>
  Resume an automation.

  Arguments:

  name: the name of the automation to resume

  id: the id of the automation to resume

  Examples:

  `$ prefect automation resume "my-automation"`

  `$ prefect automation resume --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      An automation's name
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      An automation's id
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect automation pause`

```command
prefect automation pause [OPTIONS] [NAME]
```

<Info>
  Pause an automation.

  Arguments:

  name: the name of the automation to pause

  id: the id of the automation to pause

  Examples:

  `$ prefect automation pause "my-automation"`

  `$ prefect automation pause --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      An automation's name
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      An automation's id
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect automation disable`

```command
prefect automation disable [OPTIONS] [NAME]
```

<Info>
  Pause an automation.

  Arguments:

  name: the name of the automation to pause

  id: the id of the automation to pause

  Examples:

  `$ prefect automation pause "my-automation"`

  `$ prefect automation pause --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      An automation's name
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      An automation's id
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect automation delete`

```command
prefect automation delete [OPTIONS] [NAME]
```

<Info>
  Delete an automation.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      An automation's name
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      An automation's id
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  `$ prefect automation delete "my-automation"`
  `$ prefect automation delete --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`
</Note>

## `prefect automation create`

```command
prefect automation create [OPTIONS]
```

<Info>
  Create one or more automations from a file or JSON string.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--from-file">
      Path to YAML or JSON file containing automation(s)
    </ResponseField>

    <ResponseField name="--from-json">
      JSON string containing automation(s)
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  `$ prefect automation create --from-file automation.yaml`
  `$ prefect automation create -f automation.json`
  `$ prefect automation create --from-json '{"name": "my-automation", "trigger": {...}, "actions": [...]}'`
  `$ prefect automation create -j '[{"name": "auto1", ...}, {"name": "auto2", ...}]'`
</Note>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/block



# `prefect block`

```command
prefect block [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage blocks.
</Info>

## `prefect block register`

```command
prefect block register [OPTIONS]
```

<Info>
  Register blocks types within a module or file.

  This makes the blocks available for configuration via the UI.
  If a block type has already been registered, its registration will be updated to
  match the block's current definition.

  
  Examples:
  
  Register block types in a Python module:
  \$ prefect block register -m prefect\_aws.credentials
  
  Register block types in a .py file:
  \$ prefect block register -f my\_blocks.py
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--module">
      Python module containing block types to be registered
    </ResponseField>

    <ResponseField name="--file">
      Path to .py file containing block types to be registered
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect block ls`

```command
prefect block ls [OPTIONS]
```

<Info>
  View all configured blocks.
</Info>

## `prefect block delete`

```command
prefect block delete [OPTIONS] [SLUG]
```

<Info>
  Delete a configured block.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SLUG" type="string">
      A block slug. Formatted as '\<BLOCK\_TYPE\_SLUG>/\<BLOCK\_NAME>'
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      A block id.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect block create`

```command
prefect block create [OPTIONS] BLOCK_TYPE_SLUG
```

<Info>
  Generate a link to the Prefect UI to create a block.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="BLOCK_TYPE_SLUG" type="string" required>
      A block type slug. View available types with: prefect block type ls  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect block inspect`

```command
prefect block inspect [OPTIONS] [SLUG]
```

<Info>
  Displays details about a configured block.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SLUG" type="string">
      A Block slug: \<BLOCK\_TYPE\_SLUG>/\<BLOCK\_NAME>
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      A Block id to search for if no slug is given
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect block types`

```command
prefect block types [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Inspect and delete block types.
</Info>

### `prefect block types ls`

```command
prefect block types ls [OPTIONS]
```

<Info>
  List all block types.
</Info>

### `prefect block types inspect`

```command
prefect block types inspect [OPTIONS] SLUG
```

<Info>
  Display details about a block type.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SLUG" type="string" required>
      A block type slug  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect block types delete`

```command
prefect block types delete [OPTIONS] SLUG
```

<Info>
  Delete an unprotected Block Type.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SLUG" type="string" required>
      A Block type slug  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect block type`

```command
prefect block type [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Inspect and delete block types.
</Info>

### `prefect block type ls`

```command
prefect block type ls [OPTIONS]
```

<Info>
  List all block types.
</Info>

### `prefect block type inspect`

```command
prefect block type inspect [OPTIONS] SLUG
```

<Info>
  Display details about a block type.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SLUG" type="string" required>
      A block type slug  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect block type delete`

```command
prefect block type delete [OPTIONS] SLUG
```

<Info>
  Delete an unprotected Block Type.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SLUG" type="string" required>
      A Block type slug  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/concurrency-limit



# `prefect concurrency-limit`

```command
prefect concurrency-limit [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage task-level concurrency limits.
</Info>

## `prefect concurrency-limit create`

```command
prefect concurrency-limit create [OPTIONS] TAG CONCURRENCY_LIMIT
```

<Info>
  Create a concurrency limit against a tag.

  This limit controls how many task runs with that tag may simultaneously be in a
  Running state.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="TAG" type="string" required>
      \[required]
    </ResponseField>

    <ResponseField name="CONCURRENCY_LIMIT" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect concurrency-limit inspect`

```command
prefect concurrency-limit inspect [OPTIONS] TAG
```

<Info>
  View details about a concurrency limit. `active_slots` shows a list of TaskRun IDs
  which are currently using a concurrency slot.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="TAG" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect concurrency-limit ls`

```command
prefect concurrency-limit ls [OPTIONS]
```

<Info>
  View all concurrency limits.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--limit" />

    <ResponseField name="--offset" />
  </Accordion>
</AccordionGroup>

## `prefect concurrency-limit reset`

```command
prefect concurrency-limit reset [OPTIONS] TAG
```

<Info>
  Resets the concurrency limit slots set on the specified tag.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="TAG" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect concurrency-limit delete`

```command
prefect concurrency-limit delete [OPTIONS] TAG
```

<Info>
  Delete the concurrency limit set on the specified tag.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="TAG" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/config



# `prefect config`

```command
prefect config [OPTIONS] COMMAND [ARGS]...
```

<Info>
  View and set Prefect profiles.
</Info>

## `prefect config set`

```command
prefect config set [OPTIONS] SETTINGS...
```

<Info>
  Change the value for a setting by setting the value in the current profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SETTINGS..." type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect config validate`

```command
prefect config validate [OPTIONS]
```

<Info>
  Read and validate the current profile.

  Deprecated settings will be automatically converted to new names unless both are
  set.
</Info>

## `prefect config unset`

```command
prefect config unset [OPTIONS] SETTING_NAMES...
```

<Info>
  Restore the default value for a setting.

  Removes the setting from the current profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="SETTING_NAMES..." type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--yes" />
  </Accordion>
</AccordionGroup>

## `prefect config view`

```command
prefect config view [OPTIONS]
```

<Info>
  Display the current settings.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--show-defaults">
      Toggle display of default settings.

      \--show-defaults displays all settings,
      even if they are not changed from the
      default values.

      \--hide-defaults displays only settings
      that are changed from default values.
    </ResponseField>

    <ResponseField name="--show-sources">
      Toggle display of the source of a value for
      a setting.

      The value for a setting can come from the
      current profile, environment variables, or
      the defaults.
    </ResponseField>

    <ResponseField name="--show-secrets">
      Toggle display of secrets setting values.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/dashboard



# `prefect dashboard`

```command
prefect dashboard [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Commands for interacting with the Prefect UI.
</Info>

## `prefect dashboard open`

```command
prefect dashboard open [OPTIONS]
```

<Info>
  Open the Prefect UI in the browser.
</Info>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/deployment



# `prefect deployment`

```command
prefect deployment [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage deployments.
</Info>

## `prefect deployment inspect`

```command
prefect deployment inspect [OPTIONS] NAME
```

<Info>
  View details about a deployment.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  `$ prefect deployment inspect "hello-world/my-deployment"`

  ```python
  {
      'id': '610df9c3-0fb4-4856-b330-67f588d20201',
      'created': '2022-08-01T18:36:25.192102+00:00',
      'updated': '2022-08-01T18:36:25.188166+00:00',
      'name': 'my-deployment',
      'description': None,
      'flow_id': 'b57b0aa2-ef3a-479e-be49-381fb0483b4e',
      'schedules': None,
      'parameters': {'name': 'Marvin'},
      'tags': ['test'],
      'parameter_openapi_schema': {
          'title': 'Parameters',
          'type': 'object',
          'properties': {
              'name': {
                  'title': 'name',
                  'type': 'string'
              }
          },
          'required': ['name']
      },
      'storage_document_id': '63ef008f-1e5d-4e07-a0d4-4535731adb32',
      'infrastructure_document_id': '6702c598-7094-42c8-9785-338d2ec3a028',
      'infrastructure': {
          'type': 'process',
          'env': {},
          'labels': {},
          'name': None,
          'command': ['python', '-m', 'prefect.engine'],
          'stream_output': True
      }
  }
  ```
</Note>

## `prefect deployment ls`

```command
prefect deployment ls [OPTIONS]
```

<Info>
  View all deployments or deployments for specific flows.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--flow-name" />

    <ResponseField name="--by-created" />
  </Accordion>
</AccordionGroup>

## `prefect deployment run`

```command
prefect deployment run [OPTIONS] [NAME]
```

<Info>
  Create a flow run for the given flow and deployment.

  The flow run will be scheduled to run immediately unless `--start-in` or `--start-at` is specified.
  The flow run will not execute until a worker starts.
  To watch the flow run until it reaches a terminal state, use the `--watch` flag.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      A deployed flow's name: \<FLOW\_NAME>/\<DEPLOYMENT\_NAME>
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      A deployment id to search for if no name is given
    </ResponseField>

    <ResponseField name="-jv">
      A key, value pair (key=value) specifying a flow run job variable. The value will be interpreted as JSON. May be passed multiple times to specify multiple job variable values.
    </ResponseField>

    <ResponseField name="-p">
      A key, value pair (key=value) specifying a flow parameter. The value will be interpreted as JSON. May be passed multiple times to specify multiple parameter values.
    </ResponseField>

    <ResponseField name="--params">
      A mapping of parameters to values. To use a stdin, pass '-'. Any parameters passed with `--param` will take precedence over these values.
    </ResponseField>

    <ResponseField name="--start-in">
      A human-readable string specifying a time interval to wait before starting the flow run. E.g. 'in 5 minutes', 'in 1 hour', 'in 2 days'.
    </ResponseField>

    <ResponseField name="--start-at">
      A human-readable string specifying a time to start the flow run. E.g. 'at 5:30pm', 'at 2022-08-01 17:30', 'at 2022-08-01 17:30:00'.
    </ResponseField>

    <ResponseField name="--tag">
      Tag(s) to be applied to flow run.
    </ResponseField>

    <ResponseField name="--watch">
      Whether to poll the flow run until a terminal state is reached.
    </ResponseField>

    <ResponseField name="--watch-interval">
      How often to poll the flow run for state changes (in seconds).
    </ResponseField>

    <ResponseField name="--watch-timeout">
      Timeout for --watch.
    </ResponseField>

    <ResponseField name="--flow-run-name">
      Custom name to give the flow run.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect deployment delete`

```command
prefect deployment delete [OPTIONS] [NAME]
```

<Info>
  Delete a deployment.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      A deployed flow's name: \<FLOW\_NAME>/\<DEPLOYMENT\_NAME>
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--id">
      A deployment id to search for if no name is given
    </ResponseField>

    <ResponseField name="--all">
      Delete all deployments
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  ```bash
  $ prefect deployment delete test_flow/test_deployment
  $ prefect deployment delete --id dfd3e220-a130-4149-9af6-8d487e02fea6
  ```
</Note>

## `prefect deployment schedule`

```command
prefect deployment schedule [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage deployment schedules.
</Info>

### `prefect deployment schedule create`

```command
prefect deployment schedule create [OPTIONS] NAME
```

<Info>
  Create a schedule for a given deployment.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--interval">
      An interval to schedule on, specified in seconds
    </ResponseField>

    <ResponseField name="--anchor-date">
      The anchor date for an interval schedule
    </ResponseField>

    <ResponseField name="--rrule">
      Deployment schedule rrule string
    </ResponseField>

    <ResponseField name="--cron">
      Deployment schedule cron string
    </ResponseField>

    <ResponseField name="--day_or">
      Control how croniter handles `day` and `day_of_week` entries
    </ResponseField>

    <ResponseField name="--timezone">
      Deployment schedule timezone string e.g. 'America/New\_York'
    </ResponseField>

    <ResponseField name="--active">
      Whether the schedule is active. Defaults to True.
    </ResponseField>

    <ResponseField name="--replace">
      Replace the deployment's current schedule(s) with this new schedule.
    </ResponseField>

    <ResponseField name="--accept-yes">
      Accept the confirmation prompt without prompting
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect deployment schedule delete`

```command
prefect deployment schedule delete [OPTIONS] DEPLOYMENT_NAME SCHEDULE_ID
```

<Info>
  Delete a deployment schedule.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="DEPLOYMENT_NAME" type="string" required>
      \[required]
    </ResponseField>

    <ResponseField name="SCHEDULE_ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--accept-yes">
      Accept the confirmation prompt without prompting
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect deployment schedule pause`

```command
prefect deployment schedule pause [OPTIONS] DEPLOYMENT_NAME SCHEDULE_ID
```

<Info>
  Pause a deployment schedule.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="DEPLOYMENT_NAME" type="string" required>
      \[required]
    </ResponseField>

    <ResponseField name="SCHEDULE_ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect deployment schedule resume`

```command
prefect deployment schedule resume [OPTIONS] DEPLOYMENT_NAME SCHEDULE_ID
```

<Info>
  Resume a deployment schedule.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="DEPLOYMENT_NAME" type="string" required>
      \[required]
    </ResponseField>

    <ResponseField name="SCHEDULE_ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect deployment schedule ls`

```command
prefect deployment schedule ls [OPTIONS] DEPLOYMENT_NAME
```

<Info>
  View all schedules for a deployment.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="DEPLOYMENT_NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect deployment schedule clear`

```command
prefect deployment schedule clear [OPTIONS] DEPLOYMENT_NAME
```

<Info>
  Clear all schedules for a deployment.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="DEPLOYMENT_NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--accept-yes">
      Accept the confirmation prompt without prompting
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/dev



# `prefect dev`

```command
prefect dev [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Internal Prefect development.

  Note that many of these commands require extra dependencies (such as npm and MkDocs)
  to function properly.
</Info>

## `prefect dev build-docs`

```command
prefect dev build-docs [OPTIONS]
```

<Info>
  Builds REST API reference documentation for static display.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--schema-path" />
  </Accordion>
</AccordionGroup>

## `prefect dev build-ui`

```command
prefect dev build-ui [OPTIONS]
```

<Info>
  Installs dependencies and builds UI locally. Requires npm.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--no-install" />
  </Accordion>
</AccordionGroup>

## `prefect dev ui`

```command
prefect dev ui [OPTIONS]
```

<Info>
  Starts a hot-reloading development UI.
</Info>

## `prefect dev api`

```command
prefect dev api [OPTIONS]
```

<Info>
  Starts a hot-reloading development API.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--host" />

    <ResponseField name="--port" />

    <ResponseField name="--log-level" />

    <ResponseField name="--services" />
  </Accordion>
</AccordionGroup>

## `prefect dev start`

```command
prefect dev start [OPTIONS]
```

<Info>
  Starts a hot-reloading development server with API, UI, and agent processes.

  Each service has an individual command if you wish to start them separately.
  Each service can be excluded here as well.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--no-api" />

    <ResponseField name="--no-ui" />
  </Accordion>
</AccordionGroup>

## `prefect dev build-image`

```command
prefect dev build-image [OPTIONS]
```

<Info>
  Build a docker image for development.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--arch">
      The architecture to build the container for. Defaults to the architecture of the host Python. \[default: arm64]
    </ResponseField>

    <ResponseField name="--python-version">
      The Python version to build the container for. Defaults to the version of the host Python. \[default: 3.10]
    </ResponseField>

    <ResponseField name="--flavor">
      An alternative flavor to build, for example 'conda'. Defaults to the standard Python base image
    </ResponseField>

    <ResponseField name="--dry-run" />
  </Accordion>
</AccordionGroup>

## `prefect dev container`

```command
prefect dev container [OPTIONS]
```

<Info>
  Run a docker container with local code mounted and installed.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--bg" />

    <ResponseField name="--name" />

    <ResponseField name="--api" />

    <ResponseField name="--tag" />
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/event



# `prefect event`

```command
prefect event [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Stream events.
</Info>

## `prefect event stream`

```command
prefect event stream [OPTIONS]
```

<Info>
  Subscribes to the event stream of a workspace, printing each event
  as it is received. By default, events are printed as JSON, but can be
  printed as text by passing `--format text`.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--format">
      Output format (json or text)
    </ResponseField>

    <ResponseField name="--output-file">
      File to write events to
    </ResponseField>

    <ResponseField name="--account">
      Stream events for entire account, including audit logs
    </ResponseField>

    <ResponseField name="--run-once">
      Stream only one event
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/flow



# `prefect flow`

```command
prefect flow [OPTIONS] COMMAND [ARGS]...
```

<Info>
  View and serve flows.
</Info>

## `prefect flow ls`

```command
prefect flow ls [OPTIONS]
```

<Info>
  View flows.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--limit" />
  </Accordion>
</AccordionGroup>

## `prefect flow serve`

```command
prefect flow serve [OPTIONS] ENTRYPOINT
```

<Info>
  Serve a flow via an entrypoint.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ENTRYPOINT" type="string" required>
      The path to a file containing a flow and the name of the flow function in the format `./path/to/file.py:flow_func_name`.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--name">
      The name to give the deployment created for the flow.
    </ResponseField>

    <ResponseField name="--description">
      The description to give the created deployment. If not provided, the description will be populated from the flow's description.
    </ResponseField>

    <ResponseField name="-v">
      A version to give the created deployment.
    </ResponseField>

    <ResponseField name="-t">
      One or more optional tags to apply to the created deployment.
    </ResponseField>

    <ResponseField name="--cron">
      A cron string that will be used to set a schedule for the created deployment.
    </ResponseField>

    <ResponseField name="--interval">
      An integer specifying an interval (in seconds) between scheduled runs of the flow.
    </ResponseField>

    <ResponseField name="--anchor-date">
      The start date for an interval schedule.
    </ResponseField>

    <ResponseField name="--rrule">
      An RRule that will be used to set a schedule for the created deployment.
    </ResponseField>

    <ResponseField name="--timezone">
      Timezone to used scheduling flow runs e.g. 'America/New\_York'
    </ResponseField>

    <ResponseField name="--pause-on-shutdown">
      If set, provided schedule will be paused when the serve command is stopped. If not set, the schedules will continue running.
    </ResponseField>

    <ResponseField name="--limit">
      The maximum number of runs that can be executed concurrently by the created runner; only applies to this served flow. To apply a limit across multiple served flows, use global\_limit.
    </ResponseField>

    <ResponseField name="--global-limit">
      The maximum number of concurrent runs allowed across all served flow instances associated with the same deployment.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/flow-run



# `prefect flow-run`

```command
prefect flow-run [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Interact with flow runs.
</Info>

## `prefect flow-run inspect`

```command
prefect flow-run inspect [OPTIONS] ID
```

<Info>
  View details about a flow run.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--web">
      Open the flow run in a web browser.
    </ResponseField>

    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect flow-run ls`

```command
prefect flow-run ls [OPTIONS]
```

<Info>
  View recent flow runs or flow runs for specific flows.

  Arguments:

  flow\_name: Name of the flow

  limit: Maximum number of flow runs to list. Defaults to 15.

  state: Name of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'PAUSED', 'SUSPENDED', 'AWAITINGRETRY', 'RETRYING', and 'LATE'.

  state\_type: Type of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'CRASHED', and 'PAUSED'.

  Examples:

  \$ prefect flow-runs ls --state Running

  \$ prefect flow-runs ls --state Running --state late

  \$ prefect flow-runs ls --state-type RUNNING

  \$ prefect flow-runs ls --state-type RUNNING --state-type FAILED
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--flow-name">
      Name of the flow
    </ResponseField>

    <ResponseField name="--limit">
      Maximum number of flow runs to list
    </ResponseField>

    <ResponseField name="--state">
      Name of the flow run's state
    </ResponseField>

    <ResponseField name="--state-type">
      Type of the flow run's state
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect flow-run delete`

```command
prefect flow-run delete [OPTIONS] ID
```

<Info>
  Delete a flow run by ID.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect flow-run cancel`

```command
prefect flow-run cancel [OPTIONS] ID
```

<Info>
  Cancel a flow run by ID.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect flow-run logs`

```command
prefect flow-run logs [OPTIONS] ID
```

<Info>
  View logs for a flow run.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--head">
      Show the first 20 logs instead of all logs.
    </ResponseField>

    <ResponseField name="--num-logs">
      Number of logs to show when using the --head or --tail flag. If None, defaults to 20.
    </ResponseField>

    <ResponseField name="--reverse">
      Reverse the logs order to print the most recent logs first
    </ResponseField>

    <ResponseField name="--tail">
      Show the last 20 logs instead of all logs.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect flow-run execute`

```command
prefect flow-run execute [OPTIONS] [ID]
```

<Info />

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ID" type="string">
      ID of the flow run to execute
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/global-concurrency-limit



# `prefect global-concurrency-limit`

```command
prefect global-concurrency-limit [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage global concurrency limits.
</Info>

## `prefect global-concurrency-limit ls`

```command
prefect global-concurrency-limit ls [OPTIONS]
```

<Info>
  List all global concurrency limits.
</Info>

## `prefect global-concurrency-limit inspect`

```command
prefect global-concurrency-limit inspect [OPTIONS] NAME
```

<Info>
  Inspect a global concurrency limit.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the global concurrency limit to inspect.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>

    <ResponseField name="--file">
      Path to .json file to write the global concurrency limit output to.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect global-concurrency-limit delete`

```command
prefect global-concurrency-limit delete [OPTIONS] NAME
```

<Info>
  Delete a global concurrency limit.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the global concurrency limit to delete.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect global-concurrency-limit enable`

```command
prefect global-concurrency-limit enable [OPTIONS] NAME
```

<Info>
  Enable a global concurrency limit.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the global concurrency limit to enable.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect global-concurrency-limit disable`

```command
prefect global-concurrency-limit disable [OPTIONS] NAME
```

<Info>
  Disable a global concurrency limit.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the global concurrency limit to disable.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect global-concurrency-limit update`

```command
prefect global-concurrency-limit update [OPTIONS] NAME
```

<Info>
  Update a global concurrency limit.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the global concurrency limit to update.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--enable">
      Enable the global concurrency limit.
    </ResponseField>

    <ResponseField name="--disable">
      Disable the global concurrency limit.
    </ResponseField>

    <ResponseField name="--limit">
      The limit of the global concurrency limit.
    </ResponseField>

    <ResponseField name="--active-slots">
      The number of active slots.
    </ResponseField>

    <ResponseField name="--slot-decay-per-second">
      The slot decay per second.
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  $prefect global-concurrency-limit update my-gcl --limit 10$ prefect gcl update my-gcl --active-slots 5
  $prefect gcl update my-gcl --slot-decay-per-second 0.5$ prefect gcl update my-gcl --enable
  \$ prefect gcl update my-gcl --disable --limit 5
</Note>

## `prefect global-concurrency-limit create`

```command
prefect global-concurrency-limit create [OPTIONS] NAME
```

<Info>
  Create a global concurrency limit.

  Arguments:

  name (str): The name of the global concurrency limit to create.

  limit (int): The limit of the global concurrency limit.

  disable (Optional\[bool]): Create an inactive global concurrency limit.

  active\_slots (Optional\[int]): The number of active slots.

  slot\_decay\_per\_second (Optional\[float]): The slot decay per second.

  Examples:

  \$ prefect global-concurrency-limit create my-gcl --limit 10

  \$ prefect gcl create my-gcl --limit 5 --active-slots 3

  \$ prefect gcl create my-gcl --limit 5 --active-slots 3 --slot-decay-per-second 0.5

  \$ prefect gcl create my-gcl --limit 5 --inactive
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the global concurrency limit to create.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--limit">
      The limit of the global concurrency limit.
    </ResponseField>

    <ResponseField name="--disable">
      Create an inactive global concurrency limit.
    </ResponseField>

    <ResponseField name="--active-slots">
      The number of active slots.
    </ResponseField>

    <ResponseField name="--slot-decay-per-second">
      The slot decay per second.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/init



# `prefect init`

```command
prefect init [OPTIONS]
```

<Info>
  Initialize a new deployment configuration recipe.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--name" />

    <ResponseField name="--recipe" />

    <ResponseField name="-f">
      One or more fields to pass to the recipe (e.g., image\_name) in the format of key=value.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/profile



# `prefect profile`

```command
prefect profile [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Select and manage Prefect profiles.
</Info>

## `prefect profile ls`

```command
prefect profile ls [OPTIONS]
```

<Info>
  List profile names.
</Info>

## `prefect profile create`

```command
prefect profile create [OPTIONS] NAME
```

<Info>
  Create a new profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--from">
      Copy an existing profile.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profile use`

```command
prefect profile use [OPTIONS] NAME
```

<Info>
  Set the given profile to active.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profile delete`

```command
prefect profile delete [OPTIONS] NAME
```

<Info>
  Delete the given profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profile rename`

```command
prefect profile rename [OPTIONS] NAME NEW_NAME
```

<Info>
  Change the name of a profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>

    <ResponseField name="NEW_NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profile inspect`

```command
prefect profile inspect [OPTIONS] [NAME]
```

<Info>
  Display settings from a given profile; defaults to active.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      Name of profile to inspect; defaults to active profile.
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profile populate-defaults`

```command
prefect profile populate-defaults [OPTIONS]
```

<Info>
  Populate the profiles configuration with default base profiles, preserving existing user profiles.
</Info>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/profiles



# `prefect profiles`

```command
prefect profiles [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Select and manage Prefect profiles.
</Info>

## `prefect profiles ls`

```command
prefect profiles ls [OPTIONS]
```

<Info>
  List profile names.
</Info>

## `prefect profiles create`

```command
prefect profiles create [OPTIONS] NAME
```

<Info>
  Create a new profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--from">
      Copy an existing profile.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profiles use`

```command
prefect profiles use [OPTIONS] NAME
```

<Info>
  Set the given profile to active.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profiles delete`

```command
prefect profiles delete [OPTIONS] NAME
```

<Info>
  Delete the given profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profiles rename`

```command
prefect profiles rename [OPTIONS] NAME NEW_NAME
```

<Info>
  Change the name of a profile.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>

    <ResponseField name="NEW_NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profiles inspect`

```command
prefect profiles inspect [OPTIONS] [NAME]
```

<Info>
  Display settings from a given profile; defaults to active.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      Name of profile to inspect; defaults to active profile.
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect profiles populate-defaults`

```command
prefect profiles populate-defaults [OPTIONS]
```

<Info>
  Populate the profiles configuration with default base profiles, preserving existing user profiles.
</Info>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/server



# `prefect server`

```command
prefect server [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Start a Prefect server instance and interact with the database
</Info>

## `prefect server start`

```command
prefect server start [OPTIONS]
```

<Info>
  Start a Prefect server instance
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--host" />

    <ResponseField name="--port" />

    <ResponseField name="--keep-alive-timeout" />

    <ResponseField name="--log-level" />

    <ResponseField name="--scheduler" />

    <ResponseField name="--analytics-on" />

    <ResponseField name="--late-runs" />

    <ResponseField name="--ui" />

    <ResponseField name="--no-services">
      Only run the webserver API and UI
    </ResponseField>

    <ResponseField name="--background">
      Run the server in the background
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect server stop`

```command
prefect server stop [OPTIONS]
```

<Info>
  Stop a Prefect server instance running in the background
</Info>

## `prefect server database`

```command
prefect server database [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Interact with the database.
</Info>

### `prefect server database reset`

```command
prefect server database reset [OPTIONS]
```

<Info>
  Drop and recreate all Prefect database tables
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--yes" />
  </Accordion>
</AccordionGroup>

### `prefect server database upgrade`

```command
prefect server database upgrade [OPTIONS]
```

<Info>
  Upgrade the Prefect database
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--yes" />

    <ResponseField name="-r">
      The revision to pass to `alembic upgrade`. If not provided, runs all migrations.
    </ResponseField>

    <ResponseField name="--dry-run">
      Flag to show what migrations would be made without applying them. Will emit sql statements to stdout.
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect server database downgrade`

```command
prefect server database downgrade [OPTIONS]
```

<Info>
  Downgrade the Prefect database
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--yes" />

    <ResponseField name="-r">
      The revision to pass to `alembic downgrade`. If not provided, downgrades to the most recent revision. Use 'base' to run all migrations.
    </ResponseField>

    <ResponseField name="--dry-run">
      Flag to show what migrations would be made without applying them. Will emit sql statements to stdout.
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect server database revision`

```command
prefect server database revision [OPTIONS]
```

<Info>
  Create a new migration for the Prefect database
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--message">
      A message to describe the migration.
    </ResponseField>

    <ResponseField name="--autogenerate" />
  </Accordion>
</AccordionGroup>

### `prefect server database stamp`

```command
prefect server database stamp [OPTIONS] REVISION
```

<Info>
  Stamp the revision table with the given revision; don't run any migrations
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="REVISION" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect server services`

```command
prefect server services [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Interact with server loop services.
</Info>

### `prefect server services manager`

```command
prefect server services manager [OPTIONS]
```

<Info>
  This is an internal entrypoint used by `prefect server services start --background`.
  Users do not call this directly.

  We do everything in sync so that the child won't exit until the user kills it.
</Info>

### `prefect server services list-services`

```command
prefect server services list-services [OPTIONS]
```

<Info>
  List all available services and their status.
</Info>

### `prefect server services ls`

```command
prefect server services ls [OPTIONS]
```

<Info>
  List all available services and their status.
</Info>

### `prefect server services start-services`

```command
prefect server services start-services [OPTIONS]
```

<Info>
  Start all enabled Prefect services in one process.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--background">
      Run the services in the background
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect server services start`

```command
prefect server services start [OPTIONS]
```

<Info>
  Start all enabled Prefect services in one process.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--background">
      Run the services in the background
    </ResponseField>
  </Accordion>
</AccordionGroup>

### `prefect server services stop-services`

```command
prefect server services stop-services [OPTIONS]
```

<Info>
  Stop any background Prefect services that were started.
</Info>

### `prefect server services stop`

```command
prefect server services stop [OPTIONS]
```

<Info>
  Stop any background Prefect services that were started.
</Info>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/shell



# `prefect shell`

```command
prefect shell [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Serve and watch shell commands as Prefect flows.
</Info>

## `prefect shell watch`

```command
prefect shell watch [OPTIONS] COMMAND
```

<Info>
  Executes a shell command and observes it as Prefect flow.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="COMMAND" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--log-output">
      Log the output of the command to Prefect logs.
    </ResponseField>

    <ResponseField name="--flow-run-name">
      Name of the flow run.
    </ResponseField>

    <ResponseField name="--flow-name">
      Name of the flow.
    </ResponseField>

    <ResponseField name="--stream-stdout">
      Stream the output of the command.
    </ResponseField>

    <ResponseField name="--tag">
      Optional tags for the flow run.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect shell serve`

```command
prefect shell serve [OPTIONS] COMMAND
```

<Info>
  Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.

  This function allows users to integrate shell command execution into Prefect workflows seamlessly. It provides options for
  scheduled execution via cron expressions, flow and deployment naming for better management, and the application of tags for
  easier categorization and filtering within the Prefect UI. Additionally, it supports streaming command output to Prefect logs,
  setting concurrency limits to control flow execution, and optionally running the deployment once for ad-hoc tasks.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="COMMAND" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--flow-name">
      Name of the flow
    </ResponseField>

    <ResponseField name="--deployment-name">
      Name of the deployment
    </ResponseField>

    <ResponseField name="--tag">
      Tag for the deployment (can be provided multiple times)
    </ResponseField>

    <ResponseField name="--stream-stdout">
      Stream the output of the command
    </ResponseField>

    <ResponseField name="--cron-schedule">
      Cron schedule for the flow
    </ResponseField>

    <ResponseField name="--timezone">
      Timezone for the schedule
    </ResponseField>

    <ResponseField name="--concurrency-limit">
      The maximum number of flow runs that can execute at the same time
    </ResponseField>

    <ResponseField name="--run-once">
      Run the agent loop once, instead of forever.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/task



# `prefect task`

```command
prefect task [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Work with task scheduling.
</Info>

## `prefect task serve`

```command
prefect task serve [OPTIONS] [ENTRYPOINTS]...
```

<Info>
  Serve the provided tasks so that their runs may be submitted to and
  executed in the engine.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ENTRYPOINTS..." type="string">
      The paths to one or more tasks, in the form of `./path/to/file.py:task_func_name`.
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--module">
      The module(s) to import the tasks from.
    </ResponseField>

    <ResponseField name="--limit">
      The maximum number of tasks that can be run concurrently. Defaults to 10.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/task-run



# `prefect task-run`

```command
prefect task-run [OPTIONS] COMMAND [ARGS]...
```

<Info>
  View and inspect task runs.
</Info>

## `prefect task-run inspect`

```command
prefect task-run inspect [OPTIONS] ID
```

<Info>
  View details about a task run.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--web">
      Open the task run in a web browser.
    </ResponseField>

    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect task-run ls`

```command
prefect task-run ls [OPTIONS]
```

<Info>
  View recent task runs
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--task-run-name">
      Name of the task
    </ResponseField>

    <ResponseField name="--limit">
      Maximum number of task runs to list
    </ResponseField>

    <ResponseField name="--state">
      Name of the task run's state
    </ResponseField>

    <ResponseField name="--state-type">
      Type of the task run's state
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect task-run logs`

```command
prefect task-run logs [OPTIONS] ID
```

<Info>
  View logs for a task run.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="ID" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--head">
      Show the first 20 logs instead of all logs.
    </ResponseField>

    <ResponseField name="--num-logs">
      Number of logs to show when using the --head or --tail flag. If None, defaults to 20.
    </ResponseField>

    <ResponseField name="--reverse">
      Reverse the logs order to print the most recent logs first
    </ResponseField>

    <ResponseField name="--tail">
      Show the last 20 logs instead of all logs.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/variable



# `prefect variable`

```command
prefect variable [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage variables.
</Info>

## `prefect variable ls`

```command
prefect variable ls [OPTIONS]
```

<Info>
  List variables.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--limit">
      The maximum number of variables to return.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect variable inspect`

```command
prefect variable inspect [OPTIONS] NAME
```

<Info>
  View details about a variable.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect variable get`

```command
prefect variable get [OPTIONS] NAME
```

<Info>
  Get a variable's value.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect variable set`

```command
prefect variable set [OPTIONS] NAME VALUE
```

<Info>
  Set a variable.

  If the variable already exists, use `--overwrite` to update it.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>

    <ResponseField name="VALUE" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--overwrite">
      Overwrite the variable if it already exists.
    </ResponseField>

    <ResponseField name="--tag">
      Tag to associate with the variable.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect variable unset`

```command
prefect variable unset [OPTIONS] NAME
```

<Info>
  Unset a variable.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect variable delete`

```command
prefect variable delete [OPTIONS] NAME
```

<Info>
  Unset a variable.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/version



# `prefect version`

```command
prefect version [OPTIONS]
```

<Info>
  Get the current Prefect version and integration information.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--omit-integrations">
      Omit integration information
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/work-pool



# `prefect work-pool`

```command
prefect work-pool [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage work pools.
</Info>

## `prefect work-pool create`

```command
prefect work-pool create [OPTIONS] NAME
```

<Info>
  Create a new work pool or update an existing one.

  
  Examples:
  
  Create a Kubernetes work pool in a paused state:
  
  \$ prefect work-pool create "my-pool" --type kubernetes --paused
  
  Create a Docker work pool with a custom base job template:
  
  \$ prefect work-pool create "my-pool" --type docker --base-job-template ./base-job-template.json
  
  Update an existing work pool:
  
  \$ prefect work-pool create "existing-pool" --base-job-template ./base-job-template.json --overwrite
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--base-job-template">
      The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type.
    </ResponseField>

    <ResponseField name="--paused">
      Whether or not to create the work pool in a paused state.
    </ResponseField>

    <ResponseField name="-t">
      The type of work pool to create.
    </ResponseField>

    <ResponseField name="--set-as-default">
      Whether or not to use the created work pool as the local default for deployment.
    </ResponseField>

    <ResponseField name="--provision-infrastructure">
      Whether or not to provision infrastructure for the work pool if supported for the given work pool type.
    </ResponseField>

    <ResponseField name="--overwrite">
      Whether or not to overwrite an existing work pool with the same name.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool ls`

```command
prefect work-pool ls [OPTIONS]
```

<Info>
  List work pools.

  
  Examples:
  \$ prefect work-pool ls
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--verbose">
      Show additional information about work pools.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool inspect`

```command
prefect work-pool inspect [OPTIONS] NAME
```

<Info>
  Inspect a work pool.

  
  Examples:
  \$ prefect work-pool inspect "my-pool"
  \$ prefect work-pool inspect "my-pool" --output json
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to inspect.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool pause`

```command
prefect work-pool pause [OPTIONS] NAME
```

<Info>
  Pause a work pool.

  
  Examples:
  \$ prefect work-pool pause "my-pool"
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to pause.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool resume`

```command
prefect work-pool resume [OPTIONS] NAME
```

<Info>
  Resume a work pool.

  
  Examples:
  \$ prefect work-pool resume "my-pool"
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to resume.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool update`

```command
prefect work-pool update [OPTIONS] NAME
```

<Info>
  Update a work pool.

  
  Examples:
  \$ prefect work-pool update "my-pool"
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to update.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--base-job-template">
      The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. If None, the base job template will not be modified.
    </ResponseField>

    <ResponseField name="--concurrency-limit">
      The concurrency limit for the work pool. If None, the concurrency limit will not be modified.
    </ResponseField>

    <ResponseField name="--description">
      The description for the work pool. If None, the description will not be modified.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool provision-infrastructure`

```command
prefect work-pool provision-infrastructure [OPTIONS] NAME
```

<Info>
  Provision infrastructure for a work pool.

  
  Examples:
  \$ prefect work-pool provision-infrastructure "my-pool"

  \$ prefect work-pool provision-infra "my-pool"
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to provision infrastructure for.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool provision-infra`

```command
prefect work-pool provision-infra [OPTIONS] NAME
```

<Info>
  Provision infrastructure for a work pool.

  
  Examples:
  \$ prefect work-pool provision-infrastructure "my-pool"

  \$ prefect work-pool provision-infra "my-pool"
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to provision infrastructure for.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool delete`

```command
prefect work-pool delete [OPTIONS] NAME
```

<Info>
  Delete a work pool.

  
  Examples:
  \$ prefect work-pool delete "my-pool"
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to delete.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool set-concurrency-limit`

```command
prefect work-pool set-concurrency-limit [OPTIONS] NAME CONCURRENCY_LIMIT
```

<Info>
  Set the concurrency limit for a work pool.

  
  Examples:
  \$ prefect work-pool set-concurrency-limit "my-pool" 10
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to update.  \[required]
    </ResponseField>

    <ResponseField name="CONCURRENCY_LIMIT" type="string" required>
      The new concurrency limit for the work pool.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool clear-concurrency-limit`

```command
prefect work-pool clear-concurrency-limit [OPTIONS] NAME
```

<Info>
  Clear the concurrency limit for a work pool.

  
  Examples:
  \$ prefect work-pool clear-concurrency-limit "my-pool"
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name of the work pool to update.  \[required]
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool get-default-base-job-template`

```command
prefect work-pool get-default-base-job-template [OPTIONS]
```

<Info>
  Get the default base job template for a given work pool type.

  
  Examples:
  \$ prefect work-pool get-default-base-job-template --type kubernetes
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="-t">
      The type of work pool for which to get the default base job template.
    </ResponseField>

    <ResponseField name="-f">
      If set, write the output to a file.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool preview`

```command
prefect work-pool preview [OPTIONS] [NAME]
```

<Info>
  Preview the work pool's scheduled work for all queues.

  
  Examples:
  \$ prefect work-pool preview "my-pool" --hours 24
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      The name or ID of the work pool to preview
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-h">
      The number of hours to look ahead; defaults to 1 hour
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-pool storage`

```command
prefect work-pool storage [OPTIONS] COMMAND [ARGS]...
```

<Info>
  EXPERIMENTAL: Manage work pool storage.
</Info>

### `prefect work-pool storage inspect`

```command
prefect work-pool storage inspect [OPTIONS] WORK_POOL_NAME
```

<Info>
  EXPERIMENTAL: Inspect the storage configuration for a work pool.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="WORK_POOL_NAME" type="string" required>
      The name of the work pool to display storage configuration for.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  **Example:**

  $prefect work-pool storage inspect "my-pool"$ prefect work-pool storage inspect "my-pool" --output json
</Note>

### `prefect work-pool storage configure`

```command
prefect work-pool storage configure [OPTIONS] COMMAND [ARGS]...
```

<Info>
  EXPERIMENTAL: Configure work pool storage.
</Info>

#### `prefect work-pool storage configure s3`

```command
prefect work-pool storage configure s3 [OPTIONS] WORK_POOL_NAME
```

<Info>
  EXPERIMENTAL: Configure AWS S3 storage for a work pool.

  
  Examples:
  \$ prefect work-pool storage configure s3 "my-pool" --bucket my-bucket --aws-credentials-block-name my-credentials
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="WORK_POOL_NAME" type="string" required>
      The name of the work pool to configure storage for.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--bucket">
      The name of the S3 bucket to use.
    </ResponseField>

    <ResponseField name="--aws-credentials-block-name">
      The name of the AWS credentials block to use.
    </ResponseField>
  </Accordion>
</AccordionGroup>

#### `prefect work-pool storage configure gcs`

```command
prefect work-pool storage configure gcs [OPTIONS] WORK_POOL_NAME
```

<Info>
  EXPERIMENTAL: Configure Google Cloud storage for a work pool.

  
  Examples:
  \$ prefect work-pool storage configure gcs "my-pool" --bucket my-bucket --gcp-credentials-block-name my-credentials
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="WORK_POOL_NAME" type="string" required>
      The name of the work pool to configure storage for.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--bucket">
      The name of the Google Cloud Storage bucket to use.
    </ResponseField>

    <ResponseField name="--gcp-credentials-block-name">
      The name of the Google Cloud credentials block to use.
    </ResponseField>
  </Accordion>
</AccordionGroup>

#### `prefect work-pool storage configure azure-blob-storage`

```command
prefect work-pool storage configure azure-blob-storage [OPTIONS] WORK_POOL_NAME
```

<Info>
  EXPERIMENTAL: Configure Azure Blob Storage for a work pool.

  
  Examples:
  \$ prefect work-pool storage configure azure-blob-storage "my-pool" --container my-container --azure-blob-storage-credentials-block-name my-credentials
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="WORK_POOL_NAME" type="string" required>
      The name of the work pool to configure storage for.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="--container">
      The name of the Azure Blob Storage container to use.
    </ResponseField>

    <ResponseField name="--azure-blob-storage-credentials-block-name">
      The name of the Azure Blob Storage credentials block to use.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/work-queue



# `prefect work-queue`

```command
prefect work-queue [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Manage work queues.
</Info>

## `prefect work-queue create`

```command
prefect work-queue create [OPTIONS] NAME
```

<Info>
  Create a work queue.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The unique name to assign this work queue  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-l">
      The concurrency limit to set on the queue.
    </ResponseField>

    <ResponseField name="-p">
      The name of the work pool to create the work queue in.
    </ResponseField>

    <ResponseField name="-q">
      The associated priority for the created work queue
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue set-concurrency-limit`

```command
prefect work-queue set-concurrency-limit [OPTIONS] NAME LIMIT
```

<Info>
  Set a concurrency limit on a work queue.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name or ID of the work queue  \[required]
    </ResponseField>

    <ResponseField name="LIMIT" type="string" required>
      The concurrency limit to set on the queue.  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-p">
      The name of the work pool that the work queue belongs to.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue clear-concurrency-limit`

```command
prefect work-queue clear-concurrency-limit [OPTIONS] NAME
```

<Info>
  Clear any concurrency limits from a work queue.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name or ID of the work queue to clear  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-p">
      The name of the work pool that the work queue belongs to.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue pause`

```command
prefect work-queue pause [OPTIONS] NAME
```

<Info>
  Pause a work queue.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name or ID of the work queue to pause  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-p">
      The name of the work pool that the work queue belongs to.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue resume`

```command
prefect work-queue resume [OPTIONS] NAME
```

<Info>
  Resume a paused work queue.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name or ID of the work queue to resume  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-p">
      The name of the work pool that the work queue belongs to.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue inspect`

```command
prefect work-queue inspect [OPTIONS] [NAME]
```

<Info>
  Inspect a work queue by ID.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      The name or ID of the work queue to inspect
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-p">
      The name of the work pool that the work queue belongs to.
    </ResponseField>

    <ResponseField name="--output">
      Specify an output format. Currently supports: json
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue ls`

```command
prefect work-queue ls [OPTIONS]
```

<Info>
  View all work queues.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="--verbose">
      Display more information.
    </ResponseField>

    <ResponseField name="--match">
      Will match work queues with names that start with the specified prefix string
    </ResponseField>

    <ResponseField name="-p">
      The name of the work pool containing the work queues to list.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue preview`

```command
prefect work-queue preview [OPTIONS] [NAME]
```

<Info>
  Preview a work queue.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string">
      The name or ID of the work queue to preview
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-h">
      The number of hours to look ahead; defaults to 1 hour
    </ResponseField>

    <ResponseField name="-p">
      The name of the work pool that the work queue belongs to.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue delete`

```command
prefect work-queue delete [OPTIONS] NAME
```

<Info>
  Delete a work queue by ID.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name or ID of the work queue to delete  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-p">
      The name of the work pool containing the work queue to delete.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## `prefect work-queue read-runs`

```command
prefect work-queue read-runs [OPTIONS] NAME
```

<Info>
  Get runs in a work queue. Note that this will trigger an artificial poll of
  the work queue.
</Info>

<AccordionGroup>
  <Accordion title="Arguments" defaultOpen>
    <ResponseField name="NAME" type="string" required>
      The name or ID of the work queue to poll  \[required]
    </ResponseField>
  </Accordion>

  <Accordion title="Options" defaultOpen>
    <ResponseField name="-p">
      The name of the work pool containing the work queue to poll.
    </ResponseField>
  </Accordion>
</AccordionGroup>


#  
Source: https://docs-3.prefect.io/v3/api-ref/cli/worker



# `prefect worker`

```command
prefect worker [OPTIONS] COMMAND [ARGS]...
```

<Info>
  Start and interact with workers.
</Info>

## `prefect worker start`

```command
prefect worker start [OPTIONS]
```

<Info>
  Start a worker process to poll a work pool for flow runs.
</Info>

<AccordionGroup>
  <Accordion title="Options" defaultOpen>
    <ResponseField name="-n">
      The name to give to the started worker. If not provided, a unique name will be generated.
    </ResponseField>

    <ResponseField name="-p">
      The work pool the started worker should poll.
    </ResponseField>

    <ResponseField name="-q">
      One or more work queue names for the worker to pull from. If not provided, the worker will pull from all work queues in the work pool.
    </ResponseField>

    <ResponseField name="-t">
      The type of worker to start. If not provided, the worker type will be inferred from the work pool.
    </ResponseField>

    <ResponseField name="--prefetch-seconds">
      Number of seconds to look into the future for scheduled flow runs.
    </ResponseField>

    <ResponseField name="--run-once">
      Only run worker polling once. By default, the worker runs forever.
    </ResponseField>

    <ResponseField name="-l">
      Maximum number of flow runs to start simultaneously.
    </ResponseField>

    <ResponseField name="--with-healthcheck">
      Start a healthcheck server for the worker.
    </ResponseField>

    <ResponseField name="--install-policy">
      Install policy to use workers from Prefect integration packages.
    </ResponseField>

    <ResponseField name="--base-job-template">
      The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. If the work pool already exists, this will be ignored.
    </ResponseField>
  </Accordion>
</AccordionGroup>


# API & SDK References
Source: https://docs-3.prefect.io/v3/api-ref/index

Explore Prefect's auto-generated API & SDK reference documentation.

Prefect auto-generates reference documentation for the following components:

* **[Prefect Python SDK](/v3/api-ref/python)**: used to build, test, and execute workflows.
* **[Prefect REST API](/v3/api-ref/rest-api)**: used by workflow clients and the Prefect UI for orchestration and data retrieval.
  * Prefect Cloud REST API documentation: <a href="https://app.prefect.cloud/api/docs" target="_blank">[https://app.prefect.cloud/api/docs](https://app.prefect.cloud/api/docs)</a>.
  * Self-hosted Prefect server [REST API documentation](/v3/api-ref/rest-api/server/). Additionally, if self-hosting a Prefect server instance, you can access REST API documentation at the `/docs` endpoint of your [`PREFECT_API_URL`](/v3/develop/settings-and-profiles/). For example, if you run `prefect server start` with no additional configuration you can find this reference at <a href="http://localhost:4200/docs" target="_blank">[http://localhost:4200/docs](http://localhost:4200/docs)</a>.


# artifacts
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-artifacts



# `prefect.artifacts`

Interface for creating and reading artifacts.

## Functions

### `acreate_link_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate_link_artifact(link: str, link_text: str | None = None, key: str | None = None, description: str | None = None, client: 'PrefectClient | None' = None) -> UUID
```

Create a link artifact.

**Args:**

* `link`: The link to create.
* `link_text`: The link text.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The table artifact ID.

### `create_link_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L399" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_link_artifact(link: str, link_text: str | None = None, key: str | None = None, description: str | None = None, client: 'PrefectClient | None' = None) -> UUID
```

Create a link artifact.

**Args:**

* `link`: The link to create.
* `link_text`: The link text.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The table artifact ID.

### `acreate_markdown_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate_markdown_artifact(markdown: str, key: str | None = None, description: str | None = None) -> UUID
```

Create a markdown artifact.

**Args:**

* `markdown`: The markdown to create.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The table artifact ID.

### `create_markdown_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L478" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_markdown_artifact(markdown: str, key: str | None = None, description: str | None = None) -> UUID
```

Create a markdown artifact.

**Args:**

* `markdown`: The markdown to create.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The table artifact ID.

### `acreate_table_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L522" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate_table_artifact(table: dict[str, list[Any]] | list[dict[str, Any]] | list[list[Any]], key: str | None = None, description: str | None = None) -> UUID
```

Create a table artifact asynchronously.

**Args:**

* `table`: The table to create.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The table artifact ID.

### `create_table_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_table_artifact(table: dict[str, list[Any]] | list[dict[str, Any]] | list[list[Any]], key: str | None = None, description: str | None = None) -> UUID
```

Create a table artifact.

**Args:**

* `table`: The table to create.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The table artifact ID.

### `acreate_progress_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L597" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate_progress_artifact(progress: float, key: str | None = None, description: str | None = None) -> UUID
```

Create a progress artifact asynchronously.

**Args:**

* `progress`: The percentage of progress represented by a float between 0 and 100.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The progress artifact ID.

### `create_progress_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L627" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_progress_artifact(progress: float, key: str | None = None, description: str | None = None) -> UUID
```

Create a progress artifact.

**Args:**

* `progress`: The percentage of progress represented by a float between 0 and 100.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The progress artifact ID.

### `aupdate_progress_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L656" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aupdate_progress_artifact(artifact_id: UUID, progress: float, description: str | None = None, client: 'PrefectClient | None' = None) -> UUID
```

Update a progress artifact asynchronously.

**Args:**

* `artifact_id`: The ID of the artifact to update.
* `progress`: The percentage of progress represented by a float between 0 and 100.
* `description`: A user-specified description of the artifact.

**Returns:**

* The progress artifact ID.

### `update_progress_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L698" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_progress_artifact(artifact_id: UUID, progress: float, description: str | None = None, client: 'PrefectClient | None' = None) -> UUID
```

Update a progress artifact.

**Args:**

* `artifact_id`: The ID of the artifact to update.
* `progress`: The percentage of progress represented by a float between 0 and 100.
* `description`: A user-specified description of the artifact.

**Returns:**

* The progress artifact ID.

### `acreate_image_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L739" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate_image_artifact(image_url: str, key: str | None = None, description: str | None = None) -> UUID
```

Create an image artifact asynchronously.

**Args:**

* `image_url`: The URL of the image to display.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The image artifact ID.

### `create_image_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L769" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_image_artifact(image_url: str, key: str | None = None, description: str | None = None) -> UUID
```

Create an image artifact.

**Args:**

* `image_url`: The URL of the image to display.
* `key`: A user-provided string identifier.
  Required for the artifact to show in the Artifacts page in the UI.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.

**Returns:**

* The image artifact ID.

## Classes

### `Artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An artifact is a piece of data that is created by a flow or task run.
[https://docs.prefect.io/latest/develop/artifacts](https://docs.prefect.io/latest/develop/artifacts)

**Args:**

* `type`: A string identifying the type of artifact.
* `key`: A user-provided string identifier.
  The key must only contain lowercase letters, numbers, and dashes.
* `description`: A user-specified description of the artifact.
* `data`: A JSON payload that allows for a result to be retrieved.

**Methods:**

#### `acreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate(self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

An async method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str | float | int | dict[str, Any]
```

#### `aget` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A async method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `aget_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A async method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

#### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(self: Self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

A method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str | float | int | dict[str, Any]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

### `LinkArtifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `acreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate(self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

An async method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str
```

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str | float | int | dict[str, Any]
```

#### `aget` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A async method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `aget_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A async method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

#### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(self: Self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

A method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L269" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str
```

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str | float | int | dict[str, Any]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

### `MarkdownArtifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `acreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate(self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

An async method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str
```

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str | float | int | dict[str, Any]
```

#### `aget` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A async method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `aget_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A async method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

#### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(self: Self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

A method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str
```

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str | float | int | dict[str, Any]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

### `TableArtifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `acreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate(self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

An async method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str
```

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str | float | int | dict[str, Any]
```

#### `aget` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A async method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `aget_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A async method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

#### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(self: Self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

A method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str
```

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str | float | int | dict[str, Any]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

### `ProgressArtifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `acreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate(self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

An async method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> float
```

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str | float | int | dict[str, Any]
```

#### `aget` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A async method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `aget_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A async method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

#### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(self: Self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

A method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> float
```

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str | float | int | dict[str, Any]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

### `ImageArtifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L339" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An artifact that will display an image from a publicly accessible URL in the UI.

**Args:**

* `image_url`: The URL of the image to display.

**Methods:**

#### `acreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate(self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

An async method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str
```

#### `aformat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aformat(self) -> str | float | int | dict[str, Any]
```

#### `aget` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A async method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `aget_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A async method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.

#### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(self: Self, client: 'PrefectClient | None' = None) -> 'ArtifactResponse'
```

A method to create an artifact.

**Args:**

* `client`: The PrefectClient

**Returns:**

* The created artifact.

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L354" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str
```

This method is used to format the artifact data so it can be properly sent
to the API when the .create() method is called.

**Returns:**

* The image URL.

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self) -> str | float | int | dict[str, Any]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls, key: str | None = None, client: 'PrefectClient | None' = None) -> 'ArtifactResponse | None'
```

A method to get an artifact.

**Args:**

* `key`: The key of the artifact to get.
* `client`: A client to use when calling the Prefect API.

**Returns:**

* The artifact (if found).

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/artifacts.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls, key: str | None = None, description: str | None = None, data: dict[str, Any] | Any | None = None, client: 'PrefectClient | None' = None, **kwargs: Any) -> tuple['ArtifactResponse', bool]
```

A method to get or create an artifact.

**Args:**

* `key`: The key of the artifact to get or create.
* `description`: The description of the artifact to create.
* `data`: The data of the artifact to create.
* `client`: The PrefectClient
* `**kwargs`: Additional keyword arguments to use when creating the artifact.

**Returns:**

* The artifact, either retrieved or created.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-assets-__init__



# `prefect.assets`

*This module is empty or contains only private/internal implementations.*


# core
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-assets-core



# `prefect.assets.core`

## Functions

### `add_asset_metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/assets/core.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_asset_metadata(asset: str | Asset, metadata: dict[str, Any]) -> None
```

## Classes

### `AssetProperties` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/assets/core.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Metadata properties to configure on an Asset

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Asset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/assets/core.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Assets are objects that represent materialized data,
providing a way to track lineage and dependencies.

**Methods:**

#### `add_metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/assets/core.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_metadata(self, metadata: dict[str, Any]) -> None
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# materialize
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-assets-materialize



# `prefect.assets.materialize`

## Functions

### `materialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/assets/materialize.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
materialize(*assets: Union[str, Asset], **task_kwargs: Unpack[TaskOptions]) -> Callable[[Callable[P, R]], MaterializingTask[P, R]]
```

Decorator for materializing assets.

**Args:**

* `*assets`: Assets to materialize
* `by`: An optional tool that is ultimately responsible for materializing the asset e.g. "dbt" or "spark"
* `**task_kwargs`: Additional task configuration


# automations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-automations



# `prefect.automations`

## Classes

### `Automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `acreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acreate(self: Self) -> Self
```

Asynchronously create a new automation.

Examples:

```python
auto_to_create = Automation(
    name="woodchonk",
    trigger=EventTrigger(
        expect={"animal.walked"},
        match={
            "genus": "Marmota",
            "species": "monax",
        },
        posture="Reactive",
        threshold=3,
        within=timedelta(seconds=10),
    ),
    actions=[CancelFlowRun()]
)
created_automation = await auto_to_create.acreate()
```

#### `adelete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
adelete(self: Self) -> bool
```

Asynchronously delete an automation.

Examples:

```python
auto = Automation.read(id = 123)
await auto.adelete()
```

#### `adisable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
adisable(self: Self) -> bool
```

Asynchronously disable an automation.

**Raises:**

* `ValueError`: If the automation does not have an id
* `PrefectHTTPStatusError`: If the automation cannot be disabled

Example:

```python
auto = await Automation.aread(id = 123)
await auto.adisable()
```

#### `aenable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aenable(self: Self) -> bool
```

Asynchronously enable an automation.

**Raises:**

* `ValueError`: If the automation does not have an id
* `PrefectHTTPStatusError`: If the automation cannot be enabled

Example:

```python
auto = await Automation.aread(id = 123)
await auto.aenable()
```

#### `aread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aread(cls, id: UUID, name: Optional[str] = ...) -> Self
```

#### `aread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aread(cls, id: None = None, name: str = ...) -> Self
```

#### `aread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aread(cls, id: Optional[UUID] = None, name: Optional[str] = None) -> Self
```

Asynchronously read an automation by ID or name.

Examples:

```python
automation = await Automation.aread(name="woodchonk")
```

```python
automation = await Automation.aread(id=UUID("b3514963-02b1-47a5-93d1-6eeb131041cb"))
```

#### `aupdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aupdate(self: Self) -> None
```

Updates an existing automation.

Examples:

```python
auto = Automation.read(id=123)
auto.name = "new name"
auto.update()
```

#### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(self: Self) -> Self
```

Create a new automation.

Examples:

```python
auto_to_create = Automation(
    name="woodchonk",
    trigger=EventTrigger(
        expect={"animal.walked"},
        match={
            "genus": "Marmota",
            "species": "monax",
        },
        posture="Reactive",
        threshold=3,
        within=timedelta(seconds=10),
    ),
    actions=[CancelFlowRun()]
)
created_automation = auto_to_create.create()
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(self: Self) -> bool
```

Delete an automation.

Examples:

```python
auto = Automation.read(id = 123)
auto.delete()
```

#### `disable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable(self: Self) -> bool
```

Disable an automation.

**Raises:**

* `ValueError`: If the automation does not have an id
* `PrefectHTTPStatusError`: If the automation cannot be disabled

Example:

```python
auto = Automation.read(id = 123)
auto.disable()
```

#### `enable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L401" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enable(self: Self) -> bool
```

Enable an automation.

**Raises:**

* `ValueError`: If the automation does not have an id
* `PrefectHTTPStatusError`: If the automation cannot be enabled

Example:

```python
auto = Automation.read(id = 123)
auto.enable()
```

#### `read` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read(cls, id: UUID, name: Optional[str] = ...) -> Self
```

#### `read` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read(cls, id: None = None, name: str = ...) -> Self
```

#### `read` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read(cls, id: Optional[UUID] = None, name: Optional[str] = None) -> Self
```

Read an automation by ID or name.

Examples:

```python
automation = Automation.read(name="woodchonk")
```

```python
automation = Automation.read(id=UUID("b3514963-02b1-47a5-93d1-6eeb131041cb"))
```

#### `update` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/automations.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update(self: Self)
```

Updates an existing automation.

Examples:

```python
auto = Automation.read(id=123)
auto.name = "new name"
auto.update()
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-__init__



# `prefect.blocks`

*This module is empty or contains only private/internal implementations.*


# abstract
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-abstract



# `prefect.blocks.abstract`

## Classes

### `CredentialsBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Stores credentials for an external system and exposes a client for interacting
with that system. Can also hold config that is tightly coupled to credentials
(domain, endpoint, account ID, etc.) Will often be composed with other blocks.
Parent block should rely on the client provided by a credentials block for
interacting with the corresponding external system.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_client(self, *args: Any, **kwargs: Any) -> Any
```

Returns a client for interacting with the external system.

If a service offers various clients, this method can accept
a `client_type` keyword argument to get the desired client
within the service.

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the CredentialsBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `NotificationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised if a notification block fails to send a notification.

### `NotificationBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Block that represents a resource in an external system that is able to send notifications.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the NotificationBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

Send a notification.

**Args:**

* `body`: The body of the notification.
* `subject`: The subject of the notification.

#### `raise_on_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_on_failure(self) -> Generator[None, None, None]
```

Context manager that, while active, causes the block to raise errors if it
encounters a failure sending notifications.

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `JobRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a job run in an external system. Allows waiting
for the job run's completion and fetching its results.

**Methods:**

#### `fetch_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fetch_result(self) -> T
```

Retrieve the results of the job run and return them.

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the JobRun
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `wait_for_completion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_completion(self) -> Logger
```

Wait for the job run to complete.

### `JobBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Block that represents an entity in an external service
that can trigger a long running execution.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the JobBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `trigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
trigger(self) -> JobRun[T]
```

Triggers a job run in an external service and returns a JobRun object
to track the execution of the run.

### `DatabaseBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An abstract block type that represents a database and
provides an interface for interacting with it.

Blocks that implement this interface have the option to accept
credentials directly via attributes or via a nested `CredentialsBlock`.

Use of a nested credentials block is recommended unless credentials
are tightly coupled to database connection configuration.

Implementing either sync or async context management on `DatabaseBlock`
implementations is recommended.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `execute` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
execute(self, operation: str, parameters: dict[str, Any] | None = None, **execution_kwargs: Any) -> None
```

Executes an operation on the database. This method is intended to be used
for operations that do not return data, such as INSERT, UPDATE, or DELETE.

**Args:**

* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.

#### `execute_many` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
execute_many(self, operation: str, seq_of_parameters: list[dict[str, Any]], **execution_kwargs: Any) -> None
```

Executes multiple operations on the database. This method is intended to be used
for operations that do not return data, such as INSERT, UPDATE, or DELETE.

**Args:**

* `operation`: The SQL query or other operation to be executed.
* `seq_of_parameters`: The sequence of parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.

#### `fetch_all` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fetch_all(self, operation: str, parameters: dict[str, Any] | None = None, **execution_kwargs: Any) -> list[tuple[Any, ...]]
```

Fetch all results from the database.

**Args:**

* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.

**Returns:**

* A list of tuples containing the data returned by the database,
  where each row is a tuple and each column is a value in the tuple.

#### `fetch_many` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fetch_many(self, operation: str, parameters: dict[str, Any] | None = None, size: int | None = None, **execution_kwargs: Any) -> list[tuple[Any, ...]]
```

Fetch a limited number of results from the database.

**Args:**

* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `size`: The number of results to return.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.

**Returns:**

* A list of tuples containing the data returned by the database,
  where each row is a tuple and each column is a value in the tuple.

#### `fetch_one` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fetch_one(self, operation: str, parameters: dict[str, Any] | None = None, **execution_kwargs: Any) -> tuple[Any, ...]
```

Fetch a single result from the database.

**Args:**

* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.

**Returns:**

* A list of tuples containing the data returned by the database,
  where each row is a tuple and each column is a value in the tuple.

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the DatabaseBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `ObjectStorageBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Block that represents a resource in an external service that can store
objects.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `download_folder_to_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L423" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
download_folder_to_path(self, from_folder: str, to_folder: str | Path, **download_kwargs: Any) -> Path
```

Downloads a folder from the object storage service to a path.

**Args:**

* `from_folder`: The path to the folder to download from.
* `to_folder`: The path to download the folder to.
* `**download_kwargs`: Additional keyword arguments to pass to download.

**Returns:**

* The path that the folder was downloaded to.

#### `download_object_to_file_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
download_object_to_file_object(self, from_path: str, to_file_object: BinaryIO, **download_kwargs: Any) -> BinaryIO
```

Downloads an object from the object storage service to a file-like object,
which can be a BytesIO object or a BufferedWriter.

**Args:**

* `from_path`: The path to download from.
* `to_file_object`: The file-like object to download to.
* `**download_kwargs`: Additional keyword arguments to pass to download.

**Returns:**

* The file-like object that the object was downloaded to.

#### `download_object_to_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
download_object_to_path(self, from_path: str, to_path: str | Path, **download_kwargs: Any) -> Path
```

Downloads an object from the object storage service to a path.

**Args:**

* `from_path`: The path to download from.
* `to_path`: The path to download to.
* `**download_kwargs`: Additional keyword arguments to pass to download.

**Returns:**

* The path that the object was downloaded to.

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L368" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the ObjectStorageBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `upload_from_file_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L458" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
upload_from_file_object(self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Any) -> str
```

Uploads an object to the object storage service from a file-like object,
which can be a BytesIO object or a BufferedReader.

**Args:**

* `from_file_object`: The file-like object to upload from.
* `to_path`: The path to upload the object to.
* `**upload_kwargs`: Additional keyword arguments to pass to upload.

**Returns:**

* The path that the object was uploaded to.

#### `upload_from_folder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L475" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
upload_from_folder(self, from_folder: str | Path, to_folder: str, **upload_kwargs: Any) -> str
```

Uploads a folder to the object storage service from a path.

**Args:**

* `from_folder`: The path to the folder to upload from.
* `to_folder`: The path to upload the folder to.
* `**upload_kwargs`: Additional keyword arguments to pass to upload.

**Returns:**

* The path that the folder was uploaded to.

#### `upload_from_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L442" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
upload_from_path(self, from_path: str | Path, to_path: str, **upload_kwargs: Any) -> str
```

Uploads an object from a path to the object storage service.

**Args:**

* `from_path`: The path to the file to upload from.
* `to_path`: The path to upload the file to.
* `**upload_kwargs`: Additional keyword arguments to pass to upload.

**Returns:**

* The path that the object was uploaded to.

### `SecretBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L494" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Block that represents a resource that can store and retrieve secrets.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L500" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the SecretBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `read_secret` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_secret(self) -> bytes
```

Reads the configured secret from the secret storage service.

**Returns:**

* The secret data.

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `write_secret` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L525" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_secret(self, secret_data: bytes) -> str
```

Writes secret data to the configured secret in the secret storage service.

**Args:**

* `secret_data`: The secret data to write.

**Returns:**

* The key of the secret that can be used for retrieval.


# core
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-core



# `prefect.blocks.core`

## Functions

### `block_schema_to_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_schema_to_key(schema: BlockSchema) -> str
```

Defines the unique key used to lookup the Block class for a given schema.

### `schema_extra` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schema_extra(schema: dict[str, Any], model: type['Block']) -> None
```

Customizes Pydantic's schema generation feature to add blocks related information.

## Classes

### `InvalidBlockRegistration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised on attempted registration of the base Block
class or a Block interface class

### `UnknownBlockType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a block type is not found in the registry.

### `BlockNotSavedError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a given block is not saved and an operation that requires
the block to be saved is attempted.

### `Block` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base class for implementing a block that wraps an external service.

This class can be defined with an arbitrary set of fields and methods, and
couples business logic with data contained in an block document.
`_block_document_name`, `_block_document_id`, `_block_schema_id`, and
`_block_type_id` are reserved by Prefect as Block metadata fields, but
otherwise a Block can implement arbitrary logic. Blocks can be instantiated
without populating these metadata fields, but can only be used interactively,
not with the Prefect API.

Instead of the **init** method, a block implementation allows the
definition of a `block_initialization` method that is called after
initialization.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```


# fields
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-fields



# `prefect.blocks.fields`

*This module is empty or contains only private/internal implementations.*


# notifications
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-notifications



# `prefect.blocks.notifications`

## Classes

### `AbstractAppriseNotificationBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An abstract class for sending notifications using Apprise.

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the NotificationBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

Send a notification.

**Args:**

* `body`: The body of the notification.
* `subject`: The subject of the notification.

#### `raise_on_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_on_failure(self) -> Generator[None, None, None]
```

Context manager that, while active, causes the block to raise errors if it
encounters a failure sending notifications.

### `AppriseNotificationBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base class for sending notifications using Apprise, through webhook URLs.

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None)
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

### `SlackWebhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via a provided Slack webhook.

**Examples:**

Load a saved Slack webhook and send a message:

```python
from prefect.blocks.notifications import SlackWebhook

slack_webhook_block = SlackWebhook.load("BLOCK_NAME")
slack_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None)
```

### `MicrosoftTeamsWebhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via a provided Microsoft Teams webhook.

**Examples:**

Load a saved Teams webhook and send a message:

```python
from prefect.blocks.notifications import MicrosoftTeamsWebhook
teams_webhook_block = MicrosoftTeamsWebhook.load("BLOCK_NAME")
teams_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

see [https://github.com/caronc/apprise/pull/1172](https://github.com/caronc/apprise/pull/1172)

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None)
```

### `PagerDutyWebHook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via a provided PagerDuty webhook.
See [Apprise notify\_pagerduty docs](https://github.com/caronc/apprise/wiki/Notify_pagerduty)
for more info on formatting the URL.

**Examples:**

Load a saved PagerDuty webhook and send a message:

```python
from prefect.blocks.notifications import PagerDutyWebHook
pagerduty_webhook_block = PagerDutyWebHook.load("BLOCK_NAME")
pagerduty_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None)
```

Apprise will combine subject and body by default, so we need to move
the body into the custom\_details field. custom\_details is part of the
webhook url, so we need to update the url and restart the client.

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

### `TwilioSMS` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via Twilio SMS.
Find more on sending Twilio SMS messages in the [docs](https://www.twilio.com/docs/sms).

**Examples:**

Load a saved `TwilioSMS` block and send a message:

```python
from prefect.blocks.notifications import TwilioSMS
twilio_webhook_block = TwilioSMS.load("BLOCK_NAME")
twilio_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

### `OpsgenieWebhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L404" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via a provided Opsgenie webhook.
See [Apprise notify\_opsgenie docs](https://github.com/caronc/apprise/wiki/Notify_opsgenie)
for more info on formatting the URL.

**Examples:**

Load a saved Opsgenie webhook and send a message:

```python
from prefect.blocks.notifications import OpsgenieWebhook
opsgenie_webhook_block = OpsgenieWebhook.load("BLOCK_NAME")
opsgenie_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L492" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

### `MattermostWebhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L528" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via a provided Mattermost webhook.
See [Apprise notify\_Mattermost docs](https://github.com/caronc/apprise/wiki/Notify_Mattermost) # noqa

**Examples:**

Load a saved Mattermost webhook and send a message:

```python
from prefect.blocks.notifications import MattermostWebhook

mattermost_webhook_block = MattermostWebhook.load("BLOCK_NAME")

mattermost_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L596" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

### `DiscordWebhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L621" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via a provided Discord webhook.
See [Apprise notify\_Discord docs](https://github.com/caronc/apprise/wiki/Notify_Discord) # noqa

**Examples:**

Load a saved Discord webhook and send a message:

```python
from prefect.blocks.notifications import DiscordWebhook

discord_webhook_block = DiscordWebhook.load("BLOCK_NAME")

discord_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L701" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

### `CustomWebhookNotificationBlock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L725" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via any custom webhook.

All nested string param contains `{{key}}` will be substituted with value from context/secrets.

Context values include: `subject`, `body` and `name`.

**Examples:**

Load a saved custom webhook and send a message:

```python
from prefect.blocks.notifications import CustomWebhookNotificationBlock

custom_webhook_block = CustomWebhookNotificationBlock.load("BLOCK_NAME")

custom_webhook_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L829" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logger(self) -> LoggerOrAdapter
```

Returns a logger based on whether the NotificationBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.

**Returns:**

* The run logger or a default logger with the class's name.

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L848" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```

Send a notification.

**Args:**

* `body`: The body of the notification.
* `subject`: The subject of the notification.

#### `raise_on_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/abstract.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_on_failure(self) -> Generator[None, None, None]
```

Context manager that, while active, causes the block to raise errors if it
encounters a failure sending notifications.

### `SendgridEmail` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L862" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enables sending notifications via any sendgrid account.
See [Apprise Notify\_sendgrid docs](https://github.com/caronc/apprise/wiki/Notify_Sendgrid)

**Examples:**

Load a saved Sendgrid and send a email message:

```python
from prefect.blocks.notifications import SendgridEmail

sendgrid_block = SendgridEmail.load("BLOCK_NAME")

sendgrid_block.notify("Hello from Prefect!")
```

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L907" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L932" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None)
```

#### `notify` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/notifications.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
notify(self, body: str, subject: str | None = None) -> None
```


# redis
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-redis



# `prefect.blocks.redis`

## Classes

### `RedisStorageContainer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/redis.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Block used to interact with Redis as a filesystem

**Methods:**

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/redis.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `from_connection_string` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/redis.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_connection_string(cls, connection_string: str | SecretStr) -> Self
```

Create block from a Redis connection string

Supports the following URL schemes:

* `redis://` creates a TCP socket connection
* `rediss://` creates a SSL wrapped TCP socket connection
* `unix://` creates a Unix Domain Socket connection

See \[Redis docs]\([https://redis.readthedocs.io/en/stable/examples](https://redis.readthedocs.io/en/stable/examples)
/connection\_examples.html#Connecting-to-Redis-instances-by-specifying-a-URL
-scheme.) for more info.

**Args:**

* `connection_string`: Redis connection string

**Returns:**

* `RedisStorageContainer` instance

#### `from_host` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/redis.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_host(cls, host: str, port: int = 6379, db: int = 0, username: None | str | SecretStr = None, password: None | str | SecretStr = None) -> Self
```

Create block from hostname, username and password

**Args:**

* `host`: Redis hostname
* `username`: Redis username
* `password`: Redis password
* `port`: Redis port

**Returns:**

* `RedisStorageContainer` instance

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/redis.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: Path | str)
```

Read the redis content at `path`

**Args:**

* `path`: Redis key to read from

**Returns:**

* Contents at key as bytes

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/redis.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: Path | str, content: bytes)
```

Write `content` to the redis at `path`

**Args:**

* `path`: Redis key to write to
* `content`: Binary object to write

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> None
```


# system
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-system



# `prefect.blocks.system`

## Classes

### `JSON` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/system.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A block that represents JSON. Deprecated, please use Variables to store JSON data instead.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `String` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/system.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A block that represents a string. Deprecated, please use Variables to store string data instead.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `DateTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/system.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A block that represents a datetime. Deprecated, please use Variables to store datetime data instead.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `Secret` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/system.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A block that represents a secret value. The value stored in this block will be obfuscated when
this block is viewed or edited in the UI.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/system.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self) -> T | str
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `validate_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/system.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_value(cls, value: Union[T, SecretStr, PydanticSecret[T]]) -> Union[SecretStr, PydanticSecret[T]]
```


# webhook
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-blocks-webhook



# `prefect.blocks.webhook`

## Classes

### `Webhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/webhook.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Block that enables calling webhooks.

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/webhook.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `call` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/webhook.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call(self, payload: dict[str, Any] | str | None = None) -> Response
```

Call the webhook.

**Args:**

* `payload`: an optional payload to send when calling the webhook.

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```


# cache_policies
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cache_policies



# `prefect.cache_policies`

## Classes

### `CachePolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for all cache policies.

**Methods:**

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `configure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure(self, key_storage: Union['WritableFileSystem', str, Path, None] = None, lock_manager: Optional['LockManager'] = None, isolation_level: Union[Literal['READ_COMMITTED', 'SERIALIZABLE'], 'IsolationLevel', None] = None) -> Self
```

Configure the cache policy with the given key storage, lock manager, and isolation level.

**Args:**

* `key_storage`: The storage to use for cache keys. If not provided,
  the current key storage will be used.
* `lock_manager`: The lock manager to use for the cache policy. If not provided,
  the current lock manager will be used.
* `isolation_level`: The isolation level to use for the cache policy. If not provided,
  the current isolation level will be used.

**Returns:**

* A new cache policy with the given key storage, lock manager, and isolation level.

#### `from_cache_key_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cache_key_fn(cls, cache_key_fn: Callable[['TaskRunContext', Dict[str, Any]], Optional[str]]) -> 'CacheKeyFnPolicy'
```

Given a function generates a key policy.

### `CacheKeyFnPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

This policy accepts a custom function with signature f(task\_run\_context, task\_parameters, flow\_parameters) -> str
and uses it to compute a task run cache key.

**Methods:**

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `configure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure(self, key_storage: Union['WritableFileSystem', str, Path, None] = None, lock_manager: Optional['LockManager'] = None, isolation_level: Union[Literal['READ_COMMITTED', 'SERIALIZABLE'], 'IsolationLevel', None] = None) -> Self
```

Configure the cache policy with the given key storage, lock manager, and isolation level.

**Args:**

* `key_storage`: The storage to use for cache keys. If not provided,
  the current key storage will be used.
* `lock_manager`: The lock manager to use for the cache policy. If not provided,
  the current lock manager will be used.
* `isolation_level`: The isolation level to use for the cache policy. If not provided,
  the current isolation level will be used.

**Returns:**

* A new cache policy with the given key storage, lock manager, and isolation level.

#### `from_cache_key_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cache_key_fn(cls, cache_key_fn: Callable[['TaskRunContext', Dict[str, Any]], Optional[str]]) -> 'CacheKeyFnPolicy'
```

Given a function generates a key policy.

### `CompoundCachePolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

This policy is constructed from two or more other cache policies and works by computing the keys
for each policy individually, and then hashing a sorted tuple of all computed keys.

Any keys that return `None` will be ignored.

**Methods:**

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `configure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure(self, key_storage: Union['WritableFileSystem', str, Path, None] = None, lock_manager: Optional['LockManager'] = None, isolation_level: Union[Literal['READ_COMMITTED', 'SERIALIZABLE'], 'IsolationLevel', None] = None) -> Self
```

Configure the cache policy with the given key storage, lock manager, and isolation level.

**Args:**

* `key_storage`: The storage to use for cache keys. If not provided,
  the current key storage will be used.
* `lock_manager`: The lock manager to use for the cache policy. If not provided,
  the current lock manager will be used.
* `isolation_level`: The isolation level to use for the cache policy. If not provided,
  the current isolation level will be used.

**Returns:**

* A new cache policy with the given key storage, lock manager, and isolation level.

#### `from_cache_key_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cache_key_fn(cls, cache_key_fn: Callable[['TaskRunContext', Dict[str, Any]], Optional[str]]) -> 'CacheKeyFnPolicy'
```

Given a function generates a key policy.

### `TaskSource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Policy for computing a cache key based on the source code of the task.

This policy only considers raw lines of code in the task, and not the source code of nested tasks.

**Methods:**

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: Optional[dict[str, Any]], flow_parameters: Optional[dict[str, Any]], **kwargs: Any) -> Optional[str]
```

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `configure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure(self, key_storage: Union['WritableFileSystem', str, Path, None] = None, lock_manager: Optional['LockManager'] = None, isolation_level: Union[Literal['READ_COMMITTED', 'SERIALIZABLE'], 'IsolationLevel', None] = None) -> Self
```

Configure the cache policy with the given key storage, lock manager, and isolation level.

**Args:**

* `key_storage`: The storage to use for cache keys. If not provided,
  the current key storage will be used.
* `lock_manager`: The lock manager to use for the cache policy. If not provided,
  the current lock manager will be used.
* `isolation_level`: The isolation level to use for the cache policy. If not provided,
  the current isolation level will be used.

**Returns:**

* A new cache policy with the given key storage, lock manager, and isolation level.

#### `from_cache_key_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cache_key_fn(cls, cache_key_fn: Callable[['TaskRunContext', Dict[str, Any]], Optional[str]]) -> 'CacheKeyFnPolicy'
```

Given a function generates a key policy.

### `FlowParameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L307" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Policy that computes the cache key based on a hash of the flow parameters.

**Methods:**

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `configure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure(self, key_storage: Union['WritableFileSystem', str, Path, None] = None, lock_manager: Optional['LockManager'] = None, isolation_level: Union[Literal['READ_COMMITTED', 'SERIALIZABLE'], 'IsolationLevel', None] = None) -> Self
```

Configure the cache policy with the given key storage, lock manager, and isolation level.

**Args:**

* `key_storage`: The storage to use for cache keys. If not provided,
  the current key storage will be used.
* `lock_manager`: The lock manager to use for the cache policy. If not provided,
  the current lock manager will be used.
* `isolation_level`: The isolation level to use for the cache policy. If not provided,
  the current isolation level will be used.

**Returns:**

* A new cache policy with the given key storage, lock manager, and isolation level.

#### `from_cache_key_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cache_key_fn(cls, cache_key_fn: Callable[['TaskRunContext', Dict[str, Any]], Optional[str]]) -> 'CacheKeyFnPolicy'
```

Given a function generates a key policy.

### `RunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L325" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Returns either the prevailing flow run ID, or if not found, the prevailing task
run ID.

**Methods:**

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `configure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure(self, key_storage: Union['WritableFileSystem', str, Path, None] = None, lock_manager: Optional['LockManager'] = None, isolation_level: Union[Literal['READ_COMMITTED', 'SERIALIZABLE'], 'IsolationLevel', None] = None) -> Self
```

Configure the cache policy with the given key storage, lock manager, and isolation level.

**Args:**

* `key_storage`: The storage to use for cache keys. If not provided,
  the current key storage will be used.
* `lock_manager`: The lock manager to use for the cache policy. If not provided,
  the current lock manager will be used.
* `isolation_level`: The isolation level to use for the cache policy. If not provided,
  the current isolation level will be used.

**Returns:**

* A new cache policy with the given key storage, lock manager, and isolation level.

#### `from_cache_key_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cache_key_fn(cls, cache_key_fn: Callable[['TaskRunContext', Dict[str, Any]], Optional[str]]) -> 'CacheKeyFnPolicy'
```

Given a function generates a key policy.

### `Inputs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Policy that computes a cache key based on a hash of the runtime inputs provided to the task..

**Methods:**

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L354" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `compute_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_key(self, task_ctx: TaskRunContext, inputs: dict[str, Any], flow_parameters: dict[str, Any], **kwargs: Any) -> Optional[str]
```

#### `configure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure(self, key_storage: Union['WritableFileSystem', str, Path, None] = None, lock_manager: Optional['LockManager'] = None, isolation_level: Union[Literal['READ_COMMITTED', 'SERIALIZABLE'], 'IsolationLevel', None] = None) -> Self
```

Configure the cache policy with the given key storage, lock manager, and isolation level.

**Args:**

* `key_storage`: The storage to use for cache keys. If not provided,
  the current key storage will be used.
* `lock_manager`: The lock manager to use for the cache policy. If not provided,
  the current lock manager will be used.
* `isolation_level`: The isolation level to use for the cache policy. If not provided,
  the current isolation level will be used.

**Returns:**

* A new cache policy with the given key storage, lock manager, and isolation level.

#### `from_cache_key_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cache_policies.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cache_key_fn(cls, cache_key_fn: Callable[['TaskRunContext', Dict[str, Any]], Optional[str]]) -> 'CacheKeyFnPolicy'
```

Given a function generates a key policy.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-__init__



# `prefect.cli`

*This module is empty or contains only private/internal implementations.*


# artifact
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-artifact



# `prefect.cli.artifact`

## Functions

### `list_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/artifact.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
list_artifacts(limit: int = typer.Option(100, '--limit', help='The maximum number of artifacts to return.'), all: bool = typer.Option(False, '--all', '-a', help='Whether or not to only return the latest version of each artifact.'))
```

List artifacts.

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/artifact.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(key: str, limit: int = typer.Option(10, '--limit', help='The maximum number of artifacts to return.'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

View details about an artifact.

**Args:**

* `key`: the key of the artifact to inspect

**Examples:**

`$ prefect artifact inspect "my-artifact"`

```json
[
  {
    'id': 'ba1d67be-0bd7-452e-8110-247fe5e6d8cc',
    'created': '2023-03-21T21:40:09.895910+00:00',
    'updated': '2023-03-21T21:40:09.895910+00:00',
    'key': 'my-artifact',
    'type': 'markdown',
    'description': None,
    'data': 'my markdown',
    'metadata_': None,
    'flow_run_id': '8dc54b6f-6e24-4586-a05c-e98c6490cb98',
    'task_run_id': None
  },
  {
    'id': '57f235b5-2576-45a5-bd93-c829c2900966',
    'created': '2023-03-27T23:16:15.536434+00:00',
    'updated': '2023-03-27T23:16:15.536434+00:00',
    'key': 'my-artifact',
    'type': 'markdown',
    'description': 'my-artifact-description',
    'data': 'my markdown',
    'metadata_': None,
    'flow_run_id': 'ffa91051-f249-48c1-ae0f-4754fcb7eb29',
    'task_run_id': None
  }
]
```

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/artifact.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(key: Optional[str] = typer.Argument(None, help='The key of the artifact to delete.'), artifact_id: Optional[UUID] = typer.Option(None, '--id', help='The ID of the artifact to delete.'))
```

Delete an artifact.

**Args:**

* `key`: the key of the artifact to delete

**Examples:**

`$ prefect artifact delete "my-artifact"`


# block
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-block



# `prefect.cli.block`

Command line interface for working with blocks.

## Functions

### `display_block` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
display_block(block_document: 'BlockDocument') -> Table
```

### `display_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
display_block_type(block_type: 'BlockType') -> Table
```

### `display_block_schema_properties` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
display_block_schema_properties(block_schema_fields: dict[str, Any]) -> Table
```

### `display_block_schema_extra_definitions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
display_block_schema_extra_definitions(block_schema_definitions: dict[str, Any]) -> Table
```

### `register` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register(module_name: Optional[str] = typer.Option(None, '--module', '-m', help='Python module containing block types to be registered'), file_path: Optional[Path] = typer.Option(None, '--file', '-f', help='Path to .py file containing block types to be registered'))
```

Register blocks types within a module or file.

This makes the blocks available for configuration via the UI.
If a block type has already been registered, its registration will be updated to
match the block's current definition.


Examples:

Register block types in a Python module:
$prefect block register -m prefect_aws.credentials
    
    Register block types in a .py file:
   $ prefect block register -f my\_blocks.py

### `block_ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_ls()
```

View all configured blocks.

### `block_delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_delete(slug: Optional[str] = typer.Argument(None, help="A block slug. Formatted as '<BLOCK_TYPE_SLUG>/<BLOCK_NAME>'"), block_id: Optional[UUID] = typer.Option(None, '--id', help='A block id.'))
```

Delete a configured block.

### `block_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_create(block_type_slug: str = typer.Argument(..., help='A block type slug. View available types with: prefect block type ls', show_default=False))
```

Generate a link to the Prefect UI to create a block.

### `block_inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_inspect(slug: Optional[str] = typer.Argument(None, help='A Block slug: <BLOCK_TYPE_SLUG>/<BLOCK_NAME>'), block_id: Optional[UUID] = typer.Option(None, '--id', help='A Block id to search for if no slug is given'))
```

Displays details about a configured block.

### `list_types` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
list_types()
```

List all block types.

### `blocktype_inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
blocktype_inspect(slug: str = typer.Argument(..., help='A block type slug'))
```

Display details about a block type.

### `blocktype_delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/block.py#L473" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
blocktype_delete(slug: str = typer.Argument(..., help='A Block type slug'))
```

Delete an unprotected Block Type.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-cloud-__init__



# `prefect.cli.cloud`

Command line interface for interacting with Prefect Cloud

## Functions

### `set_login_api_ready_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_login_api_ready_event() -> None
```

### `lifespan` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
lifespan(app: FastAPI)
```

### `receive_login` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
receive_login(payload: LoginSuccess) -> None
```

### `receive_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
receive_failure(payload: LoginFailed) -> None
```

### `serve_login_api` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve_login_api(cancel_scope: anyio.CancelScope, task_status: anyio.abc.TaskStatus[uvicorn.Server]) -> None
```

### `confirm_logged_in` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
confirm_logged_in() -> None
```

### `get_current_workspace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_current_workspace(workspaces: Iterable[Workspace]) -> Workspace | None
```

### `prompt_select_from_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prompt_select_from_list(console: Console, prompt: str, options: list[str] | list[tuple[T, str]]) -> str | T
```

Given a list of options, display the values to user in a table and prompt them
to select one.

**Args:**

* `options`: A list of options to present to the user.
  A list of tuples can be passed as key value pairs. If a value is chosen, the
  key will be returned.

**Returns:**

* the selected option

### `login_with_browser` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L269" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
login_with_browser() -> str
```

Perform login using the browser.

On failure, this function will exit the process.
On success, it will return an API key.

### `check_key_is_valid_for_login` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_key_is_valid_for_login(key: str) -> bool
```

Attempt to use a key to see if it is valid

### `login` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
login(key: Optional[str] = typer.Option(None, '--key', '-k', help='API Key to authenticate with Prefect'), workspace_handle: Optional[str] = typer.Option(None, '--workspace', '-w', help="Full handle of workspace, in format '<account_handle>/<workspace_handle>'"))
```

Log in to Prefect Cloud.
Creates a new profile configured to use the specified PREFECT\_API\_KEY.
Uses a previously configured profile if it exists.

### `logout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L598" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logout()
```

Logout the current workspace.
Reset PREFECT\_API\_KEY and PREFECT\_API\_URL to default.

### `open` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L624" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
open()
```

Open the Prefect Cloud UI in the browser.

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L647" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls()
```

List available workspaces.

### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L677" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(workspace_handle: str = typer.Option(None, '--workspace', '-w', help="Full handle of workspace, in format '<account_handle>/<workspace_handle>'"))
```

Set current workspace. Shows a workspace picker if no workspace is specified.

## Classes

### `LoginSuccess` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `LoginFailed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `LoginResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `ServerExit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/__init__.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# ip_allowlist
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-cloud-ip_allowlist



# `prefect.cli.cloud.ip_allowlist`

## Functions

### `require_access_to_ip_allowlisting` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
require_access_to_ip_allowlisting(ctx: typer.Context) -> None
```

Enforce access to IP allowlisting for all subcommands.

### `enable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enable(ctx: typer.Context) -> None
```

Enable the IP allowlist for your account. When enabled, if the allowlist is non-empty, then access to your Prefect Cloud account will be restricted to only those IP addresses on the allowlist.

### `disable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable()
```

Disable the IP allowlist for your account. When disabled, all IP addresses will be allowed to access your Prefect Cloud account.

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(ctx: typer.Context)
```

Fetch and list all IP allowlist entries in your account.

### `parse_ip_network_argument` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_ip_network_argument(val: str) -> IPNetworkArg
```

### `add` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add(ctx: typer.Context, ip_address_or_range: IP_ARGUMENT, description: Optional[str] = typer.Option(None, '--description', '-d', help='A short description to annotate the entry with.'))
```

Add a new IP entry to your account IP allowlist.

### `remove` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove(ctx: typer.Context, ip_address_or_range: IP_ARGUMENT)
```

Remove an IP entry from your account IP allowlist.

### `toggle` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
toggle(ctx: typer.Context, ip_address_or_range: IP_ARGUMENT)
```

Toggle the enabled status of an individual IP entry in your account IP allowlist.

## Classes

### `IPNetworkArg` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/ip_allowlist.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# webhook
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-cloud-webhook



# `prefect.cli.cloud.webhook`

Command line interface for working with webhooks

## Functions

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/webhook.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls()
```

Fetch and list all webhooks in your workspace

### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/webhook.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(webhook_id: UUID)
```

Retrieve a webhook by ID.

### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/webhook.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(webhook_name: str, description: str = typer.Option('', '--description', '-d', help='Description of the webhook'), template: str = typer.Option(None, '--template', '-t', help='Jinja2 template expression'))
```

Create a new Cloud webhook

### `rotate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/webhook.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rotate(webhook_id: UUID)
```

Rotate url for an existing Cloud webhook, in case it has been compromised

### `toggle` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/webhook.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
toggle(webhook_id: UUID)
```

Toggle the enabled status of an existing Cloud webhook

### `update` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/webhook.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update(webhook_id: UUID, webhook_name: str = typer.Option(None, '--name', '-n', help='Webhook name'), description: str = typer.Option(None, '--description', '-d', help='Description of the webhook'), template: str = typer.Option(None, '--template', '-t', help='Jinja2 template expression'))
```

Partially update an existing Cloud webhook

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/cloud/webhook.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(webhook_id: UUID)
```

Delete an existing Cloud webhook


# concurrency_limit
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-concurrency_limit



# `prefect.cli.concurrency_limit`

Command line interface for working with concurrency limits.

## Functions

### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/concurrency_limit.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(tag: str, concurrency_limit: int)
```

Create a concurrency limit against a tag.

This limit controls how many task runs with that tag may simultaneously be in a
Running state.

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/concurrency_limit.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(tag: str, output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

View details about a concurrency limit. `active_slots` shows a list of TaskRun IDs
which are currently using a concurrency slot.

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/concurrency_limit.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(limit: int = 15, offset: int = 0)
```

View all concurrency limits.

### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/concurrency_limit.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(tag: str)
```

Resets the concurrency limit slots set on the specified tag.

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/concurrency_limit.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(tag: str)
```

Delete the concurrency limit set on the specified tag.


# config
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-config



# `prefect.cli.config`

Command line interface for working with profiles

## Functions

### `set_` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/config.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_(settings: list[str])
```

Change the value for a setting by setting the value in the current profile.

### `validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/config.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate()
```

Read and validate the current profile.

Deprecated settings will be automatically converted to new names unless both are
set.

### `unset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/config.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unset(setting_names: list[str], confirm: bool = typer.Option(False, '--yes', '-y'))
```

Restore the default value for a setting.

Removes the setting from the current profile.

### `view` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/config.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
view(show_defaults: bool = typer.Option(False, '--show-defaults/--hide-defaults', help=show_defaults_help), show_sources: bool = typer.Option(True, '--show-sources/--hide-sources', help=show_sources_help), show_secrets: bool = typer.Option(False, '--show-secrets/--hide-secrets', help='Toggle display of secrets setting values.'))
```

Display the current settings.


# dashboard
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-dashboard



# `prefect.cli.dashboard`

## Functions

### `open` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dashboard.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
open() -> None
```

Open the Prefect UI in the browser.


# deployment
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-deployment



# `prefect.cli.deployment`

Command line interface for working with deployments.

## Functions

### `str_presenter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
str_presenter(dumper: yaml.Dumper | yaml.representer.SafeRepresenter, data: str) -> yaml.ScalarNode
```

configures yaml for dumping multiline strings
Ref: [https://stackoverflow.com/questions/8640959/how-can-i-control-what-scalar-form-pyyaml-uses-for-my-data](https://stackoverflow.com/questions/8640959/how-can-i-control-what-scalar-form-pyyaml-uses-for-my-data)

### `assert_deployment_name_format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_deployment_name_format(name: str) -> None
```

### `get_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_deployment(client: 'PrefectClient', name: str | None, deployment_id: str | None) -> DeploymentResponse
```

### `create_work_queue_and_set_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_work_queue_and_set_concurrency_limit(work_queue_name: str, work_pool_name: str | None, work_queue_concurrency: int | None) -> None
```

### `check_work_pool_exists` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_work_pool_exists(work_pool_name: str | None, client: 'PrefectClient | None' = None)
```

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L224" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(name: str, output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

View details about a deployment.

**Examples:**

`$ prefect deployment inspect "hello-world/my-deployment"`

```python
{
    'id': '610df9c3-0fb4-4856-b330-67f588d20201',
    'created': '2022-08-01T18:36:25.192102+00:00',
    'updated': '2022-08-01T18:36:25.188166+00:00',
    'name': 'my-deployment',
    'description': None,
    'flow_id': 'b57b0aa2-ef3a-479e-be49-381fb0483b4e',
    'schedules': None,
    'parameters': {'name': 'Marvin'},
    'tags': ['test'],
    'parameter_openapi_schema': {
        'title': 'Parameters',
        'type': 'object',
        'properties': {
            'name': {
                'title': 'name',
                'type': 'string'
            }
        },
        'required': ['name']
    },
    'storage_document_id': '63ef008f-1e5d-4e07-a0d4-4535731adb32',
    'infrastructure_document_id': '6702c598-7094-42c8-9785-338d2ec3a028',
    'infrastructure': {
        'type': 'process',
        'env': {},
        'labels': {},
        'name': None,
        'command': ['python', '-m', 'prefect.engine'],
        'stream_output': True
    }
}
```

### `create_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_schedule(name: str, interval: Optional[float] = typer.Option(None, '--interval', help='An interval to schedule on, specified in seconds', min=0.0001), interval_anchor: Optional[str] = typer.Option(None, '--anchor-date', help='The anchor date for an interval schedule'), rrule_string: Optional[str] = typer.Option(None, '--rrule', help='Deployment schedule rrule string'), cron_string: Optional[str] = typer.Option(None, '--cron', help='Deployment schedule cron string'), cron_day_or: bool = typer.Option(True, '--day_or', help='Control how croniter handles `day` and `day_of_week` entries'), timezone: Optional[str] = typer.Option(None, '--timezone', help="Deployment schedule timezone string e.g. 'America/New_York'"), active: bool = typer.Option(True, '--active', help='Whether the schedule is active. Defaults to True.'), replace: Optional[bool] = typer.Option(False, '--replace', help="Replace the deployment's current schedule(s) with this new schedule."), assume_yes: Optional[bool] = typer.Option(False, '--accept-yes', '-y', help='Accept the confirmation prompt without prompting'))
```

Create a schedule for a given deployment.

### `delete_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L470" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_schedule(deployment_name: str, schedule_id: UUID, assume_yes: bool = typer.Option(False, '--accept-yes', '-y', help='Accept the confirmation prompt without prompting'))
```

Delete a deployment schedule.

### `pause_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L629" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause_schedule(deployment_name: Optional[str] = typer.Argument(None), schedule_id: Optional[UUID] = typer.Argument(None), _all: bool = typer.Option(False, '--all', help='Pause all deployment schedules'))
```

Pause deployment schedules.

**Examples:**

Pause a specific schedule:
\$ prefect deployment schedule pause my-flow/my-deployment abc123-...

Pause all schedules:
\$ prefect deployment schedule pause --all

### `resume_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L648" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_schedule(deployment_name: Optional[str] = typer.Argument(None), schedule_id: Optional[UUID] = typer.Argument(None), _all: bool = typer.Option(False, '--all', help='Resume all deployment schedules'))
```

Resume deployment schedules.

**Examples:**

Resume a specific schedule:
\$ prefect deployment schedule resume my-flow/my-deployment abc123-...

Resume all schedules:
\$ prefect deployment schedule resume --all

### `list_schedules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L667" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
list_schedules(deployment_name: str)
```

View all schedules for a deployment.

### `clear_schedules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L710" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_schedules(deployment_name: str, assume_yes: bool = typer.Option(False, '--accept-yes', '-y', help='Accept the confirmation prompt without prompting'))
```

Clear all schedules for a deployment.

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L747" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(flow_name: Optional[list[str]] = None, by_created: bool = False)
```

View all deployments or deployments for specific flows.

### `run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L796" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run(name: Optional[str] = typer.Argument(None, help="A deployed flow's name: <FLOW_NAME>/<DEPLOYMENT_NAME>"), deployment_id: Optional[str] = typer.Option(None, '--id', help='A deployment id to search for if no name is given'), job_variables: list[str] = typer.Option(None, '-jv', '--job-variable', help='A key, value pair (key=value) specifying a flow run job variable. The value will be interpreted as JSON. May be passed multiple times to specify multiple job variable values.'), params: list[str] = typer.Option(None, '-p', '--param', help='A key, value pair (key=value) specifying a flow parameter. The value will be interpreted as JSON. May be passed multiple times to specify multiple parameter values.'), multiparams: Optional[str] = typer.Option(None, '--params', help="A mapping of parameters to values. To use a stdin, pass '-'. Any parameters passed with `--param` will take precedence over these values."), start_in: Optional[str] = typer.Option(None, '--start-in', help="A human-readable string specifying a time interval to wait before starting the flow run. E.g. 'in 5 minutes', 'in 1 hour', 'in 2 days'."), start_at: Optional[str] = typer.Option(None, '--start-at', help="A human-readable string specifying a time to start the flow run. E.g. 'at 5:30pm', 'at 2022-08-01 17:30', 'at 2022-08-01 17:30:00'."), tags: list[str] = typer.Option(None, '--tag', help='Tag(s) to be applied to flow run.'), watch: bool = typer.Option(False, '--watch', help='Whether to poll the flow run until a terminal state is reached.'), watch_interval: Optional[int] = typer.Option(None, '--watch-interval', help='How often to poll the flow run for state changes (in seconds).'), watch_timeout: Optional[int] = typer.Option(None, '--watch-timeout', help='Timeout for --watch.'), flow_run_name: Optional[str] = typer.Option(None, '--flow-run-name', help='Custom name to give the flow run.'))
```

Create a flow run for the given flow and deployment.

The flow run will be scheduled to run immediately unless `--start-in` or `--start-at` is specified.
The flow run will not execute until a worker starts.
To watch the flow run until it reaches a terminal state, use the `--watch` flag.

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L1050" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(name: Optional[str] = typer.Argument(None, help="A deployed flow's name: <FLOW_NAME>/<DEPLOYMENT_NAME>"), deployment_id: Optional[UUID] = typer.Option(None, '--id', help='A deployment id to search for if no name is given'), _all: bool = typer.Option(False, '--all', help='Delete all deployments'))
```

Delete a deployment.

**Examples:**

```bash
$ prefect deployment delete test_flow/test_deployment
$ prefect deployment delete --id dfd3e220-a130-4149-9af6-8d487e02fea6
```

## Classes

### `RichTextIO` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `write` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/deployment.py#L217" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write(self, content: str) -> None
```


# dev
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-dev



# `prefect.cli.dev`

Command line interface for working with Prefect Server

## Functions

### `exit_with_error_if_not_editable_install` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exit_with_error_if_not_editable_install() -> None
```

### `build_docs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_docs(schema_path: Optional[str] = None)
```

Builds REST API reference documentation for static display.

### `build_ui` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_ui(no_install: bool = False)
```

### `ui` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ui()
```

Starts a hot-reloading development UI.

### `api` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
api(host: str = SettingsOption(PREFECT_SERVER_API_HOST), port: int = SettingsOption(PREFECT_SERVER_API_PORT), log_level: str = 'DEBUG', services: bool = True)
```

Starts a hot-reloading development API.

### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(exclude_api: bool = typer.Option(False, '--no-api'), exclude_ui: bool = typer.Option(False, '--no-ui'))
```

Starts a hot-reloading development server with API, UI, and agent processes.

Each service has an individual command if you wish to start them separately.
Each service can be excluded here as well.

### `build_image` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_image(arch: str = typer.Option(None, help=f'The architecture to build the container for. Defaults to the architecture of the host Python. [default: {platform.machine()}]'), python_version: str = typer.Option(None, help=f'The Python version to build the container for. Defaults to the version of the host Python. [default: {python_version_minor()}]'), flavor: str = typer.Option(None, help="An alternative flavor to build, for example 'conda'. Defaults to the standard Python base image"), dry_run: bool = False)
```

Build a docker image for development.

### `container` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/dev.py#L296" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
container(bg: bool = False, name = 'prefect-dev', api: bool = True, tag: Optional[str] = None)
```

Run a docker container with local code mounted and installed.


# events
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-events



# `prefect.cli.events`

## Functions

### `stream` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/events.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stream(format: StreamFormat = typer.Option(StreamFormat.json, '--format', help='Output format (json or text)'), output_file: str = typer.Option(None, '--output-file', help='File to write events to'), account: bool = typer.Option(False, '--account', help='Stream events for entire account, including audit logs'), run_once: bool = typer.Option(False, '--run-once', help='Stream only one event'))
```

Subscribes to the event stream of a workspace, printing each event
as it is received. By default, events are printed as JSON, but can be
printed as text by passing `--format text`.

### `handle_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/events.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_event(event: Event, format: StreamFormat, output_file: str) -> None
```

### `handle_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/events.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_error(exc: Exception) -> None
```

## Classes

### `StreamFormat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/events.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# flow
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-flow



# `prefect.cli.flow`

Command line interface for working with flows.

## Functions

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(limit: int = 15)
```

View flows.

### `serve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve(entrypoint: str = typer.Argument(..., help='The path to a file containing a flow and the name of the flow function in the format `./path/to/file.py:flow_func_name`.'), name: str = typer.Option(..., '--name', '-n', help='The name to give the deployment created for the flow.'), description: Optional[str] = typer.Option(None, '--description', '-d', help="The description to give the created deployment. If not provided, the description will be populated from the flow's description."), version: Optional[str] = typer.Option(None, '-v', '--version', help='A version to give the created deployment.'), tags: Optional[List[str]] = typer.Option(None, '-t', '--tag', help='One or more optional tags to apply to the created deployment.'), cron: Optional[str] = typer.Option(None, '--cron', help='A cron string that will be used to set a schedule for the created deployment.'), interval: Optional[int] = typer.Option(None, '--interval', help='An integer specifying an interval (in seconds) between scheduled runs of the flow.'), interval_anchor: Optional[str] = typer.Option(None, '--anchor-date', help='The start date for an interval schedule.'), rrule: Optional[str] = typer.Option(None, '--rrule', help='An RRule that will be used to set a schedule for the created deployment.'), timezone: Optional[str] = typer.Option(None, '--timezone', help="Timezone to used scheduling flow runs e.g. 'America/New_York'"), pause_on_shutdown: bool = typer.Option(True, help='If set, provided schedule will be paused when the serve command is stopped. If not set, the schedules will continue running.'), limit: Optional[int] = typer.Option(None, help='The maximum number of runs that can be executed concurrently by the created runner; only applies to this served flow. To apply a limit across multiple served flows, use global_limit.'), global_limit: Optional[int] = typer.Option(None, help='The maximum number of concurrent runs allowed across all served flow instances associated with the same deployment.'))
```

Serve a flow via an entrypoint.


# flow_run
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-flow_run



# `prefect.cli.flow_run`

Command line interface for working with flow runs

## Functions

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow_run.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(id: UUID, web: bool = typer.Option(False, '--web', help='Open the flow run in a web browser.'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

View details about a flow run.

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow_run.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(flow_name: List[str] = typer.Option(None, help='Name of the flow'), limit: int = typer.Option(15, help='Maximum number of flow runs to list'), state: List[str] = typer.Option(None, help="Name of the flow run's state"), state_type: List[str] = typer.Option(None, help="Type of the flow run's state"))
```

View recent flow runs or flow runs for specific flows.

Arguments:

flow\_name: Name of the flow

limit: Maximum number of flow runs to list. Defaults to 15.

state: Name of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'PAUSED', 'SUSPENDED', 'AWAITINGRETRY', 'RETRYING', and 'LATE'.

state\_type: Type of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'CRASHED', and 'PAUSED'.

Examples:

\$ prefect flow-runs ls --state Running

\$ prefect flow-runs ls --state Running --state late

\$ prefect flow-runs ls --state-type RUNNING

\$ prefect flow-runs ls --state-type RUNNING --state-type FAILED

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow_run.py#L224" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(id: UUID)
```

Delete a flow run by ID.

### `cancel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow_run.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cancel(id: UUID)
```

Cancel a flow run by ID.

### `logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow_run.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logs(id: UUID, head: bool = typer.Option(False, '--head', '-h', help=f'Show the first {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of all logs.'), num_logs: int = typer.Option(None, '--num-logs', '-n', help=f'Number of logs to show when using the --head or --tail flag. If None, defaults to {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS}.', min=1), reverse: bool = typer.Option(False, '--reverse', '-r', help='Reverse the logs order to print the most recent logs first'), tail: bool = typer.Option(False, '--tail', '-t', help=f'Show the last {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of all logs.'))
```

View logs for a flow run.

### `execute` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/flow_run.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
execute(id: Optional[UUID] = typer.Argument(None, help='ID of the flow run to execute'))
```


# global_concurrency_limit
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-global_concurrency_limit



# `prefect.cli.global_concurrency_limit`

## Functions

### `list_global_concurrency_limits` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/global_concurrency_limit.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
list_global_concurrency_limits()
```

List all global concurrency limits.

### `inspect_global_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/global_concurrency_limit.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect_global_concurrency_limit(name: str = typer.Argument(..., help='The name of the global concurrency limit to inspect.'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'), file_path: Optional[Path] = typer.Option(None, '--file', '-f', help='Path to .json file to write the global concurrency limit output to.'))
```

Inspect a global concurrency limit.

**Args:**

* `name`: The name of the global concurrency limit to inspect.
* `output`: An output format for the command. Currently only supports JSON.
  Required if --file/-f is set.
* `file_path`: A path to .json file to write the global concurrent limit output to.

**Returns:**

* The ID of the global concurrency limit.
* The created date of the global concurrency limit.
* The updated date of the global concurrency limit.
* The name of the global concurrency limit.
* The limit of the global concurrency limit.
* The number of active slots.
* The slot decay per second.

### `delete_global_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/global_concurrency_limit.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_global_concurrency_limit(name: str = typer.Argument(..., help='The name of the global concurrency limit to delete.'))
```

Delete a global concurrency limit.

**Args:**

* `name`: The name of the global concurrency limit to delete.

### `enable_global_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/global_concurrency_limit.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enable_global_concurrency_limit(name: str = typer.Argument(..., help='The name of the global concurrency limit to enable.'))
```

Enable a global concurrency limit.

**Args:**

* `name`: The name of the global concurrency limit to enable.

### `disable_global_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/global_concurrency_limit.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable_global_concurrency_limit(name: str = typer.Argument(..., help='The name of the global concurrency limit to disable.'))
```

Disable a global concurrency limit.

**Args:**

* `name`: The name of the global concurrency limit to disable.

### `update_global_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/global_concurrency_limit.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_global_concurrency_limit(name: str = typer.Argument(..., help='The name of the global concurrency limit to update.'), enable: Optional[bool] = typer.Option(None, '--enable', help='Enable the global concurrency limit.'), disable: Optional[bool] = typer.Option(None, '--disable', help='Disable the global concurrency limit.'), limit: Optional[int] = typer.Option(None, '--limit', '-l', help='The limit of the global concurrency limit.'), active_slots: Optional[int] = typer.Option(None, '--active-slots', help='The number of active slots.'), slot_decay_per_second: Optional[float] = typer.Option(None, '--slot-decay-per-second', help='The slot decay per second.'))
```

Update a global concurrency limit.

**Args:**

* `name`: The name of the global concurrency limit to update.
* `enable`: Enable the global concurrency limit.
* `disable`: Disable the global concurrency limit.
* `limit`: The limit of the global concurrency limit.
* `active_slots`: The number of active slots.
* `slot_decay_per_second`: The slot decay per second.

**Examples:**

$prefect global-concurrency-limit update my-gcl --limit 10$ prefect gcl update my-gcl --active-slots 5
$prefect gcl update my-gcl --slot-decay-per-second 0.5$ prefect gcl update my-gcl --enable
\$ prefect gcl update my-gcl --disable --limit 5

### `create_global_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/global_concurrency_limit.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_global_concurrency_limit(name: str = typer.Argument(..., help='The name of the global concurrency limit to create.'), limit: int = typer.Option(..., '--limit', '-l', help='The limit of the global concurrency limit.'), disable: Optional[bool] = typer.Option(None, '--disable', help='Create an inactive global concurrency limit.'), active_slots: Optional[int] = typer.Option(0, '--active-slots', help='The number of active slots.'), slot_decay_per_second: Optional[float] = typer.Option(0.0, '--slot-decay-per-second', help='The slot decay per second.'))
```

Create a global concurrency limit.

Arguments:

name (str): The name of the global concurrency limit to create.

limit (int): The limit of the global concurrency limit.

disable (Optional\[bool]): Create an inactive global concurrency limit.

active\_slots (Optional\[int]): The number of active slots.

slot\_decay\_per\_second (Optional\[float]): The slot decay per second.

Examples:

\$ prefect global-concurrency-limit create my-gcl --limit 10

\$ prefect gcl create my-gcl --limit 5 --active-slots 3

\$ prefect gcl create my-gcl --limit 5 --active-slots 3 --slot-decay-per-second 0.5

\$ prefect gcl create my-gcl --limit 5 --inactive


# profile
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-profile



# `prefect.cli.profile`

Command line interface for working with profiles.

## Functions

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls()
```

List profile names.

### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(name: str, from_name: str = typer.Option(None, '--from', help='Copy an existing profile.'))
```

Create a new profile.

### `use` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
use(name: str)
```

Set the given profile to active.

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(name: str)
```

Delete the given profile.

### `rename` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rename(name: str, new_name: str)
```

Change the name of a profile.

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(name: Optional[str] = typer.Argument(None, help='Name of profile to inspect; defaults to active profile.'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

Display settings from a given profile; defaults to active.

### `show_profile_changes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
show_profile_changes(user_profiles: ProfilesCollection, default_profiles: ProfilesCollection) -> bool
```

### `populate_defaults` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
populate_defaults()
```

Populate the profiles configuration with default base profiles, preserving existing user profiles.

### `check_server_connection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L371" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_server_connection() -> ConnectionStatus
```

## Classes

### `ConnectionStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/profile.py#L360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`


# root
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-root



# `prefect.cli.root`

Base `prefect` command-line application

## Functions

### `version_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/root.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
version_callback(value: bool) -> None
```

### `is_interactive` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/root.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_interactive() -> bool
```

### `main` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/root.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
main(ctx: typer.Context, version: bool = typer.Option(None, '--version', '-v', callback=version_callback, help='Display the current version.', is_eager=True), profile: str = typer.Option(None, '--profile', '-p', help='Select a profile for this CLI run.', is_eager=True), prompt: bool = SettingsOption(prefect.settings.PREFECT_CLI_PROMPT, help='Force toggle prompts for this CLI run.'))
```

### `version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/root.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
version(omit_integrations: bool = typer.Option(False, '--omit-integrations', help='Omit integration information'))
```

Get the current Prefect version and integration information.

### `get_prefect_integrations` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/root.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_prefect_integrations() -> dict[str, str]
```

Get information about installed Prefect integrations.

### `display` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/root.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
display(object: dict[str, Any], nesting: int = 0) -> None
```

Recursive display of a dictionary with nesting.


# server
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-server



# `prefect.cli.server`

Command line interface for working with the Prefect API and server.

## Functions

### `generate_welcome_blurb` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_welcome_blurb(base_url: str, ui_enabled: bool) -> str
```

### `prestart_check` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prestart_check(base_url: str) -> None
```

Check if `PREFECT_API_URL` is set in the current profile. If not, prompt the user to set it.

**Args:**

* `base_url`: The base URL the server will be running on

### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(host: str = SettingsOption(PREFECT_SERVER_API_HOST), port: int = SettingsOption(PREFECT_SERVER_API_PORT), keep_alive_timeout: int = SettingsOption(PREFECT_SERVER_API_KEEPALIVE_TIMEOUT), log_level: str = SettingsOption(PREFECT_SERVER_LOGGING_LEVEL), scheduler: bool = SettingsOption(PREFECT_API_SERVICES_SCHEDULER_ENABLED), analytics: bool = SettingsOption(PREFECT_SERVER_ANALYTICS_ENABLED, '--analytics-on/--analytics-off'), late_runs: bool = SettingsOption(PREFECT_API_SERVICES_LATE_RUNS_ENABLED), ui: bool = SettingsOption(PREFECT_UI_ENABLED), no_services: bool = typer.Option(False, '--no-services', help='Only run the webserver API and UI'), background: bool = typer.Option(False, '--background', '-b', help='Run the server in the background'), workers: int = typer.Option(1, '--workers', help='Number of worker processes to run. Only runs the webserver API and UI'))
```

Start a Prefect server instance

### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L509" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop()
```

Stop a Prefect server instance running in the background

### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(yes: bool = typer.Option(False, '--yes', '-y'))
```

Drop and recreate all Prefect database tables

### `upgrade` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L550" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
upgrade(yes: bool = typer.Option(False, '--yes', '-y'), revision: str = typer.Option('head', '-r', help='The revision to pass to `alembic upgrade`. If not provided, runs all migrations.'), dry_run: bool = typer.Option(False, help='Flag to show what migrations would be made without applying them. Will emit sql statements to stdout.'))
```

Upgrade the Prefect database

### `downgrade` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
downgrade(yes: bool = typer.Option(False, '--yes', '-y'), revision: str = typer.Option('-1', '-r', help="The revision to pass to `alembic downgrade`. If not provided, downgrades to the most recent revision. Use 'base' to run all migrations."), dry_run: bool = typer.Option(False, help='Flag to show what migrations would be made without applying them. Will emit sql statements to stdout.'))
```

Downgrade the Prefect database

### `revision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L633" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
revision(message: str = typer.Option(None, '--message', '-m', help='A message to describe the migration.'), autogenerate: bool = False)
```

Create a new migration for the Prefect database

### `stamp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L655" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stamp(revision: str)
```

Stamp the revision table with the given revision; don't run any migrations

### `run_manager_process` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L698" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_manager_process()
```

This is an internal entrypoint used by `prefect server services start --background`.
Users do not call this directly.

We do everything in sync so that the child won't exit until the user kills it.

### `list_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L720" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
list_services()
```

List all available services and their status.

### `start_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L743" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_services(background: bool = typer.Option(False, '--background', '-b', help='Run the services in the background'))
```

Start all enabled Prefect services in one process.

### `stop_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/server.py#L802" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop_services()
```

Stop any background Prefect services that were started.


# shell
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-shell



# `prefect.cli.shell`

Provides a set of tools for executing shell commands as Prefect flows.
Includes functionalities for running shell commands ad-hoc or serving them as Prefect flows,
with options for logging output, scheduling, and deployment customization.

## Functions

### `output_stream` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/shell.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
output_stream(pipe: IO[str], logger_function: Callable[[str], None]) -> None
```

Read from a pipe line by line and log using the provided logging function.

**Args:**

* `pipe`: A file-like object for reading process output.
* `logger_function`: A logging function from the logger.

### `output_collect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/shell.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
output_collect(pipe: IO[str], container: list[str]) -> None
```

Collects output from a subprocess pipe and stores it in a container list.

**Args:**

* `pipe`: The output pipe of the subprocess, either stdout or stderr.
* `container`: A list to store the collected output lines.

### `run_shell_process` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/shell.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_shell_process(command: str, log_output: bool = True, stream_stdout: bool = False, log_stderr: bool = False, popen_kwargs: Optional[Dict[str, Any]] = None)
```

Asynchronously executes the specified shell command and logs its output.

This function is designed to be used within Prefect flows to run shell commands as part of task execution.
It handles both the execution of the command and the collection of its output for logging purposes.

**Args:**

* `command`: The shell command to execute.
* `log_output`: If True, the output of the command (both stdout and stderr) is logged to Prefect.
* `stream_stdout`: If True, the stdout of the command is streamed to Prefect logs.
* `log_stderr`: If True, the stderr of the command is logged to Prefect logs.
* `popen_kwargs`: Additional keyword arguments to pass to the `subprocess.Popen` call.

### `watch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/shell.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
watch(command: str, log_output: bool = typer.Option(True, help='Log the output of the command to Prefect logs.'), flow_run_name: str = typer.Option(None, help='Name of the flow run.'), flow_name: str = typer.Option('Shell Command', help='Name of the flow.'), stream_stdout: bool = typer.Option(True, help='Stream the output of the command.'), tag: Annotated[Optional[List[str]], typer.Option(help='Optional tags for the flow run.')] = None)
```

Executes a shell command and observes it as Prefect flow.

**Args:**

* `command`: The shell command to be executed.
* `log_output`: If True, logs the command's output. Defaults to True.
* `flow_run_name`: An optional name for the flow run.
* `flow_name`: An optional name for the flow. Useful for identification in the Prefect UI.
* `tag`: An optional list of tags for categorizing and filtering flows in the Prefect UI.

### `serve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/shell.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve(command: str, flow_name: str = typer.Option(..., help='Name of the flow'), deployment_name: str = typer.Option('CLI Runner Deployment', help='Name of the deployment'), deployment_tags: List[str] = typer.Option(None, '--tag', help='Tag for the deployment (can be provided multiple times)'), log_output: bool = typer.Option(True, help='Stream the output of the command', hidden=True), stream_stdout: bool = typer.Option(True, help='Stream the output of the command'), cron_schedule: str = typer.Option(None, help='Cron schedule for the flow'), timezone: str = typer.Option(None, help='Timezone for the schedule'), concurrency_limit: int = typer.Option(None, min=1, help='The maximum number of flow runs that can execute at the same time'), run_once: bool = typer.Option(False, help='Run the agent loop once, instead of forever.'))
```

Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.

This function allows users to integrate shell command execution into Prefect workflows seamlessly. It provides options for
scheduled execution via cron expressions, flow and deployment naming for better management, and the application of tags for
easier categorization and filtering within the Prefect UI. Additionally, it supports streaming command output to Prefect logs,
setting concurrency limits to control flow execution, and optionally running the deployment once for ad-hoc tasks.

**Args:**

* `command`: The shell command the flow will execute.
* `name`: The name assigned to the flow. This is required..
* `deployment_tags`: Optional tags for the deployment to facilitate filtering and organization.
* `log_output`: If True, streams the output of the shell command to the Prefect logs. Defaults to True.
* `cron_schedule`: A cron expression that defines when the flow will run. If not provided, the flow can be triggered manually.
* `timezone`: The timezone for the cron schedule. This is important if the schedule should align with local time.
* `concurrency_limit`: The maximum number of instances of the flow that can run simultaneously.
* `deployment_name`: The name of the deployment. This helps distinguish deployments within the Prefect platform.
* `run_once`: When True, the flow will only run once upon deployment initiation, rather than continuously.


# task
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-task



# `prefect.cli.task`

## Functions

### `serve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/task.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve(entrypoints: Optional[list[str]] = typer.Argument(None, help='The paths to one or more tasks, in the form of `./path/to/file.py:task_func_name`.'), module: Optional[list[str]] = typer.Option(None, '--module', '-m', help='The module(s) to import the tasks from.'), limit: int = typer.Option(10, help='The maximum number of tasks that can be run concurrently. Defaults to 10.'))
```

Serve the provided tasks so that their runs may be submitted to and
executed in the engine.

**Args:**

* `entrypoints`: List of strings representing the paths to one or more
  tasks. Each path should be in the format
  `./path/to/file.py\:task_func_name`.
* `module`: The module(s) to import the task definitions from.
* `limit`: The maximum number of tasks that can be run concurrently. Defaults to 10.


# task_run
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-task_run



# `prefect.cli.task_run`

Command line interface for working with task runs

## Functions

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/task_run.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(id: UUID, web: bool = typer.Option(False, '--web', help='Open the task run in a web browser.'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

View details about a task run.

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/task_run.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(task_run_name: List[str] = typer.Option(None, help='Name of the task'), limit: int = typer.Option(15, help='Maximum number of task runs to list'), state: List[str] = typer.Option(None, help="Name of the task run's state"), state_type: List[StateType] = typer.Option(None, help="Type of the task run's state"))
```

View recent task runs

### `logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/task_run.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logs(id: UUID, head: bool = typer.Option(False, '--head', '-h', help=f'Show the first {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of all logs.'), num_logs: int = typer.Option(LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS, '--num-logs', '-n', help=f'Number of logs to show when using the --head or --tail flag. If None, defaults to {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS}.', min=1), reverse: bool = typer.Option(False, '--reverse', '-r', help='Reverse the logs order to print the most recent logs first'), tail: bool = typer.Option(False, '--tail', '-t', help=f'Show the last {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of all logs.'))
```

View logs for a task run.


# variable
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-variable



# `prefect.cli.variable`

## Functions

### `list_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/variable.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
list_variables(limit: int = typer.Option(100, '--limit', help='The maximum number of variables to return.'))
```

List variables.

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/variable.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(name: str, output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

View details about a variable.

**Args:**

* `name`: the name of the variable to inspect

### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/variable.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(name: str)
```

Get a variable's value.

**Args:**

* `name`: the name of the variable to get

### `parse_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/variable.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_value(value: str) -> Union[str, int, float, bool, None, Dict[str, Any], List[str]]
```

### `unset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/variable.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unset(name: str)
```

Unset a variable.

**Args:**

* `name`: the name of the variable to unset


# work_pool
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-work_pool



# `prefect.cli.work_pool`

Command line interface for working with work queues.

## Functions

### `set_work_pool_as_default` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_work_pool_as_default(name: str) -> None
```

### `has_provisioner_for_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
has_provisioner_for_type(work_pool_type: str) -> bool
```

Check if there is a provisioner for the given work pool type.

**Args:**

* `work_pool_type`: The type of the work pool.

**Returns:**

* True if a provisioner exists for the given type, False otherwise.

### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(name: str = typer.Argument(..., help='The name of the work pool.'), base_job_template: typer.FileText = typer.Option(None, '--base-job-template', help='The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type.'), paused: bool = typer.Option(False, '--paused', help='Whether or not to create the work pool in a paused state.'), type: str = typer.Option(None, '-t', '--type', help='The type of work pool to create.'), set_as_default: bool = typer.Option(False, '--set-as-default', help='Whether or not to use the created work pool as the local default for deployment.'), provision_infrastructure: bool = typer.Option(False, '--provision-infrastructure', '--provision-infra', help='Whether or not to provision infrastructure for the work pool if supported for the given work pool type.'), overwrite: bool = typer.Option(False, '--overwrite', help='Whether or not to overwrite an existing work pool with the same name.'))
```

Create a new work pool or update an existing one.


Examples:

Create a Kubernetes work pool in a paused state:

$prefect work-pool create "my-pool" --type kubernetes --paused
    
    Create a Docker work pool with a custom base job template:
        
       $ prefect work-pool create "my-pool" --type docker --base-job-template ./base-job-template.json

Update an existing work pool:

\$ prefect work-pool create "existing-pool" --base-job-template ./base-job-template.json --overwrite

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L269" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(verbose: bool = typer.Option(False, '--verbose', '-v', help='Show additional information about work pools.'))
```

List work pools.


Examples:
\$ prefect work-pool ls

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(name: str = typer.Argument(..., help='The name of the work pool to inspect.'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

Inspect a work pool.


Examples:
$prefect work-pool inspect "my-pool"
   $ prefect work-pool inspect "my-pool" --output json

### `pause` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L357" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause(name: str = typer.Argument(..., help='The name of the work pool to pause.'))
```

Pause a work pool.


Examples:
\$ prefect work-pool pause "my-pool"

### `resume` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume(name: str = typer.Argument(..., help='The name of the work pool to resume.'))
```

Resume a work pool.


Examples:
\$ prefect work-pool resume "my-pool"

### `update` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update(name: str = typer.Argument(..., help='The name of the work pool to update.'), base_job_template: typer.FileText = typer.Option(None, '--base-job-template', help='The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. If None, the base job template will not be modified.'), concurrency_limit: int = typer.Option(None, '--concurrency-limit', help='The concurrency limit for the work pool. If None, the concurrency limit will not be modified.'), description: str = typer.Option(None, '--description', help='The description for the work pool. If None, the description will not be modified.'))
```

Update a work pool.


Examples:
\$ prefect work-pool update "my-pool"

### `provision_infrastructure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L466" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision_infrastructure(name: str = typer.Argument(..., help='The name of the work pool to provision infrastructure for.'))
```

Provision infrastructure for a work pool.


Examples:
\$ prefect work-pool provision-infrastructure "my-pool"

\$ prefect work-pool provision-infra "my-pool"

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L526" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(name: str = typer.Argument(..., help='The name of the work pool to delete.'))
```

Delete a work pool.


Examples:
\$ prefect work-pool delete "my-pool"

### `set_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L555" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_concurrency_limit(name: str = typer.Argument(..., help='The name of the work pool to update.'), concurrency_limit: int = typer.Argument(..., help='The new concurrency limit for the work pool.'))
```

Set the concurrency limit for a work pool.


Examples:
\$ prefect work-pool set-concurrency-limit "my-pool" 10

### `clear_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L586" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_concurrency_limit(name: str = typer.Argument(..., help='The name of the work pool to update.'))
```

Clear the concurrency limit for a work pool.


Examples:
\$ prefect work-pool clear-concurrency-limit "my-pool"

### `get_default_base_job_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L612" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_default_base_job_template(type: str = typer.Option(None, '-t', '--type', help='The type of work pool for which to get the default base job template.'), file: str = typer.Option(None, '-f', '--file', help='If set, write the output to a file.'))
```

Get the default base job template for a given work pool type.


Examples:
\$ prefect work-pool get-default-base-job-template --type kubernetes

### `preview` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L648" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
preview(name: str = typer.Argument(None, help='The name or ID of the work pool to preview'), hours: int = typer.Option(None, '-h', '--hours', help='The number of hours to look ahead; defaults to 1 hour'))
```

Preview the work pool's scheduled work for all queues.


Examples:
\$ prefect work-pool preview "my-pool" --hours 24

### `storage_inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L745" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
storage_inspect(work_pool_name: Annotated[str, typer.Argument(..., help='The name of the work pool to display storage configuration for.')], output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

EXPERIMENTAL: Inspect the storage configuration for a work pool.

**Examples:**

$prefect work-pool storage inspect "my-pool"$ prefect work-pool storage inspect "my-pool" --output json

### `s3` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L884" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
s3(work_pool_name: str = typer.Argument(..., help='The name of the work pool to configure storage for.', show_default=False), bucket: str = typer.Option(..., '--bucket', help='The name of the S3 bucket to use.', show_default=False, prompt='Enter the name of the S3 bucket to use'), credentials_block_name: str = typer.Option(..., '--aws-credentials-block-name', help='The name of the AWS credentials block to use.', show_default=False, prompt='Enter the name of the AWS credentials block to use'))
```

EXPERIMENTAL: Configure AWS S3 storage for a work pool.


Examples:
\$ prefect work-pool storage configure s3 "my-pool" --bucket my-bucket --aws-credentials-block-name my-credentials

### `gcs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L970" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
gcs(work_pool_name: str = typer.Argument(..., help='The name of the work pool to configure storage for.', show_default=False), bucket: str = typer.Option(..., '--bucket', help='The name of the Google Cloud Storage bucket to use.', show_default=False, prompt='Enter the name of the Google Cloud Storage bucket to use'), credentials_block_name: str = typer.Option(..., '--gcp-credentials-block-name', help='The name of the Google Cloud credentials block to use.', show_default=False, prompt='Enter the name of the Google Cloud credentials block to use'))
```

EXPERIMENTAL: Configure Google Cloud storage for a work pool.


Examples:
\$ prefect work-pool storage configure gcs "my-pool" --bucket my-bucket --gcp-credentials-block-name my-credentials

### `azure_blob_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_pool.py#L1055" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
azure_blob_storage(work_pool_name: str = typer.Argument(..., help='The name of the work pool to configure storage for.', show_default=False), container: str = typer.Option(..., '--container', help='The name of the Azure Blob Storage container to use.', show_default=False, prompt='Enter the name of the Azure Blob Storage container to use'), credentials_block_name: str = typer.Option(..., '--azure-blob-storage-credentials-block-name', help='The name of the Azure Blob Storage credentials block to use.', show_default=False, prompt='Enter the name of the Azure Blob Storage credentials block to use'))
```

EXPERIMENTAL: Configure Azure Blob Storage for a work pool.


Examples:
\$ prefect work-pool storage configure azure-blob-storage "my-pool" --container my-container --azure-blob-storage-credentials-block-name my-credentials


# work_queue
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-work_queue



# `prefect.cli.work_queue`

Command line interface for working with work queues.

## Functions

### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(name: str = typer.Argument(..., help='The unique name to assign this work queue'), limit: int = typer.Option(None, '-l', '--limit', help='The concurrency limit to set on the queue.'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool to create the work queue in.'), priority: Optional[int] = typer.Option(None, '-q', '--priority', help='The associated priority for the created work queue'))
```

Create a work queue.

### `set_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_concurrency_limit(name: str = typer.Argument(..., help='The name or ID of the work queue'), limit: int = typer.Argument(..., help='The concurrency limit to set on the queue.'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool that the work queue belongs to.'))
```

Set a concurrency limit on a work queue.

### `clear_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_concurrency_limit(name: str = typer.Argument(..., help='The name or ID of the work queue to clear'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool that the work queue belongs to.'))
```

Clear any concurrency limits from a work queue.

### `pause` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause(name: str = typer.Argument(..., help='The name or ID of the work queue to pause'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool that the work queue belongs to.'))
```

Pause a work queue.

### `resume` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L255" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume(name: str = typer.Argument(..., help='The name or ID of the work queue to resume'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool that the work queue belongs to.'))
```

Resume a paused work queue.

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(name: str = typer.Argument(None, help='The name or ID of the work queue to inspect'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool that the work queue belongs to.'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json'))
```

Inspect a work queue by ID.

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls(verbose: bool = typer.Option(False, '--verbose', '-v', help='Display more information.'), work_queue_prefix: str = typer.Option(None, '--match', '-m', help='Will match work queues with names that start with the specified prefix string'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool containing the work queues to list.'))
```

View all work queues.

### `preview` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L466" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
preview(name: str = typer.Argument(None, help='The name or ID of the work queue to preview'), hours: int = typer.Option(None, '-h', '--hours', help='The number of hours to look ahead; defaults to 1 hour'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool that the work queue belongs to.'))
```

Preview a work queue.

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L554" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(name: str = typer.Argument(..., help='The name or ID of the work queue to delete'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool containing the work queue to delete.'))
```

Delete a work queue by ID.

### `read_wq_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/work_queue.py#L595" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_wq_runs(name: str = typer.Argument(..., help='The name or ID of the work queue to poll'), pool: Optional[str] = typer.Option(None, '-p', '--pool', help='The name of the work pool containing the work queue to poll.'))
```

Get runs in a work queue. Note that this will trigger an artificial poll of
the work queue.


# worker
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-cli-worker



# `prefect.cli.worker`

## Functions

### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/worker.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(worker_name: str = typer.Option(None, '-n', '--name', help='The name to give to the started worker. If not provided, a unique name will be generated.'), work_pool_name: str = typer.Option(..., '-p', '--pool', help='The work pool the started worker should poll.', prompt=True), work_queues: List[str] = typer.Option(None, '-q', '--work-queue', help='One or more work queue names for the worker to pull from. If not provided, the worker will pull from all work queues in the work pool.'), worker_type: Optional[str] = typer.Option(None, '-t', '--type', help='The type of worker to start. If not provided, the worker type will be inferred from the work pool.'), prefetch_seconds: int = SettingsOption(PREFECT_WORKER_PREFETCH_SECONDS, help='Number of seconds to look into the future for scheduled flow runs.'), run_once: bool = typer.Option(False, help='Only run worker polling once. By default, the worker runs forever.'), limit: int = typer.Option(None, '-l', '--limit', help='Maximum number of flow runs to start simultaneously.'), with_healthcheck: bool = typer.Option(False, help='Start a healthcheck server for the worker.'), install_policy: InstallPolicy = typer.Option(InstallPolicy.PROMPT.value, '--install-policy', help='Install policy to use workers from Prefect integration packages.', case_sensitive=False), base_job_template: typer.FileText = typer.Option(None, '--base-job-template', help='The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. If the work pool already exists, this will be ignored.'))
```

Start a worker process to poll a work pool for flow runs.

## Classes

### `InstallPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/cli/worker.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-__init__



# `prefect.client`

Asynchronous client implementation for communicating with the [Prefect REST API](https://docs.prefect.io/v3/api-ref/rest-api/).

Explore the client by communicating with an in-memory webserver - no setup required:

\<div class="termy">

```
$ # start python REPL with native await functionality
$ python -m asyncio
from prefect.client.orchestration import get_client
async with get_client() as client:
    response = await client.hello()
    print(response.json())
👋
```

\</div>


# base
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-base



# `prefect.client.base`

## Functions

### `app_lifespan_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
app_lifespan_context(app: ASGIApp) -> AsyncGenerator[None, None]
```

A context manager that calls startup/shutdown hooks for the given application.

Lifespan contexts are cached per application to avoid calling the lifespan hooks
more than once if the context is entered in nested code. A no-op context will be
returned if the context for the given application is already being managed.

This manager is robust to concurrent access within the event loop. For example,
if you have concurrent contexts for the same application, it is guaranteed that
startup hooks will be called before their context starts and shutdown hooks will
only be called after their context exits.

A reference count is used to support nested use of clients without running
lifespan hooks excessively. The first client context entered will create and enter
a lifespan context. Each subsequent client will increment a reference count but will
not create a new lifespan context. When each client context exits, the reference
count is decremented. When the last client context exits, the lifespan will be
closed.

In simple nested cases, the first client context will be the one to exit the
lifespan. However, if client contexts are entered concurrently they may not exit
in a consistent order. If the first client context was responsible for closing
the lifespan, it would have to wait until all other client contexts to exit to
avoid firing shutdown hooks while the application is in use. Waiting for the other
clients to exit can introduce deadlocks, so, instead, the first client will exit
without closing the lifespan context and reference counts will be used to ensure
the lifespan is closed once all of the clients are done.

### `determine_server_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L672" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
determine_server_type() -> ServerType
```

Determine the server type based on the current settings.

**Returns:**

* * `ServerType.EPHEMERAL` if the ephemeral server is enabled
* * `ServerType.SERVER` if a API URL is configured and it is not a cloud URL
* * `ServerType.CLOUD` if an API URL is configured and it is a cloud URL
* * `ServerType.UNCONFIGURED` if no API URL is configured and ephemeral mode is
    not enabled

## Classes

### `ASGIApp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `PrefectResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect wrapper for the `httpx.Response` class.

Provides more informative error messages.

**Methods:**

#### `from_httpx_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_httpx_response(cls: type[Self], response: httpx.Response) -> Response
```

Create a `PrefectResponse` from an `httpx.Response`.

By changing the `__class__` attribute of the Response, we change the method
resolution order to look for methods defined in PrefectResponse, while leaving
everything else about the original Response instance intact.

#### `raise_for_status` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_for_status(self) -> Response
```

Raise an exception if the response contains an HTTPStatusError.

The `PrefectHTTPStatusError` contains useful additional information that
is not contained in the `HTTPStatusError`.

### `PrefectHttpxAsyncClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect wrapper for the async httpx client with support for retry-after headers
for the provided status codes (typically 429, 502 and 503).

Additionally, this client will always call `raise_for_status` on responses.

For more details on rate limit headers, see:
[Configuring Cloudflare Rate Limiting](https://support.cloudflare.com/hc/en-us/articles/115001635128-Configuring-Rate-Limiting-from-UI)

**Methods:**

#### `send` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
send(self, request: Request, *args: Any, **kwargs: Any) -> Response
```

Send a request with automatic retry behavior for the following status codes:

* 403 Forbidden, if the request failed due to CSRF protection
* 408 Request Timeout
* 429 CloudFlare-style rate limiting
* 502 Bad Gateway
* 503 Service unavailable
* Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`

### `PrefectHttpxSyncClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L422" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect wrapper for the async httpx client with support for retry-after headers
for the provided status codes (typically 429, 502 and 503).

Additionally, this client will always call `raise_for_status` on responses.

For more details on rate limit headers, see:
[Configuring Cloudflare Rate Limiting](https://support.cloudflare.com/hc/en-us/articles/115001635128-Configuring-Rate-Limiting-from-UI)

**Methods:**

#### `send` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
send(self, request: Request, *args: Any, **kwargs: Any) -> Response
```

Send a request with automatic retry behavior for the following status codes:

* 403 Forbidden, if the request failed due to CSRF protection
* 408 Request Timeout
* 429 CloudFlare-style rate limiting
* 502 Bad Gateway
* 503 Service unavailable
* Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`

### `ServerType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/base.py#L665" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`


# cloud
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-cloud



# `prefect.client.cloud`

## Functions

### `get_cloud_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_cloud_client(host: Optional[str] = None, api_key: Optional[str] = None, httpx_settings: Optional[dict[str, Any]] = None, infer_cloud_url: bool = False) -> 'CloudClient'
```

Needs a docstring.

## Classes

### `CloudUnauthorizedError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the CloudClient receives a 401 or 403 from the Cloud API.

### `CloudClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `account_base_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
account_base_url(self) -> str
```

#### `api_healthcheck` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
api_healthcheck(self) -> None
```

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

If successful, returns `None`.

#### `check_ip_allowlist_access` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_ip_allowlist_access(self) -> IPAllowlistMyAccessResponse
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, route: str, **kwargs: Any) -> Any
```

#### `read_account_ip_allowlist` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_account_ip_allowlist(self) -> IPAllowlist
```

#### `read_account_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_account_settings(self) -> dict[str, Any]
```

#### `read_current_workspace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_current_workspace(self) -> Workspace
```

#### `read_worker_metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `read_workspaces` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_workspaces(self) -> list[Workspace]
```

#### `request` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
request(self, method: str, route: str, **kwargs: Any) -> Any
```

#### `update_account_ip_allowlist` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_account_ip_allowlist(self, updated_allowlist: IPAllowlist) -> None
```

#### `update_account_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_account_settings(self, settings: dict[str, Any]) -> None
```

#### `workspace_base_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/cloud.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
workspace_base_url(self) -> str
```


# collections
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-collections



# `prefect.client.collections`

## Functions

### `get_collections_metadata_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/collections.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_collections_metadata_client(httpx_settings: Optional[Dict[str, Any]] = None) -> 'CollectionsMetadataClient'
```

Creates a client that can be used to fetch metadata for
Prefect collections.

Will return a `CloudClient` if profile is set to connect
to Prefect Cloud, otherwise will return an `OrchestrationClient`.

## Classes

### `CollectionsMetadataClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/collections.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `read_worker_metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/collections.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_worker_metadata(self) -> Dict[str, Any]
```


# constants
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-constants



# `prefect.client.constants`

*This module is empty or contains only private/internal implementations.*


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-orchestration-__init__



# `prefect.client.orchestration`

## Functions

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

```python
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:

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

To return a synchronous client, pass sync\_client=True:

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

## Classes

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

An asynchronous client for interacting with the [Prefect REST API](https://docs.prefect.io/v3/api-ref/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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L475" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L467" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
api_url(self) -> httpx.URL
```

Get the base URL for the API.

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

```python
api_version(self) -> str
```

#### `apply_slas_for_deployment` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1023" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_version(self) -> str
```

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `create_automation` <sup><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></sup>

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

Creates an automation in Prefect Cloud.

#### `create_block_document` <sup><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></sup>

```python
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` <sup><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></sup>

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

Create a block schema in the Prefect API.

#### `create_block_type` <sup><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></sup>

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

Create a block type in the Prefect API.

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L717" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1368" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

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

```python
create_deployment_schedules(self, deployment_id: UUID, schedules: list[tuple['SCHEDULE_TYPES', bool]]) -> 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.

**Raises:**

* `RequestError`: if the schedules were not created for any reason

**Returns:**

* the list of schedules created in the backend

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L537" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L945" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L814" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `create_logs` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L768" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

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

Creates a variable with the provided configuration.

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L494" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L664" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `delete_automation` <sup><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></sup>

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

#### `delete_block_document` <sup><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></sup>

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

Delete a block document.

#### `delete_block_type` <sup><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></sup>

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

Delete a block type.

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L1005" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L850" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `delete_resource_owned_automations` <sup><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></sup>

```python
delete_resource_owned_automations(self, resource_id: str) -> None
```

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

```python
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` <sup><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></sup>

```python
delete_variable_by_name(self, name: str) -> None
```

Deletes a variable by name.

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L737" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L971" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `find_automation` <sup><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></sup>

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

#### `get_most_recent_block_schema_for_block_type` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L609" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L559" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L488" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hello(self) -> httpx.Response
```

Send a GET request to /hello for testing purposes.

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L718" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L641" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1027" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
loop(self) -> asyncio.AbstractEventLoop | None
```

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

```python
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` <sup><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></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1030" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_for_api_version_mismatch(self) -> None
```

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

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

#### `read_automation` <sup><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></sup>

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

#### `read_automations` <sup><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></sup>

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

#### `read_automations_by_name` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

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

Look up a block schema checksum

#### `read_block_schemas` <sup><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></sup>

```python
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` <sup><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></sup>

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

Read a block type by its slug.

#### `read_block_types` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L515" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L972" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1007" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L1048" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

**Returns:**

* a list of Deployment model representations
  of the deployments

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L325" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L705" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L989" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L916" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L757" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

**Returns:**

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

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

```python
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`: limit for the flow query
* `offset`: offset for the flow query

**Returns:**

* a list of Flow model representations of the flows

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

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

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

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

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

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

#### `read_logs` <sup><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></sup>

```python
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` <sup><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></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L949" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L854" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

**Returns:**

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

#### `read_variable_by_name` <sup><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></sup>

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

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

#### `read_variables` <sup><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></sup>

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

Reads all variables.

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

```python
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_pools` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L649" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L548" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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_status` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L675" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L968" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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`: Limit for the queue query.
* `offset`: Limit for the queue query.

**Returns:**

* List of queues for the specified work pool.

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

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

Reads worker metadata stored in Prefect collection registry.

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L770" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L796" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L751" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L728" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L863" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L934" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L761" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `update_automation` <sup><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></sup>

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

Updates an automation in Prefect Cloud.

#### `update_block_document` <sup><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></sup>

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

Update a block document in the Prefect API.

#### `update_block_type` <sup><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></sup>

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

Update a block document in the Prefect API.

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

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

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

```python
update_deployment_schedule(self, deployment_id: UUID, schedule_id: UUID, active: bool | None = None, schedule: 'SCHEDULE_TYPES | 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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L1020" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

Updates the labels of a flow run.

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

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

#### `update_variable` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L512" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L583" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_concurrency_limits/client.py#L882" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
upsert_global_concurrency_limit_by_name(self, name: str, limit: int) -> 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 if it is different.

Note: This is not done atomically.

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

A synchronous client for interacting with the [Prefect REST API](https://docs.prefect.io/v3/api-ref/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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
api_url(self) -> httpx.URL
```

Get the base URL for the API.

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

```python
api_version(self) -> str
```

#### `apply_slas_for_deployment` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1379" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_version(self) -> str
```

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `create_automation` <sup><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></sup>

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

Creates an automation in Prefect Cloud.

#### `create_block_document` <sup><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></sup>

```python
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` <sup><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></sup>

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

Create a block schema in the Prefect API.

#### `create_block_type` <sup><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></sup>

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

Create a block type in the Prefect API.

#### `create_concurrency_limit` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L693" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

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

```python
create_deployment_schedules(self, deployment_id: UUID, schedules: list[tuple['SCHEDULE_TYPES', bool]]) -> 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.

**Raises:**

* `RequestError`: if the schedules were not created for any reason

**Returns:**

* the list of schedules created in the backend

#### `create_flow` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L614" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L447" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

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

#### `create_logs` <sup><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></sup>

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

Create logs for a flow or task run

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

```python
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` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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.

#### `decrement_v1_concurrency_slots` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_artifacts/client.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

#### `delete_automation` <sup><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></sup>

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

#### `delete_block_document` <sup><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></sup>

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

Delete a block document.

#### `delete_block_type` <sup><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></sup>

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

Delete a block type.

#### `delete_concurrency_limit_by_tag` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L565" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L505" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

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

#### `delete_resource_owned_automations` <sup><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></sup>

```python
delete_resource_owned_automations(self, resource_id: str) -> None
```

#### `delete_variable_by_name` <sup><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></sup>

```python
delete_variable_by_name(self, name: str) -> None
```

Deletes a variable by name.

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

```python
delete_work_pool(self, work_pool_name: str) -> None
```

Deletes a work pool.

**Args:**

* `work_pool_name`: Name of the work pool to delete.

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

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

#### `find_automation` <sup><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></sup>

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

#### `get_most_recent_block_schema_for_block_type` <sup><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></sup>

```python
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_scheduled_flow_runs_for_deployments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L592" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hello(self) -> httpx.Response
```

Send a GET request to /hello for testing purposes.

#### `increment_concurrency_slots` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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.

#### `pause_automation` <sup><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></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_for_api_version_mismatch(self) -> None
```

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

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

#### `read_automation` <sup><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></sup>

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

#### `read_automations` <sup><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></sup>

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

#### `read_automations_by_name` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

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

Look up a block schema checksum

#### `read_block_schemas` <sup><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></sup>

```python
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` <sup><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></sup>

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

Read a block type by its slug.

#### `read_block_types` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

**Returns:**

* a list of Deployment model representations
  of the deployments

#### `read_flow` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flows/client.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L489" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

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

**Returns:**

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

#### `read_flows` <sup><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></sup>

```python
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`: limit for the flow query
* `offset`: offset for the flow query

**Returns:**

* a list of Flow model representations of the flows

#### `read_global_concurrency_limit_by_name` <sup><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></sup>

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

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

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

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

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

#### `read_logs` <sup><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></sup>

```python
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` <sup><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></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1590" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1513" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

**Returns:**

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

#### `read_variable_by_name` <sup><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></sup>

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

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

#### `read_variables` <sup><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></sup>

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

Reads all variables.

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

```python
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_pools` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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_workers_for_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

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

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

```python
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` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_deployments/client.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

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

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/__init__.py#L1412" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

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

```python
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` <sup><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></sup>

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

#### `update_automation` <sup><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></sup>

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

Updates an automation in Prefect Cloud.

#### `update_block_document` <sup><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></sup>

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

Update a block document in the Prefect API.

#### `update_block_type` <sup><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></sup>

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

Update a block document in the Prefect API.

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

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

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

```python
update_deployment_schedule(self, deployment_id: UUID, schedule_id: UUID, active: bool | None = None, schedule: 'SCHEDULE_TYPES | 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

#### `update_flow_run` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_flow_runs/client.py#L520" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

Updates the labels of a flow run.

#### `update_global_concurrency_limit` <sup><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></sup>

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

#### `update_variable` <sup><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></sup>

```python
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` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/_work_pools/client.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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.

#### `upsert_global_concurrency_limit_by_name` <sup><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></sup>

```python
upsert_global_concurrency_limit_by_name(self, name: str, limit: int) -> 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 if it is different.

Note: This is not done atomically.


# base
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-orchestration-base



# `prefect.client.orchestration.base`

## Classes

### `BaseClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/base.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `request` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/base.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
request(self, method: HTTP_METHODS, path: 'ServerRoutes', params: dict[str, Any] | None = None, path_params: dict[str, Any] | None = None, **kwargs: Any) -> 'Response'
```

### `BaseAsyncClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/base.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `request` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/base.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
request(self, method: HTTP_METHODS, path: 'ServerRoutes', params: dict[str, Any] | None = None, path_params: dict[str, Any] | None = None, **kwargs: Any) -> 'Response'
```


# routes
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-orchestration-routes



# `prefect.client.orchestration.routes`

*This module is empty or contains only private/internal implementations.*


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-schemas-__init__



# `prefect.client.schemas`

*This module is empty or contains only private/internal implementations.*


# actions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-schemas-actions



# `prefect.client.schemas.actions`

## Classes

### `StateCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a new state.

### `FlowCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a flow.

### `FlowUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a flow.

### `DeploymentScheduleCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `from_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_schedule(cls, schedule: Schedule) -> 'DeploymentScheduleCreate'
```

#### `validate_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_active(cls, v: Any, handler: Callable[[Any], Any]) -> bool
```

#### `validate_max_scheduled_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_max_scheduled_runs(cls, v: Optional[int]) -> Optional[int]
```

### `DeploymentScheduleUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `validate_max_scheduled_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_max_scheduled_runs(cls, v: Optional[int]) -> Optional[int]
```

### `DeploymentCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a deployment.

**Methods:**

#### `check_valid_configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L279" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_valid_configuration(self, base_job_template: dict[str, Any]) -> None
```

Check that the combination of base\_job\_template defaults
and job\_variables conforms to the specified schema.

#### `convert_to_strings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
convert_to_strings(cls, values: Optional[Union[str, list[str]]]) -> Union[str, list[str]]
```

#### `remove_old_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_old_fields(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `DeploymentUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L299" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a deployment.

**Methods:**

#### `check_valid_configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_valid_configuration(self, base_job_template: dict[str, Any]) -> None
```

Check that the combination of base\_job\_template defaults
and job\_variables conforms to the specified schema.

#### `remove_old_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L304" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_old_fields(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `DeploymentBranch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L376" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `validate_branch_length` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L389" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_branch_length(cls, v: str) -> str
```

### `FlowRunUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a flow run.

### `TaskRunCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a task run

### `TaskRunUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L454" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a task run

### `FlowRunCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L460" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a flow run.

### `DeploymentFlowRunCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L492" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a flow run from a deployment.

**Methods:**

#### `convert_parameters_to_plain_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L523" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
convert_parameters_to_plain_data(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `SavedSearchCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L537" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a saved search.

### `ConcurrencyLimitCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L546" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a concurrency limit.

### `ConcurrencyLimitV2Create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L555" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a v2 concurrency limit.

### `ConcurrencyLimitV2Update` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L575" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a v2 concurrency limit.

### `BlockTypeCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L586" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a block type.

### `BlockTypeUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L607" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a block type.

**Methods:**

#### `updatable_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L616" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
updatable_fields(cls) -> set[str]
```

### `BlockSchemaCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L620" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a block schema.

### `BlockDocumentCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L637" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a block document.

**Methods:**

#### `validate_name_is_present_if_not_anonymous` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L661" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_name_is_present_if_not_anonymous(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `BlockDocumentUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L667" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a block document.

### `BlockDocumentReferenceCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used to create block document reference.

### `LogCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L697" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a log.

**Methods:**

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L708" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]
```

The worker\_id field is only included in logs sent to Prefect Cloud.
If it's unset, we should not include it in the log payload.

### `WorkPoolCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L719" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a work pool.

### `WorkPoolUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L746" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a work pool.

### `WorkQueueCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L759" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a work queue.

### `WorkQueueUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L788" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a work queue.

### `ArtifactCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L811" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create an artifact.

### `ArtifactUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L823" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update an artifact.

### `VariableCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L831" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a Variable.

### `VariableUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L843" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a Variable.

### `GlobalConcurrencyLimitCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L855" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a global concurrency limit.

### `GlobalConcurrencyLimitUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/actions.py#L882" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a global concurrency limit.


# filters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-schemas-filters



# `prefect.client.schemas.filters`

Schemas that define Prefect REST API filtering operations.

## Classes

### `Operator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Operators for combining filter criteria.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `OperatorMixin` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base model for Prefect filters that combines criteria with a user-provided operator

### `FlowFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Flow.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Flow.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Flow.tags`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter for flows. Only flows matching all criteria will be returned.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by FlowRun.id.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.tags`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterDeploymentId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.deployment_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterWorkQueueName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.work_queue_name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterStateType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.state_type`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterStateName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterFlowVersion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.flow_version`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.start_time`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterExpectedStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.expected_start_time`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterNextScheduledStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.next_scheduled_start_time`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterParentFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter for subflows of the given flow runs

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterParentTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.parent_task_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilterIdempotencyKey` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by FlowRun.idempotency\_key.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L284" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter flow runs. Only flow runs matching all criteria will be returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.flow_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L342" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.tags`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterStateType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.state_type`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterStateName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L394" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterSubFlowRuns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L405" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.subflow_run`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilterStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L417" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.start_time`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter task runs. Only task runs matching all criteria will be returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DeploymentFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L459" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DeploymentFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L470" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DeploymentFilterWorkQueueName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.work_queue_name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DeploymentFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L500" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.tags`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DeploymentFilterConcurrencyLimit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L521" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

DEPRECATED: Prefer `Deployment.concurrency_limit_id` over `Deployment.concurrency_limit`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DeploymentFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L538" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter for deployments. Only deployments matching all criteria will be returned.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `LogFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L560" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `LogFilterLevel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L570" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.level`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `LogFilterTimestamp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L586" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.timestamp`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `LogFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L599" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.flow_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `LogFilterTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L607" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.task_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `LogFilterTextSearch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L615" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by text search across log content.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `LogFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter logs. Only logs matching all criteria will be returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FilterSet` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L650" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A collection of filters for common objects

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockTypeFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L668" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockType.name`

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockTypeFilterSlug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockType.slug`

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockTypeFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L690" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter BlockTypes

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockSchemaFilterBlockTypeId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L702" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockSchema.block_type_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockSchemaFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L710" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by BlockSchema.id

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockSchemaFilterCapabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L718" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockSchema.capabilities`

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockSchemaFilterVersion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L731" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockSchema.capabilities`

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockSchemaFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L741" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter BlockSchemas

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockDocumentFilterIsAnonymous` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L758" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.is_anonymous`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockDocumentFilterBlockTypeId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L769" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.block_type_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockDocumentFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L777" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockDocumentFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L785" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockDocumentFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L801" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkQueueFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L823" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkQueue.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkQueueFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L832" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkQueue.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkQueueFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L852" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter work queues. Only work queues matching all criteria will be
returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkPoolFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L865" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkPool.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkPoolFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L873" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkPool.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkPoolFilterType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L881" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkPool.type`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkPoolFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L889" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkerFilterWorkPoolId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L901" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Worker.worker_config_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkerFilterLastHeartbeatTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L909" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Worker.last_heartbeat_time`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkerFilterStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L926" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Worker.status`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkerFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L937" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L951" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactFilterKey` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L959" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.key`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L984" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.flow_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactFilterTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L992" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.task_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactFilterType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1000" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.type`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1011" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter artifacts. Only artifacts matching all criteria will be returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactCollectionFilterLatestId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1031" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.latest_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactCollectionFilterKey` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1039" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.key`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactCollectionFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1065" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.flow_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactCollectionFilterTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1073" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.task_run_id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactCollectionFilterType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1081" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.type`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ArtifactCollectionFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1092" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter artifact collections. Only artifact collections matching all criteria will be returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `VariableFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Variable.id`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `VariableFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Variable.name`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `VariableFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Variable.tags`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `VariableFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/filters.py#L1152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter variables. Only variables matching all criteria will be returned

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# objects
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-schemas-objects



# `prefect.client.schemas.objects`

## Functions

### `data_discriminator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
data_discriminator(x: Any) -> str
```

## Classes

### `RunType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `StateType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of state types.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `WorkPoolStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of work pool statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

#### `display_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
display_name(self) -> str
```

### `WorkerStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of worker statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `DeploymentStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of deployment statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `WorkQueueStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of work queue statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `ConcurrencyLimitStrategy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of concurrency limit strategies.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `ConcurrencyOptions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Class for storing the concurrency config in database.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ConcurrencyLimitConfig` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Class for storing the concurrency limit config in database.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ConcurrencyLeaseHolder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Model for validating concurrency lease holder information.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `to_run_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_run_result(self, run_type: RunType) -> Optional[Union[FlowRunResult, TaskRunResult]]
```

### `State` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The state of a run.

**Methods:**

#### `aresult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aresult(self: 'State[R]', raise_on_failure: Literal[True] = ..., retry_result_failure: bool = ...) -> R
```

#### `aresult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aresult(self: 'State[R]', raise_on_failure: Literal[False] = False, retry_result_failure: bool = ...) -> Union[R, Exception]
```

#### `aresult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aresult(self: 'State[R]', raise_on_failure: bool = ..., retry_result_failure: bool = ...) -> Union[R, Exception]
```

#### `aresult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aresult(self, raise_on_failure: bool = True, retry_result_failure: bool = True) -> Union[R, Exception]
```

Retrieve the result attached to this state.

#### `default_name_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_name_from_type(self) -> Self
```

If a name is not provided, use the type

#### `default_scheduled_start_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L394" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_scheduled_start_time(self) -> Self
```

#### `fresh_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fresh_copy(self, **kwargs: Any) -> Self
```

Return a fresh copy of the state with a new ID.

#### `is_cancelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_cancelled(self) -> bool
```

#### `is_cancelling` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L427" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_cancelling(self) -> bool
```

#### `is_completed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L415" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_completed(self) -> bool
```

#### `is_crashed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L421" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_crashed(self) -> bool
```

#### `is_failed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_failed(self) -> bool
```

#### `is_final` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L430" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_final(self) -> bool
```

#### `is_paused` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_paused(self) -> bool
```

#### `is_pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_pending(self) -> bool
```

#### `is_running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L412" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_running(self) -> bool
```

#### `is_scheduled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_scheduled(self) -> bool
```

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self) -> Self
```

Copying API models should return an object that could be inserted into the
database again. The 'timestamp' is reset using the default factory.

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self: 'State[R]', raise_on_failure: Literal[True] = ..., retry_result_failure: bool = ...) -> R
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self: 'State[R]', raise_on_failure: Literal[False] = False, retry_result_failure: bool = ...) -> Union[R, Exception]
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self: 'State[R]', raise_on_failure: bool = ..., retry_result_failure: bool = ...) -> Union[R, Exception]
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L295" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: bool = True, retry_result_failure: bool = True) -> Union[R, Exception]
```

Retrieve the result attached to this state.

**Args:**

* `raise_on_failure`: a boolean specifying whether to raise an exception
  if the state is of type `FAILED` and the underlying data is an exception. When flow
  was run in a different memory space (using `run_deployment`), this will only raise
  if `fetch` is `True`.
* `retry_result_failure`: a boolean specifying whether to retry on failures to
  load the result from result storage

**Raises:**

* `TypeError`: If the state is failed but the result is not an exception.

**Returns:**

* The result of the run

**Examples:**

Get the result from a flow state

```python
@flow
def my_flow():
    return "hello"
my_flow(return_state=True).result()
# hello
```

Get the result from a failed state

```python
@flow
def my_flow():
    raise ValueError("oh no!")
state = my_flow(return_state=True)  # Error is wrapped in FAILED state
state.result()  # Raises `ValueError`
```

Get the result from a failed state without erroring

```python
@flow
def my_flow():
    raise ValueError("oh no!")
state = my_flow(return_state=True)
result = state.result(raise_on_failure=False)
print(result)
# ValueError("oh no!")
```

Get the result from a flow state in an async context

```python
@flow
async def my_flow():
    return "hello"
state = await my_flow(return_state=True)
await state.result()
# hello
```

Get the result with `raise_on_failure` from a flow run in a different memory space

```python
@flow
async def my_flow():
    raise ValueError("oh no!")
my_flow.deploy("my_deployment/my_flow")
flow_run = run_deployment("my_deployment/my_flow")
await flow_run.state.result(raise_on_failure=True) # Raises `ValueError("oh no!")`
```

#### `set_unpersisted_results_to_none` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L401" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_unpersisted_results_to_none(self) -> Self
```

### `FlowRunPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L510" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines of how a flow run should be orchestrated.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `populate_deprecated_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L545" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
populate_deprecated_fields(cls, values: Any) -> Any
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L551" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `set_default_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L709" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_default_name(cls, name: Optional[str]) -> str
```

### `TaskRunPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L713" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines of how a task run should retry.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `populate_deprecated_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L742" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
populate_deprecated_fields(self)
```

If deprecated fields are provided, populate the corresponding new fields
to preserve orchestration behavior.

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `validate_configured_retry_delays` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L762" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_configured_retry_delays(cls, v: Optional[int | float | list[int] | list[float]]) -> Optional[int | float | list[int] | list[float]]
```

#### `validate_jitter_factor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L769" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_jitter_factor(cls, v: Optional[float]) -> Optional[float]
```

### `RunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L773" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for classes that represent inputs to task runs, which
could include, constants, parameters, or other task runs.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L786" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a task run result input to another task run.

### `FlowRunResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L793" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Parameter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L798" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a parameter input to a task run.

### `Constant` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L805" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents constant input value to a task run.

### `TaskRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L812" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `set_default_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L922" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_default_name(cls, name: Optional[str]) -> Name
```

### `Workspace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L926" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect Cloud workspace.

Expected payload for each workspace returned by the `me/workspaces` route.

**Methods:**

#### `api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L949" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
api_url(self) -> str
```

Generate the API URL for accessing this workspace

#### `handle` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L943" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle(self) -> str
```

The full handle of the workspace as `account_handle` / `workspace_handle`

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `ui_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L959" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ui_url(self) -> str
```

Generate the UI URL for accessing this workspace

### `IPAllowlistEntry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L973" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `IPAllowlist` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L985" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect Cloud IP allowlist.

Expected payload for an IP allowlist from the Prefect Cloud API.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `IPAllowlistMyAccessResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L995" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Expected payload for an IP allowlist access response from the Prefect Cloud API.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1002" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block type

### `BlockSchema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1026" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A representation of a block schema.

### `BlockDocument` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1047" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block document.

**Methods:**

#### `serialize_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1087" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize_data(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `validate_name_is_present_if_not_anonymous` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1081" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_name_is_present_if_not_anonymous(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `Flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1098" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of flow data.

### `DeploymentSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `VersionInfo` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BranchingScheduleHandling` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `DeploymentBranchingOptions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of deployment data.

### `ConcurrencyLimit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a concurrency limit.

### `BlockSchemaReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block schema reference.

### `BlockDocumentReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block document reference.

**Methods:**

#### `validate_parent_and_ref_are_different` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_parent_and_ref_are_different(cls, values: Any) -> Any
```

### `Configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of account info.

### `SavedSearchFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A filter for a saved search model. Intended for use by the Prefect UI.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `SavedSearch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1344" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of saved search data. Represents a set of filter criteria.

### `Log` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1354" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of log data.

### `QueueFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter criteria definition for a work queue.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a work queue

### `WorkQueueHealthPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `evaluate_health_status` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
evaluate_health_status(self, late_runs_count: int, last_polled: datetime.datetime | None = None) -> bool
```

Given empirical information about the state of the work queue, evaluate its health status.

**Args:**

* `late_runs`: the count of late runs for the work queue.
* `last_polled`: the last time the work queue was polled, if available.

**Returns:**

* whether or not the work queue is healthy.

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkQueueStatusDetail` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1466" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Agent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1482" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of an agent

### `WorkPoolStorageConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1500" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A work pool storage configuration

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1515" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a work pool

**Methods:**

#### `helpful_error_for_missing_default_queue_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
helpful_error_for_missing_default_queue_id(cls, v: Optional[UUID]) -> UUID
```

#### `is_managed_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1557" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_managed_pool(self) -> bool
```

#### `is_push_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1553" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_push_pool(self) -> bool
```

### `Worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1566" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a worker

### `Artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1592" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `validate_metadata_length` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_metadata_length(cls, v: Optional[dict[str, str]]) -> Optional[dict[str, str]]
```

### `ArtifactCollection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1636" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1673" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `FlowRunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1692" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `decoded_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1701" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
decoded_value(self) -> Any
```

Decode the value of the input.

**Returns:**

* the decoded value

### `GlobalConcurrencyLimit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1711" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a global concurrency limit

### `CsrfToken` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1738" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Integration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1754" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A representation of an installed Prefect integration.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkerMetadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/objects.py#L1761" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Worker metadata.

We depend on the structure of `integrations`, but otherwise, worker classes
should support flexible metadata.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# responses
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-schemas-responses



# `prefect.client.schemas.responses`

## Classes

### `SetStateStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumerates return statuses for setting run states.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `StateAcceptDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with an ACCEPT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateRejectDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with a REJECT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateAbortDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with an ABORT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateWaitDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with a WAIT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `HistoryResponseState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a single state's history over an interval.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `HistoryResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a history of aggregation states over an interval

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `OrchestrationResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A container for the output of state orchestration.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkerFlowRunResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `DeploymentResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `as_related_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L446" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_related_resource(self, role: str = 'deployment') -> 'RelatedResource'
```

### `MinimalConcurrencyLimitResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L472" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ConcurrencyLimitWithLeaseResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L480" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `GlobalConcurrencyLimitResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/responses.py#L487" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A response object for global concurrency limits.


# schedules
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-schemas-schedules



# `prefect.client.schemas.schedules`

Schedule schemas

## Functions

### `is_valid_timezone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_valid_timezone(v: str) -> bool
```

Validate that the provided timezone is a valid IANA timezone.

Unfortunately this list is slightly different from the list of valid
timezones we use for cron and interval timezone validation.

### `is_schedule_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L333" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_schedule_type(obj: Any) -> TypeGuard[SCHEDULE_TYPES]
```

### `construct_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
construct_schedule(interval: Optional[Union[int, float, datetime.timedelta]] = None, anchor_date: Optional[Union[datetime.datetime, str]] = None, cron: Optional[str] = None, rrule: Optional[str] = None, timezone: Optional[str] = None) -> SCHEDULE_TYPES
```

Construct a schedule from the provided arguments.

**Args:**

* `interval`: An interval on which to schedule runs. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `anchor_date`: The start date for an interval schedule.
* `cron`: A cron schedule for runs.
* `rrule`: An rrule schedule of when to execute runs of this flow.
* `timezone`: A timezone to use for the schedule. Defaults to UTC.

## Classes

### `IntervalSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A schedule formed by adding `interval` increments to an `anchor_date`. If no
`anchor_date` is supplied, the current UTC time is used.  If a
timezone-naive datetime is provided for `anchor_date`, it is assumed to be
in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,
anchor dates are always stored as UTC offsets, so a `timezone` can be
provided to determine localization behaviors like DST boundary handling. If
none is provided it will be inferred from the anchor date.

NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a
DST-observing timezone, then the schedule will adjust itself appropriately.
Intervals greater than 24 hours will follow DST conventions, while intervals
of less than 24 hours will follow UTC intervals. For example, an hourly
schedule will fire every UTC hour, even across DST boundaries. When clocks
are set back, this will result in two runs that *appear* to both be
scheduled for 1am local time, even though they are an hour apart in UTC
time. For longer intervals, like a daily schedule, the interval schedule
will adjust for DST boundaries so that the clock-hour remains constant. This
means that a daily schedule that always fires at 9am will observe DST and
continue to fire at 9am in the local time zone.

**Args:**

* `interval`: an interval to schedule on
* `anchor_date`: an anchor date to schedule increments against;
  if not provided, the current timestamp will be used
* `timezone`: a valid timezone string

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `validate_timezone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_timezone(self)
```

### `CronSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Cron schedule

NOTE: If the timezone is a DST-observing one, then the schedule will adjust
itself appropriately. Cron's rules for DST are based on schedule times, not
intervals. This means that an hourly cron schedule will fire on every new
schedule hour, not every elapsed hour; for example, when clocks are set back
this will result in a two-hour pause as the schedule will fire *the first
time* 1am is reached and *the first time* 2am is reached, 120 minutes later.
Longer schedules, such as one that fires at 9am every morning, will
automatically adjust for DST.

**Args:**

* `cron`: a valid cron string
* `timezone`: a valid timezone string in IANA tzdata format (for example,
  America/New\_York).
* `day_or`: Control how croniter handles `day` and `day_of_week`
  entries. Defaults to True, matching cron which connects those values using
  OR. If the switch is set to False, the values are connected using AND. This
  behaves like fcron and enables you to e.g. define a job that executes each
  2nd friday of a month by setting the days of month and the weekday.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `valid_cron_string` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
valid_cron_string(cls, v: str) -> str
```

#### `valid_timezone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
valid_timezone(cls, v: Optional[str]) -> Optional[str]
```

### `RRuleSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

RRule schedule, based on the iCalendar standard
([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as
implemented in `dateutils.rrule`.

RRules are appropriate for any kind of calendar-date manipulation, including
irregular intervals, repetition, exclusions, week day or day-of-month
adjustments, and more.

Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to
to the initial timezone provided. A 9am daily schedule with a daylight saving
time-aware start date will maintain a local 9am time through DST boundaries;
a 9am daily schedule with a UTC start date will maintain a 9am UTC time.

**Args:**

* `rrule`: a valid RRule string
* `timezone`: a valid timezone string

**Methods:**

#### `from_rrule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_rrule(cls, rrule: Union[dateutil.rrule.rrule, dateutil.rrule.rruleset]) -> 'RRuleSchedule'
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `to_rrule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_rrule(self) -> Union[dateutil.rrule.rrule, dateutil.rrule.rruleset]
```

Since rrule doesn't properly serialize/deserialize timezones, we localize dates
here

#### `valid_timezone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L308" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
valid_timezone(cls, v: Optional[str]) -> str
```

Validate that the provided timezone is a valid IANA timezone.

Unfortunately this list is slightly different from the list of valid
timezones we use for cron and interval timezone validation.

#### `validate_rrule_str` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_rrule_str(cls, v: str) -> str
```

### `NoSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/schedules.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# sorting
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-schemas-sorting



# `prefect.client.schemas.sorting`

## Classes

### `FlowRunSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L4" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines flow run sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `TaskRunSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines task run sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `AutomationSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines automation sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `LogSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines log sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `FlowSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines flow sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `DeploymentSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines deployment sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `ArtifactSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines artifact sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `ArtifactCollectionSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines artifact collection sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `VariableSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines variables sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `BlockDocumentSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/schemas/sorting.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines block document sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`


# subscriptions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-subscriptions



# `prefect.client.subscriptions`

## Classes

### `Subscription` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/subscriptions.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `websocket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/subscriptions.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
websocket(self) -> websockets.asyncio.client.ClientConnection
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-types-__init__



# `prefect.client.types`

*This module is empty or contains only private/internal implementations.*


# flexible_schedule_list
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-types-flexible_schedule_list



# `prefect.client.types.flexible_schedule_list`

*This module is empty or contains only private/internal implementations.*


# utilities
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-client-utilities



# `prefect.client.utilities`

Utilities for working with clients.

## Functions

### `get_or_create_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/utilities.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create_client(client: Optional['PrefectClient'] = None) -> tuple['PrefectClient', bool]
```

Returns provided client, infers a client from context if available, or creates a new client.

**Args:**

* `- client`: an optional client to use

**Returns:**

* * tuple: a tuple of the client and a boolean indicating if the client was inferred from context

### `client_injector` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/utilities.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_injector(func: Callable[Concatenate['PrefectClient', P], Coroutine[Any, Any, R]]) -> Callable[P, Coroutine[Any, Any, R]]
```

### `inject_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/utilities.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inject_client(fn: Callable[P, Coroutine[Any, Any, R]]) -> Callable[P, Coroutine[Any, Any, R]]
```

Simple helper to provide a context managed client to an asynchronous function.

The decorated function *must* take a `client` kwarg and if a client is passed when
called it will be used instead of creating a new one, but it will not be context
managed as it is assumed that the caller is managing the context.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-__init__



# `prefect.concurrency`

*This module is empty or contains only private/internal implementations.*


# asyncio
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-asyncio



# `prefect.concurrency.asyncio`

## Functions

### `concurrency` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/asyncio.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
concurrency(names: Union[str, list[str]], occupy: int = 1, timeout_seconds: Optional[float] = None, max_retries: Optional[int] = None, lease_duration: float = 300, strict: bool = False, holder: 'Optional[ConcurrencyLeaseHolder]' = None) -> AsyncGenerator[None, None]
```

A
context manager that acquires and releases concurrency slots from the
given concurrency limits.

**Args:**

* `names`: The names of the concurrency limits to acquire slots from.
* `occupy`: The number of slots to acquire and hold from each limit.
* `timeout_seconds`: The number of seconds to wait for the slots to be acquired before
  raising a `TimeoutError`. A timeout of `None` will wait indefinitely.
* `max_retries`: The maximum number of retries to acquire the concurrency slots.
* `lease_duration`: The duration of the lease for the acquired slots in seconds.
* `strict`: A boolean specifying whether to raise an error if the concurrency limit does not exist.
  Defaults to `False`.
* `holder`: A dictionary containing information about the holder of the concurrency slots.
  Typically includes 'type' and 'id' keys.

**Raises:**

* `TimeoutError`: If the slots are not acquired within the given timeout.
* `ConcurrencySlotAcquisitionError`: If the concurrency limit does not exist and `strict` is `True`.

Example:
A simple example of using the async `concurrency` context manager:

```python
from prefect.concurrency.asyncio import concurrency

async def resource_heavy():
    async with concurrency("test", occupy=1):
        print("Resource heavy task")

async def main():
    await resource_heavy()
```

### `rate_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/asyncio.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rate_limit(names: Union[str, list[str]], occupy: int = 1, timeout_seconds: Optional[float] = None, strict: bool = False) -> None
```

Block execution until an `occupy` number of slots of the concurrency
limits given in `names` are acquired.

Requires that all given concurrency limits have a slot decay.

**Args:**

* `names`: The names of the concurrency limits to acquire slots from.
* `occupy`: The number of slots to acquire and hold from each limit.
* `timeout_seconds`: The number of seconds to wait for the slots to be acquired before
  raising a `TimeoutError`. A timeout of `None` will wait indefinitely.
* `strict`: A boolean specifying whether to raise an error if the concurrency limit does not exist.
  Defaults to `False`.

**Raises:**

* `TimeoutError`: If the slots are not acquired within the given timeout.
* `ConcurrencySlotAcquisitionError`: If the concurrency limit does not exist and `strict` is `True`.


# context
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-context



# `prefect.concurrency.context`

## Classes

### `ConcurrencyContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/context.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.


# services
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-services



# `prefect.concurrency.services`

## Classes

### `ConcurrencySlotAcquisitionService` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/services.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `acquire` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/services.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire(self, slots: int, mode: Literal['concurrency', 'rate_limit'], timeout_seconds: Optional[float] = None, max_retries: Optional[int] = None) -> httpx.Response
```


# sync
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-sync



# `prefect.concurrency.sync`

## Functions

### `concurrency` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/sync.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
concurrency(names: Union[str, list[str]], occupy: int = 1, timeout_seconds: Optional[float] = None, max_retries: Optional[int] = None, lease_duration: float = 300, strict: bool = False, holder: 'Optional[ConcurrencyLeaseHolder]' = None) -> Generator[None, None, None]
```

A context manager that acquires and releases concurrency slots from the
given concurrency limits.

**Args:**

* `names`: The names of the concurrency limits to acquire slots from.
* `occupy`: The number of slots to acquire and hold from each limit.
* `timeout_seconds`: The number of seconds to wait for the slots to be acquired before
  raising a `TimeoutError`. A timeout of `None` will wait indefinitely.
* `max_retries`: The maximum number of retries to acquire the concurrency slots.
* `lease_duration`: The duration of the lease for the acquired slots in seconds.
* `strict`: A boolean specifying whether to raise an error if the concurrency limit does not exist.
  Defaults to `False`.
* `holder`: A dictionary containing information about the holder of the concurrency slots.
  Typically includes 'type' and 'id' keys.

**Raises:**

* `TimeoutError`: If the slots are not acquired within the given timeout.
* `ConcurrencySlotAcquisitionError`: If the concurrency limit does not exist and `strict` is `True`.

Example:
A simple example of using the sync `concurrency` context manager:

```python
from prefect.concurrency.sync import concurrency

def resource_heavy():
    with concurrency("test", occupy=1):
        print("Resource heavy task")

def main():
    resource_heavy()
```

### `rate_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/sync.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rate_limit(names: Union[str, list[str]], occupy: int = 1, timeout_seconds: Optional[float] = None, strict: bool = False) -> None
```

Block execution until an `occupy` number of slots of the concurrency
limits given in `names` are acquired. Requires that all given concurrency
limits have a slot decay.

**Args:**

* `names`: The names of the concurrency limits to acquire slots from.
* `occupy`: The number of slots to acquire and hold from each limit.
* `timeout_seconds`: The number of seconds to wait for the slots to be acquired before
  raising a `TimeoutError`. A timeout of `None` will wait indefinitely.
* `strict`: A boolean specifying whether to raise an error if the concurrency limit does not exist.
  Defaults to `False`.

**Raises:**

* `TimeoutError`: If the slots are not acquired within the given timeout.
* `ConcurrencySlotAcquisitionError`: If the concurrency limit does not exist and `strict` is `True`.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-v1-__init__



# `prefect.concurrency.v1`

*This module is empty or contains only private/internal implementations.*


# asyncio
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-v1-asyncio



# `prefect.concurrency.v1.asyncio`

## Functions

### `concurrency` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/v1/asyncio.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
concurrency(names: Union[str, list[str]], task_run_id: UUID, timeout_seconds: Optional[float] = None) -> AsyncGenerator[None, None]
```

A context manager that acquires and releases concurrency slots from the
given concurrency limits.

**Args:**

* `names`: The names of the concurrency limits to acquire slots from.
* `task_run_id`: The name of the task\_run\_id that is incrementing the slots.
* `timeout_seconds`: The number of seconds to wait for the slots to be acquired before
  raising a `TimeoutError`. A timeout of `None` will wait indefinitely.

**Raises:**

* `TimeoutError`: If the slots are not acquired within the given timeout.

Example:
A simple example of using the async `concurrency` context manager:

```python
from prefect.concurrency.v1.asyncio import concurrency

async def resource_heavy():
    async with concurrency("test", task_run_id):
        print("Resource heavy task")

async def main():
    await resource_heavy()
```


# context
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-v1-context



# `prefect.concurrency.v1.context`

## Classes

### `ConcurrencyContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/v1/context.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.


# services
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-v1-services



# `prefect.concurrency.v1.services`

## Classes

### `ConcurrencySlotAcquisitionServiceError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/v1/services.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when an error occurs while acquiring concurrency slots.

### `ConcurrencySlotAcquisitionService` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/v1/services.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `acquire` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/v1/services.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire(self, task_run_id: UUID, timeout_seconds: Optional[float] = None) -> httpx.Response
```


# sync
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-concurrency-v1-sync



# `prefect.concurrency.v1.sync`

## Functions

### `concurrency` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/concurrency/v1/sync.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
concurrency(names: Union[str, list[str]], task_run_id: UUID, timeout_seconds: Optional[float] = None) -> Generator[None, None, None]
```

A context manager that acquires and releases concurrency slots from the
given concurrency limits.

**Args:**

* `names`: The names of the concurrency limits to acquire.
* `task_run_id`: The task run ID acquiring the limits.
* `timeout_seconds`: The number of seconds to wait to acquire the limits before
  raising a `TimeoutError`. A timeout of `None` will wait indefinitely.

**Raises:**

* `TimeoutError`: If the limits are not acquired within the given timeout.

Example:
A simple example of using the sync `concurrency` context manager:

```python
from prefect.concurrency.v1.sync import concurrency

def resource_heavy():
    with concurrency("test"):
        print("Resource heavy task")

def main():
    resource_heavy()
```


# context
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-context



# `prefect.context`

Async and thread safe models for passing runtime context data.

These contexts should never be directly mutated by the user.

For more user-accessible information about the current run, see [`prefect.runtime`](https://docs.prefect.io/v3/api-ref/python/prefect-runtime-flow_run).

## Functions

### `serialize_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize_context(asset_ctx_kwargs: Union[dict[str, Any], None] = None) -> dict[str, Any]
```

Serialize the current context for use in a remote execution environment.

Optionally provide asset\_ctx\_kwargs to create new AssetContext, that will be used
in the remote execution environment. This is useful for TaskRunners, who rely on creating the
task run in the remote environment.

### `hydrated_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hydrated_context(serialized_context: Optional[dict[str, Any]] = None, client: Union[PrefectClient, SyncPrefectClient, None] = None) -> Generator[None, Any, None]
```

### `get_run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L746" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_run_context() -> Union[FlowRunContext, TaskRunContext]
```

Get the current run context from within a task or flow function.

**Returns:**

* A `FlowRunContext` or `TaskRunContext` depending on the function type.

**Raises:**

* `RuntimeError`: If called outside of a flow or task run.

### `get_settings_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L769" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_settings_context() -> SettingsContext
```

Get the current settings context which contains profile information and the
settings that are being used.

Generally, the settings that are being used are a combination of values from the
profile and environment. See `prefect.context.use_profile` for more details.

### `tags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L786" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
tags(*new_tags: str) -> Generator[set[str], None, None]
```

Context manager to add tags to flow and task run calls.

Tags are always combined with any existing tags.

**Examples:**

```python
from prefect import tags, task, flow
@task
def my_task():
    pass
```

Run a task with tags

```python
@flow
def my_flow():
    with tags("a", "b"):
        my_task()  # has tags: a, b
```

Run a flow with tags

```python
@flow
def my_flow():
    pass
with tags("a", "b"):
    my_flow()  # has tags: a, b
```

Run a task with nested tag contexts

```python
@flow
def my_flow():
    with tags("a", "b"):
        with tags("c", "d"):
            my_task()  # has tags: a, b, c, d
        my_task()  # has tags: a, b
```

Inspect the current tags

```python
@flow
def my_flow():
    with tags("c", "d"):
        with tags("e", "f") as current_tags:
             print(current_tags)
with tags("a", "b"):
    my_flow()
# {"a", "b", "c", "d", "e", "f"}
```

### `use_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L853" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
use_profile(profile: Union[Profile, str], override_environment_variables: bool = False, include_current_context: bool = True) -> Generator[SettingsContext, Any, None]
```

Switch to a profile for the duration of this context.

Profile contexts are confined to an async context in a single thread.

**Args:**

* `profile`: The name of the profile to load or an instance of a Profile.
* `override_environment_variable`: If set, variables in the profile will take
  precedence over current environment variables. By default, environment
  variables will override profile settings.
* `include_current_context`: If set, the new settings will be constructed
  with the current settings context as a base. If not set, the use\_base settings
  will be loaded from the environment and defaults.

### `root_settings_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L905" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
root_settings_context() -> SettingsContext
```

Return the settings context that will exist as the root context for the module.

The profile to use is determined with the following precedence

* Command line via 'prefect --profile \<name>'
* Environment variable via 'PREFECT\_PROFILE'
* Profiles file via the 'active' key

## Classes

### `ContextModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base model for context data that forbids mutation and extra data while providing
a context manager

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.

### `SyncClientContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A context for managing the sync Prefect client instances.

Clients were formerly tracked on the TaskRunContext and FlowRunContext, but
having two separate places and the addition of both sync and async clients
made it difficult to manage. This context is intended to be the single
source for sync clients.

The client creates a sync client, which can either be read directly from
the context object OR loaded with get\_client, inject\_client, or other
Prefect utilities.

with SyncClientContext.get\_or\_create() as ctx:
c1 = get\_client(sync\_client=True)
c2 = get\_client(sync\_client=True)
assert c1 is c2
assert c1 is ctx.client

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls) -> Generator[Self, None, None]
```

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.

### `AsyncClientContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A context for managing the async Prefect client instances.

Clients were formerly tracked on the TaskRunContext and FlowRunContext, but
having two separate places and the addition of both sync and async clients
made it difficult to manage. This context is intended to be the single
source for async clients.

The client creates an async client, which can either be read directly from
the context object OR loaded with get\_client, inject\_client, or other
Prefect utilities.

with AsyncClientContext.get\_or\_create() as ctx:
c1 = get\_client(sync\_client=False)
c2 = get\_client(sync\_client=False)
assert c1 is c2
assert c1 is ctx.client

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `get_or_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create(cls) -> AsyncGenerator[Self, None]
```

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.

### `RunContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The base context for a flow or task run. Data in this context will always be
available when `get_run_context` is called.

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self: Self, include_secrets: bool = True) -> dict[str, Any]
```

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.

### `EngineContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The context for a flow run. Data in this context is only available from within a
flow run function.

**Methods:**

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L412" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self: Self, include_secrets: bool = True) -> dict[str, Any]
```

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self: Self, include_secrets: bool = True) -> dict[str, Any]
```

### `TaskRunContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The context for a task run. Data in this context is only available from within a
task run function.

**Methods:**

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L459" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self: Self, include_secrets: bool = True) -> dict[str, Any]
```

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self: Self, include_secrets: bool = True) -> dict[str, Any]
```

### `AssetContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L482" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The asset context for a materializing task run. Contains all asset-related information needed
for asset event emission and downstream asset dependency propagation.

**Methods:**

#### `add_asset_metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L563" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_asset_metadata(self, asset_key: str, metadata: dict[str, Any]) -> None
```

Add metadata for a materialized asset.

**Args:**

* `asset_key`: The asset key
* `metadata`: Metadata dictionary to add

**Raises:**

* `ValueError`: If asset\_key is not in downstream\_assets

#### `asset_as_related` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L606" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asset_as_related(asset: Asset) -> dict[str, str]
```

Convert Asset to event related format.

#### `asset_as_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L584" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asset_as_resource(asset: Asset) -> dict[str, str]
```

Convert Asset to event resource format.

#### `emit_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L621" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_events(self, state: State) -> None
```

Emit asset events

#### `from_task_and_inputs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_task_and_inputs(cls, task: 'Task[Any, Any]', task_run_id: UUID, task_inputs: Optional[dict[str, set[Any]]] = None, copy_to_child_ctx: bool = False) -> 'AssetContext'
```

Create an AssetContext from a task and its resolved inputs.

**Args:**

* `task`: The task instance
* `task_run_id`: The task run ID
* `task_inputs`: The resolved task inputs (TaskRunResult objects)
* `copy_to_child_ctx`: Whether this context should be copied on a child AssetContext

**Returns:**

* Configured AssetContext

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `related_materialized_by` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L614" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
related_materialized_by(by: str) -> dict[str, str]
```

Create a related resource for the tool that performed the materialization

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L685" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self: Self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the AssetContext for distributed execution.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.

#### `update_tracked_assets` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L664" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_tracked_assets(self) -> None
```

Update the flow run context with assets that should be propagated downstream.

### `TagsContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L697" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The context for `prefect.tags` management.

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L708" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls) -> Self
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.

### `SettingsContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L715" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The context for a Prefect settings.

This allows for safe concurrent access and modification of settings.

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L735" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls) -> Optional['SettingsContext']
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-__init__



# `prefect.deployments`

*This module is empty or contains only private/internal implementations.*


# base
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-base



# `prefect.deployments.base`

Core primitives for managing Prefect deployments via `prefect deploy`, providing a minimally opinionated
build system for managing flows and deployments.

To get started, follow along with [the deployments tutorial](https://docs.prefect.io/v3/how-to-guides/deployments/create-deployments).

## Functions

### `create_default_prefect_yaml` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/base.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_default_prefect_yaml(path: str, name: Optional[str] = None, contents: Optional[Dict[str, Any]] = None) -> bool
```

Creates default `prefect.yaml` file in the provided path if one does not already exist;
returns boolean specifying whether a file was created.

**Args:**

* `name`: the name of the project; if not provided, the current directory name
  will be used
* `contents`: a dictionary of contents to write to the file; if not provided,
  defaults will be used

### `configure_project_by_recipe` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/base.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure_project_by_recipe(recipe: str, **formatting_kwargs: Any) -> dict[str, Any] | type[NotSet]
```

Given a recipe name, returns a dictionary representing base configuration options.

**Args:**

* `recipe`: the name of the recipe to use
* `formatting_kwargs`: additional keyword arguments to format the recipe

**Raises:**

* `ValueError`: if provided recipe name does not exist.

### `initialize_project` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/base.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
initialize_project(name: Optional[str] = None, recipe: Optional[str] = None, inputs: Optional[Dict[str, Any]] = None) -> List[str]
```

Initializes a basic project structure with base files.  If no name is provided, the name
of the current directory is used.  If no recipe is provided, one is inferred.

**Args:**

* `name`: the name of the project; if not provided, the current directory name
* `recipe`: the name of the recipe to use; if not provided, one is inferred
* `inputs`: a dictionary of inputs to use when formatting the recipe

**Returns:**

* List\[str]: a list of files / directories that were created


# deployments
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-deployments



# `prefect.deployments.deployments`

*This module is empty or contains only private/internal implementations.*


# flow_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-flow_runs



# `prefect.deployments.flow_runs`

## Functions

### `run_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/flow_runs.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_deployment(name: Union[str, UUID], client: Optional['PrefectClient'] = None, parameters: Optional[dict[str, Any]] = None, scheduled_time: Optional[datetime] = None, flow_run_name: Optional[str] = None, timeout: Optional[float] = None, poll_interval: Optional[float] = 5, tags: Optional[Iterable[str]] = None, idempotency_key: Optional[str] = None, work_queue_name: Optional[str] = None, as_subflow: Optional[bool] = True, job_variables: Optional[dict[str, Any]] = None) -> 'FlowRun'
```

Create a flow run for a deployment and return it after completion or a timeout.

By default, this function blocks until the flow run finishes executing.
Specify a timeout (in seconds) to wait for the flow run to execute before
returning flow run metadata. To return immediately, without waiting for the
flow run to execute, set `timeout=0`.

Note that if you specify a timeout, this function will return the flow run
metadata whether or not the flow run finished executing.

If called within a flow or task, the flow run this function creates will
be linked to the current flow run as a subflow. Disable this behavior by
passing `as_subflow=False`.

**Args:**

* `name`: The deployment id or deployment name in the form:
  `"flow name/deployment name"`
* `parameters`: Parameter overrides for this flow run. Merged with the deployment
  defaults.
* `scheduled_time`: The time to schedule the flow run for, defaults to scheduling
  the flow run to start now.
* `flow_run_name`: A name for the created flow run
* `timeout`: The amount of time to wait (in seconds) for the flow run to
  complete before returning. Setting `timeout` to 0 will return the flow
  run metadata immediately. Setting `timeout` to None will allow this
  function to poll indefinitely. Defaults to None.
* `poll_interval`: The number of seconds between polls
* `tags`: A list of tags to associate with this flow run; tags can be used in
  automations and for organizational purposes.
* `idempotency_key`: A unique value to recognize retries of the same run, and
  prevent creating multiple flow runs.
* `work_queue_name`: The name of a work queue to use for this run. Defaults to
  the default work queue for the deployment.
* `as_subflow`: Whether to link the flow run as a subflow of the current
  flow or task run.
* `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'`


# runner
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-runner



# `prefect.deployments.runner`

Objects for creating and configuring deployments for flows using `serve` functionality.

Example:

```python
import time
from prefect import flow, serve


@flow
def slow_flow(sleep: int = 60):
    "Sleepy flow - sleeps the provided amount of time (in seconds)."
    time.sleep(sleep)


@flow
def fast_flow():
    "Fastest flow this side of the Mississippi."
    return


if __name__ == "__main__":
    # to_deployment creates RunnerDeployment instances
    slow_deploy = slow_flow.to_deployment(name="sleeper", interval=45)
    fast_deploy = fast_flow.to_deployment(name="fast")

    serve(slow_deploy, fast_deploy)
```

## Functions

### `deploy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L1139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deploy(*deployments: RunnerDeployment) -> List[UUID]
```

Deploy the provided list of deployments to dynamic infrastructure via a
work pool.

By default, calling this function will build a Docker image for the deployments, push it to a
registry, and create each deployment via the Prefect API that will run the corresponding
flow on the given schedule.

If you want to use an existing image, you can pass `build=False` to skip building and pushing
an image.

**Args:**

* `*deployments`: A list of deployments to deploy.
* `work_pool_name`: The name of the work pool to use for these deployments. Defaults to
  the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.
* `image`: The name of the Docker image to build, including the registry and
  repository. Pass a DockerImage instance to customize the Dockerfile used
  and build arguments.
* `build`: Whether or not to build a new image for the flow. If False, the provided
  image will be used as-is and pulled at runtime.
* `push`: Whether or not to skip pushing the built image to a registry.
* `print_next_steps_message`: Whether or not to print a message with next steps
  after deploying the deployments.

**Returns:**

* A list of deployment IDs for the created/updated deployments.

**Examples:**

Deploy a group of flows to a work pool:

```python
from prefect import deploy, flow

@flow(log_prints=True)
def local_flow():
    print("I'm a locally defined flow!")

if __name__ == "__main__":
    deploy(
        local_flow.to_deployment(name="example-deploy-local-flow"),
        flow.from_source(
            source="https://github.com/org/repo.git",
            entrypoint="flows.py:my_flow",
        ).to_deployment(
            name="example-deploy-remote-flow",
        ),
        work_pool_name="my-work-pool",
        image="my-registry/my-image:dev",
    )
```

## Classes

### `DeploymentApplyError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when an error occurs while applying a deployment.

### `RunnerDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect RunnerDeployment definition, used for specifying and building deployments.

**Methods:**

#### `afrom_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L889" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
afrom_storage(cls, storage: RunnerStorage, entrypoint: str, name: str, flow_name: Optional[str] = None, interval: Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, parameters: Optional[dict[str, Any]] = None, triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, description: Optional[str] = None, tags: Optional[List[str]] = None, version: Optional[str] = None, version_type: Optional[VersionType] = None, enforce_parameter_schema: bool = True, work_pool_name: Optional[str] = None, work_queue_name: Optional[str] = None, job_variables: Optional[dict[str, Any]] = None, _sla: Optional[Union[SlaTypes, list[SlaTypes]]] = None) -> 'RunnerDeployment'
```

Create a RunnerDeployment from a flow located at a given entrypoint and stored in a
local storage location.

**Args:**

* `entrypoint`: The path to a file containing a flow and the name of the flow function in
  the format `./path/to/file.py\:flow_func_name`.
* `name`: A name for the deployment
* `flow_name`: The name of the flow to deploy
* `storage`: A storage object to use for retrieving flow code. If not provided, a
  URL must be provided.
* `interval`: An interval on which to execute the current flow. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `cron`: A cron schedule of when to execute runs of this flow.
* `rrule`: An rrule schedule of when to execute runs of this flow.
* `paused`: Whether or not the deployment is paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `triggers`: A list of triggers that should kick of a run of this flow.
* `parameters`: A dictionary of default parameter values to pass to runs of this flow.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `version_type`: The type of version information to use for the deployment. The version type
  will be inferred if not provided.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for this deployment.
* `work_pool_name`: The name of the work pool to use for this deployment.
* `work_queue_name`: The name of the work queue to use for this deployment's scheduled runs.
  If not provided the default work queue for the work pool will be used.
* `job_variables`: Settings used to override the values specified default base job template
  of the chosen work pool. Refer to the base job template of the chosen work pool for
  available settings.
* `_sla`: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.

#### `apply` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L493" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
apply(self, schedules: Optional[List[dict[str, Any]]] = None, work_pool_name: Optional[str] = None, image: Optional[str] = None, version_info: Optional[VersionInfo] = None) -> UUID
```

Registers this deployment with the API and returns the deployment's ID.

**Args:**

* `work_pool_name`: The name of the work pool to use for this
  deployment.
* `image`: The registry, name, and tag of the Docker image to
  use for this deployment. Only used when the deployment is
  deployed to a work pool.
* `version_info`: The version information to use for the deployment.

Returns:
The ID of the created deployment.

#### `entrypoint_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
entrypoint_type(self) -> EntrypointType
```

#### `from_entrypoint` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L785" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_entrypoint(cls, entrypoint: str, name: str, flow_name: Optional[str] = None, interval: Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, parameters: Optional[dict[str, Any]] = None, triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, description: Optional[str] = None, tags: Optional[List[str]] = None, version: Optional[str] = None, enforce_parameter_schema: bool = True, work_pool_name: Optional[str] = None, work_queue_name: Optional[str] = None, job_variables: Optional[dict[str, Any]] = None, _sla: Optional[Union[SlaTypes, list[SlaTypes]]] = None) -> 'RunnerDeployment'
```

Configure a deployment for a given flow located at a given entrypoint.

**Args:**

* `entrypoint`: The path to a file containing a flow and the name of the flow function in
  the format `./path/to/file.py\:flow_func_name`.
* `name`: A name for the deployment
* `flow_name`: The name of the flow to deploy
* `interval`: An interval on which to execute the current flow. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `cron`: A cron schedule of when to execute runs of this flow.
* `rrule`: An rrule schedule of when to execute runs of this flow.
* `paused`: Whether or not to set this deployment as paused.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to define multiple schedules or additional scheduling options like `timezone`.
* `triggers`: A list of triggers that should kick of a run of this flow.
* `parameters`: A dictionary of default parameter values to pass to runs of this flow.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for this deployment.
* `work_pool_name`: The name of the work pool to use for this deployment.
* `work_queue_name`: The name of the work queue to use for this deployment's scheduled runs.
  If not provided the default work queue for the work pool will be used.
* `job_variables`: Settings used to override the values specified default base job template
  of the chosen work pool. Refer to the base job template of the chosen work pool for
  available settings.
* `_sla`: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.

#### `from_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L641" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_flow(cls, flow: 'Flow[..., Any]', name: str, interval: Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, parameters: Optional[dict[str, Any]] = None, triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, description: Optional[str] = None, tags: Optional[List[str]] = None, version: Optional[str] = None, version_type: Optional[VersionType] = None, enforce_parameter_schema: bool = True, work_pool_name: Optional[str] = None, work_queue_name: Optional[str] = None, job_variables: Optional[dict[str, Any]] = None, entrypoint_type: EntrypointType = EntrypointType.FILE_PATH, _sla: Optional[Union[SlaTypes, list[SlaTypes]]] = None) -> 'RunnerDeployment'
```

Configure a deployment for a given flow.

**Args:**

* `flow`: A flow function to deploy
* `name`: A name for the deployment
* `interval`: An interval on which to execute the current flow. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `cron`: A cron schedule of when to execute runs of this flow.
* `rrule`: An rrule schedule of when to execute runs of this flow.
* `paused`: Whether or not to set this deployment as paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to define multiple schedules or additional scheduling options like `timezone`.
* `concurrency_limit`: The maximum number of concurrent runs this deployment will allow.
* `triggers`: A list of triggers that should kick of a run of this flow.
* `parameters`: A dictionary of default parameter values to pass to runs of this flow.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `version_type`: The type of version information to use for the deployment.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for this deployment.
* `work_pool_name`: The name of the work pool to use for this deployment.
* `work_queue_name`: The name of the work queue to use for this deployment's scheduled runs.
  If not provided the default work queue for the work pool will be used.
* `job_variables`: Settings used to override the values specified default base job template
  of the chosen work pool. Refer to the base job template of the chosen work pool for
  available settings.
* `_sla`: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.

#### `from_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L1015" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_storage(cls, storage: RunnerStorage, entrypoint: str, name: str, flow_name: Optional[str] = None, interval: Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, parameters: Optional[dict[str, Any]] = None, triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, description: Optional[str] = None, tags: Optional[List[str]] = None, version: Optional[str] = None, version_type: Optional[VersionType] = None, enforce_parameter_schema: bool = True, work_pool_name: Optional[str] = None, work_queue_name: Optional[str] = None, job_variables: Optional[dict[str, Any]] = None, _sla: Optional[Union[SlaTypes, list[SlaTypes]]] = None) -> 'RunnerDeployment'
```

Create a RunnerDeployment from a flow located at a given entrypoint and stored in a
local storage location.

**Args:**

* `entrypoint`: The path to a file containing a flow and the name of the flow function in
  the format `./path/to/file.py\:flow_func_name`.
* `name`: A name for the deployment
* `flow_name`: The name of the flow to deploy
* `storage`: A storage object to use for retrieving flow code. If not provided, a
  URL must be provided.
* `interval`: An interval on which to execute the current flow. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `cron`: A cron schedule of when to execute runs of this flow.
* `rrule`: An rrule schedule of when to execute runs of this flow.
* `paused`: Whether or not the deployment is paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `triggers`: A list of triggers that should kick of a run of this flow.
* `parameters`: A dictionary of default parameter values to pass to runs of this flow.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `version_type`: The type of version information to use for the deployment. The version type
  will be inferred if not provided.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for this deployment.
* `work_pool_name`: The name of the work pool to use for this deployment.
* `work_queue_name`: The name of the work queue to use for this deployment's scheduled runs.
  If not provided the default work queue for the work pool will be used.
* `job_variables`: Settings used to override the values specified default base job template
  of the chosen work pool. Refer to the base job template of the chosen work pool for
  available settings.
* `_sla`: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.

#### `full_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
full_name(self) -> str
```

#### `reconcile_paused` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reconcile_paused(cls, values: dict[str, Any]) -> dict[str, Any]
```

#### `reconcile_schedules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reconcile_schedules(cls, values: dict[str, Any]) -> dict[str, Any]
```

#### `validate_automation_names` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L292" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_automation_names(self)
```

Ensure that each trigger has a name for its automation if none is provided.

#### `validate_deployment_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_deployment_parameters(self) -> Self
```

Update the parameter schema to mark frozen parameters as readonly.

#### `validate_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_name(cls, value: str) -> str
```


# schedules
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-schedules



# `prefect.deployments.schedules`

## Functions

### `create_deployment_schedule_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/schedules.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_deployment_schedule_create(schedule: Union['SCHEDULE_TYPES', 'Schedule'], active: Optional[bool] = True) -> DeploymentScheduleCreate
```

Create a DeploymentScheduleCreate object from common schedule parameters.

### `normalize_to_deployment_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/schedules.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
normalize_to_deployment_schedule(schedules: Optional['FlexibleScheduleList']) -> List[Union[DeploymentScheduleCreate, DeploymentScheduleUpdate]]
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-steps-__init__



# `prefect.deployments.steps`

*This module is empty or contains only private/internal implementations.*


# core
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-steps-core



# `prefect.deployments.steps.core`

Core primitives for running Prefect deployment steps.

Deployment steps are YAML representations of Python functions along with their inputs.

Whenever a step is run, the following actions are taken:

* The step's inputs and block / variable references are resolved (see [the `prefect deploy` documentation](https://docs.prefect.io/v3/how-to-guides/deployments/prefect-yaml#templating-options) for more details)
* The step's function is imported; if it cannot be found, the `requires` keyword is used to install the necessary packages
* The step's function is called with the resolved inputs
* The step's output is returned and used to resolve inputs for subsequent steps

## Functions

### `run_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/core.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_step(step: dict[str, Any], upstream_outputs: Optional[dict[str, Any]] = None) -> dict[str, Any]
```

Runs a step, returns the step's output.

Steps are assumed to be in the format `{"importable.func.name": {"kwarg1": "value1", ...}}`.

The 'id and 'requires' keywords are reserved for specific purposes and will be removed from the
inputs before passing to the step function:

This keyword is used to specify packages that should be installed before running the step.

### `run_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/core.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_steps(steps: List[Dict[str, Any]], upstream_outputs: Optional[Dict[str, Any]] = None, print_function: Any = print) -> dict[str, Any]
```

## Classes

### `StepExecutionError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/core.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a step fails to execute.


# pull
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-steps-pull



# `prefect.deployments.steps.pull`

Core set of steps for specifying a Prefect project pull step.

## Functions

### `set_working_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/pull.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_working_directory(directory: str) -> dict[str, str]
```

Sets the working directory; works with both absolute and relative paths.

**Args:**

* `directory`: the directory to set as the working directory

**Returns:**

* a dictionary containing a `directory` key of the
  absolute path of the directory that was set

### `agit_clone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/pull.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
agit_clone(repository: str, branch: Optional[str] = None, commit_sha: Optional[str] = None, include_submodules: bool = False, access_token: Optional[str] = None, credentials: Optional['Block'] = None, directories: Optional[list[str]] = None) -> dict[str, str]
```

Asynchronously clones a git repository into the current working directory.

**Args:**

* `repository`: the URL of the repository to clone
* `branch`: the branch to clone; if not provided, the default branch will be used
* `commit_sha`: the commit SHA to clone; if not provided, the default branch will be used
* `include_submodules`: whether to include git submodules when cloning the repository
* `access_token`: an access token to use for cloning the repository; if not provided
  the repository will be cloned using the default git credentials
* `credentials`: a GitHubCredentials, GitLabCredentials, or BitBucketCredentials block can be used to specify the
  credentials to use for cloning the repository.

**Returns:**

* a dictionary containing a `directory` key of the new directory that was created

**Raises:**

* `subprocess.CalledProcessError`: if the git clone command fails for any reason

### `git_clone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/pull.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
git_clone(repository: str, branch: Optional[str] = None, commit_sha: Optional[str] = None, include_submodules: bool = False, access_token: Optional[str] = None, credentials: Optional['Block'] = None, directories: Optional[list[str]] = None) -> dict[str, str]
```

Clones a git repository into the current working directory.

**Args:**

* `repository`: the URL of the repository to clone
* `branch`: the branch to clone; if not provided, the default branch will be used
* `commit_sha`: the commit SHA to clone; if not provided, the default branch will be used
* `include_submodules`: whether to include git submodules when cloning the repository
* `access_token`: an access token to use for cloning the repository; if not provided
  the repository will be cloned using the default git credentials
* `credentials`: a GitHubCredentials, GitLabCredentials, or BitBucketCredentials block can be used to specify the
  credentials to use for cloning the repository.
* `directories`: Specify directories you want to be included (uses git sparse-checkout)

**Returns:**

* a dictionary containing a `directory` key of the new directory that was created

**Raises:**

* `subprocess.CalledProcessError`: if the git clone command fails for any reason

**Examples:**

Clone a public repository:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/PrefectHQ/prefect.git
```

Clone a branch of a public repository:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/PrefectHQ/prefect.git
        branch: my-branch
```

Clone a private repository using a GitHubCredentials block:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/org/repo.git
        credentials: "{{ prefect.blocks.github-credentials.my-github-credentials-block }}"
```

Clone a private repository using an access token:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/org/repo.git
        access_token: "{{ prefect.blocks.secret.github-access-token }}" # Requires creation of a Secret block
```

Note that you will need to [create a Secret block](https://docs.prefect.io/v3/concepts/blocks/#pre-registered-blocks) to store the
value of your git credentials. You can also store a username/password combo or token prefix (e.g. `x-token-auth`)
in your secret block. Refer to your git providers documentation for the correct authentication schema.

Clone a repository with submodules:

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/org/repo.git
        include_submodules: true
```

Clone a repository with an SSH key (note that the SSH key must be added to the worker
before executing flows):

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: git@github.com:org/repo.git
```

Clone a repository using sparse-checkout (allows specific folders of the repository to be checked out)

```yaml
pull:
    - prefect.deployments.steps.git_clone:
        repository: https://github.com/org/repo.git
        directories: ["dir_1", "dir_2", "prefect"]
```

### `pull_from_remote_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/pull.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_from_remote_storage(url: str, **settings: Any) -> dict[str, Any]
```

Pulls code from a remote storage location into the current working directory.

Works with protocols supported by `fsspec`.

**Args:**

* `url`: the URL of the remote storage location. Should be a valid `fsspec` URL.
  Some protocols may require an additional `fsspec` dependency to be installed.
  Refer to the [`fsspec` docs](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations)
  for more details.
* `**settings`: any additional settings to pass the `fsspec` filesystem class.

**Returns:**

* a dictionary containing a `directory` key of the new directory that was created

**Examples:**

Pull code from a remote storage location:

```yaml
pull:
    - prefect.deployments.steps.pull_from_remote_storage:
        url: s3://my-bucket/my-folder
```

Pull code from a remote storage location with additional settings:

```yaml
pull:
    - prefect.deployments.steps.pull_from_remote_storage:
        url: s3://my-bucket/my-folder
        key: {{ prefect.blocks.secret.my-aws-access-key }}}
        secret: {{ prefect.blocks.secret.my-aws-secret-key }}}
```

### `pull_with_block` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/pull.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_with_block(block_document_name: str, block_type_slug: str) -> dict[str, Any]
```

Pulls code using a block.

**Args:**

* `block_document_name`: The name of the block document to use
* `block_type_slug`: The slug of the type of block to use


# utility
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-deployments-steps-utility



# `prefect.deployments.steps.utility`

Utility project steps that are useful for managing a project's deployment lifecycle.

Steps within this module can be used within a `build`, `push`, or `pull` deployment action.

Example:
Use the `run_shell_script` setp to retrieve the short Git commit hash of the current
repository and use it as a Docker image tag:

```yaml
build:
    - prefect.deployments.steps.run_shell_script:
        id: get-commit-hash
        script: git rev-parse --short HEAD
        stream_output: false
    - prefect_docker.deployments.steps.build_docker_image:
        requires: prefect-docker
        image_name: my-image
        image_tag: "{{ get-commit-hash.stdout }}"
        dockerfile: auto
```

## Functions

### `run_shell_script` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/utility.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_shell_script(script: str, directory: Optional[str] = None, env: Optional[Dict[str, str]] = None, stream_output: bool = True, expand_env_vars: bool = False) -> RunShellScriptResult
```

Runs one or more shell commands in a subprocess. Returns the standard
output and standard error of the script.

**Args:**

* `script`: The script to run
* `directory`: The directory to run the script in. Defaults to the current
  working directory.
* `env`: A dictionary of environment variables to set for the script
* `stream_output`: Whether to stream the output of the script to
  stdout/stderr
* `expand_env_vars`: Whether to expand environment variables in the script
  before running it

**Returns:**

* A dictionary with the keys `stdout` and `stderr` containing the output
  of the script

**Examples:**

Retrieve the short Git commit hash of the current repository to use as
a Docker image tag:

```yaml
build:
    - prefect.deployments.steps.run_shell_script:
        id: get-commit-hash
        script: git rev-parse --short HEAD
        stream_output: false
    - prefect_docker.deployments.steps.build_docker_image:
        requires: prefect-docker
        image_name: my-image
        image_tag: "{{ get-commit-hash.stdout }}"
        dockerfile: auto
```

Run a multi-line shell script:

```yaml
build:
    - prefect.deployments.steps.run_shell_script:
        script: |
            echo "Hello"
            echo "World"
```

Run a shell script with environment variables:

```yaml
build:
    - prefect.deployments.steps.run_shell_script:
        script: echo "Hello $NAME"
        env:
            NAME: World
```

Run a shell script with environment variables expanded
from the current environment:

```yaml
pull:
    - prefect.deployments.steps.run_shell_script:
        script: |
            echo "User: $USER"
            echo "Home Directory: $HOME"
        stream_output: true
        expand_env_vars: true
```

Run a shell script in a specific directory:

```yaml
build:
    - prefect.deployments.steps.run_shell_script:
        script: echo "Hello"
        directory: /path/to/directory
```

Run a script stored in a file:

```yaml
build:
    - prefect.deployments.steps.run_shell_script:
        script: "bash path/to/script.sh"
```

### `pip_install_requirements` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/utility.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pip_install_requirements(directory: Optional[str] = None, requirements_file: str = 'requirements.txt', stream_output: bool = True) -> dict[str, Any]
```

Installs dependencies from a requirements.txt file.

**Args:**

* `requirements_file`: The requirements.txt to use for installation.
* `directory`: The directory the requirements.txt file is in. Defaults to
  the current working directory.
* `stream_output`: Whether to stream the output from pip install should be
  streamed to the console

**Returns:**

* A dictionary with the keys `stdout` and `stderr` containing the output
  the `pip install` command

**Raises:**

* `subprocess.CalledProcessError`: if the pip install command fails for any reason

## Classes

### `RunShellScriptResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/steps/utility.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The result of a `run_shell_script` step.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-docker-__init__



# `prefect.docker`

*This module is empty or contains only private/internal implementations.*


# docker_image
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-docker-docker_image



# `prefect.docker.docker_image`

## Classes

### `DockerImage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/docker/docker_image.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Configuration used to build and push a Docker image for a deployment.

**Methods:**

#### `build` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/docker/docker_image.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build(self) -> None
```

#### `push` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/docker/docker_image.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
push(self) -> None
```

#### `reference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/docker/docker_image.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reference(self) -> str
```


# engine
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-engine



# `prefect.engine`

## Functions

### `handle_engine_signals` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/engine.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_engine_signals(flow_run_id: UUID | None = None)
```

Handle signals from the orchestrator to abort or pause the flow run or otherwise
handle unexpected exceptions.

This context manager will handle exiting the process depending on the signal received.

**Args:**

* `flow_run_id`: The ID of the flow run to handle signals for.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-__init__



# `prefect.events`

*This module is empty or contains only private/internal implementations.*


# actions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-actions



# `prefect.events.actions`

## Classes

### `Action` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An Action that may be performed when an Automation is triggered

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DoNothing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Do nothing when an Automation is triggered

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `DeploymentAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Deployments and need to infer them from
events

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `selected_deployment_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_deployment_requires_id(self)
```

### `RunDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Runs the given deployment with the given parameters

**Methods:**

#### `selected_deployment_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_deployment_requires_id(self)
```

### `PauseDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses the given Deployment

**Methods:**

#### `selected_deployment_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_deployment_requires_id(self)
```

### `ResumeDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes the given Deployment

**Methods:**

#### `selected_deployment_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_deployment_requires_id(self)
```

### `ChangeFlowRunState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Changes the state of a flow run associated with the trigger

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `CancelFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Cancels a flow run associated with the trigger

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `ResumeFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a flow run associated with the trigger

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `SuspendFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Suspends a flow run associated with the trigger

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `CallWebhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Call a webhook when an Automation is triggered.

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `SendNotification` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Send a notification when an Automation is triggered

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `WorkPoolAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Work Pools and need to infer them from
events

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `PauseWorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses a Work Pool

### `ResumeWorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a Work Pool

### `WorkQueueAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Work Queues and need to infer them from
events

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `selected_work_queue_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_work_queue_requires_id(self) -> Self
```

### `PauseWorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses a Work Queue

**Methods:**

#### `selected_work_queue_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_work_queue_requires_id(self) -> Self
```

### `ResumeWorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a Work Queue

**Methods:**

#### `selected_work_queue_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_work_queue_requires_id(self) -> Self
```

### `AutomationAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Automations and need to infer them from
events

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `selected_automation_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_automation_requires_id(self) -> Self
```

### `PauseAutomation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses a Work Queue

**Methods:**

#### `selected_automation_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_automation_requires_id(self) -> Self
```

### `ResumeAutomation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a Work Queue

**Methods:**

#### `selected_automation_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_automation_requires_id(self) -> Self
```

### `DeclareIncident` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Declares an incident for the triggering event.  Only available on Prefect Cloud

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-cli-__init__



# `prefect.events.cli`

*This module is empty or contains only private/internal implementations.*


# automations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-cli-automations



# `prefect.events.cli.automations`

Command line interface for working with automations.

## Functions

### `requires_automations` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/cli/automations.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_automations(func: Callable[..., Any]) -> Callable[..., Any]
```

### `ls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/cli/automations.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ls()
```

List all automations.

### `inspect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/cli/automations.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inspect(name: Optional[str] = typer.Argument(None, help="An automation's name"), id: Optional[str] = typer.Option(None, '--id', help="An automation's id"), yaml: bool = typer.Option(False, '--yaml', help='Output as YAML'), json: bool = typer.Option(False, '--json', help='Output as JSON'), output: Optional[str] = typer.Option(None, '--output', '-o', help='Specify an output format. Currently supports: json, yaml'))
```

Inspect an automation.

Arguments:

name: the name of the automation to inspect

id: the id of the automation to inspect

yaml: output as YAML

json: output as JSON

Examples:

`$ prefect automation inspect "my-automation"`

`$ prefect automation inspect --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`

`$ prefect automation inspect "my-automation" --yaml`

`$ prefect automation inspect "my-automation" --output json`
`$ prefect automation inspect "my-automation" --output yaml`

### `resume` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/cli/automations.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume(name: Optional[str] = typer.Argument(None, help="An automation's name"), id: Optional[str] = typer.Option(None, '--id', help="An automation's id"))
```

Resume an automation.

Arguments:

name: the name of the automation to resume

id: the id of the automation to resume

Examples:

`$ prefect automation resume "my-automation"`

`$ prefect automation resume --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`

### `pause` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/cli/automations.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause(name: Optional[str] = typer.Argument(None, help="An automation's name"), id: Optional[str] = typer.Option(None, '--id', help="An automation's id"))
```

Pause an automation.

Arguments:

name: the name of the automation to pause

id: the id of the automation to pause

Examples:

`$ prefect automation pause "my-automation"`

`$ prefect automation pause --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`

### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/cli/automations.py#L301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(name: Optional[str] = typer.Argument(None, help="An automation's name"), id: Optional[str] = typer.Option(None, '--id', help="An automation's id"))
```

Delete an automation.

**Args:**

* `name`: the name of the automation to delete
* `id`: the id of the automation to delete

**Examples:**

`$ prefect automation delete "my-automation"`
`$ prefect automation delete --id "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"`

### `create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/cli/automations.py#L353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create(from_file: Optional[str] = typer.Option(None, '--from-file', '-f', help='Path to YAML or JSON file containing automation(s)'), from_json: Optional[str] = typer.Option(None, '--from-json', '-j', help='JSON string containing automation(s)'))
```

Create one or more automations from a file or JSON string.

**Examples:**

`$ prefect automation create --from-file automation.yaml`
`$ prefect automation create -f automation.json`
`$ prefect automation create --from-json '{"name": "my-automation", "trigger": {...}, "actions": [...]}'`
`$ prefect automation create -j '[{"name": "auto1", ...}, {"name": "auto2", ...}]'`


# clients
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-clients



# `prefect.events.clients`

## Functions

### `http_to_ws` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
http_to_ws(url: str) -> str
```

### `events_in_socket_from_api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_in_socket_from_api_url(url: str) -> str
```

### `events_out_socket_from_api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_out_socket_from_api_url(url: str) -> str
```

### `get_events_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_events_client(reconnection_attempts: int = 10, checkpoint_every: int = 700) -> 'EventsClient'
```

### `get_events_subscriber` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_events_subscriber(filter: Optional['EventFilter'] = None, reconnection_attempts: int = 10) -> 'PrefectEventSubscriber'
```

## Classes

### `EventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The abstract interface for all Prefect Events clients

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

Emit a single event

### `NullEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect Events client implementation that does nothing

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

Emit a single event

### `AssertingEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect Events client that records all events sent to it for inspection during
tests.

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

Emit a single event

#### `pop_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L219" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pop_events(self) -> List[Event]
```

#### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(cls) -> None
```

Reset all captured instances and their events. For use between
tests

### `PrefectEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect Events client that streams events to a Prefect server

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

Emit a single event

### `AssertingPassthroughEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect Events client that BOTH records all events sent to it for inspection
during tests AND sends them to a Prefect server.

**Methods:**

#### `pop_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pop_events(self) -> list[Event]
```

#### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L429" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(cls) -> None
```

### `PrefectCloudEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L451" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect Events client that streams events to a Prefect Cloud Workspace

### `PrefectEventSubscriber` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L486" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Subscribes to a Prefect event stream, yielding events as they occur.

Example:

from prefect.events.clients import PrefectEventSubscriber
from prefect.events.filters import EventFilter, EventNameFilter

filter = EventFilter(event=EventNameFilter(prefix=\["prefect.flow-run."]))

async with PrefectEventSubscriber(filter=filter) as subscriber:
async for event in subscriber:
print(event.occurred, event.resource.id, event.event)

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L548" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

### `PrefectCloudEventSubscriber` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L674" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L548" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

### `PrefectCloudAccountEventSubscriber` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L700" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# filters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-filters



# `prefect.events.filters`

## Classes

### `AutomationFilterCreated` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Automation.created`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `AutomationFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Automation.created`.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `AutomationFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `EventDataFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base class for filtering event data.

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `EventOccurredFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventNameFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventResourceFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventRelatedFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventAnyResourceFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventIDFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventTextFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by text search across event content.

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventOrder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `EventFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?


# related
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-related



# `prefect.events.related`

## Functions

### `tags_as_related_resources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/related.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
tags_as_related_resources(tags: Iterable[str]) -> List[RelatedResource]
```

### `object_as_related_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/related.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
object_as_related_resource(kind: str, role: str, object: Any) -> RelatedResource
```

### `related_resources_from_run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/related.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
related_resources_from_run_context(client: 'PrefectClient', exclude: Optional[Set[str]] = None) -> List[RelatedResource]
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-schemas-__init__



# `prefect.events.schemas`

*This module is empty or contains only private/internal implementations.*


# automations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-schemas-automations



# `prefect.events.schemas.automations`

## Functions

### `trigger_discriminator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
trigger_discriminator(value: Any) -> str
```

Discriminator for triggers that defaults to 'event' if no type is specified.

## Classes

### `Posture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `Trigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class describing a set of criteria that must be satisfied in order to trigger
an automation.

**Methods:**

#### `actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
actions(self) -> List[ActionTypes]
```

#### `as_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_automation(self) -> 'AutomationCore'
```

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `owner_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
owner_resource(self) -> Optional[str]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `set_deployment_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_deployment_id(self, deployment_id: UUID) -> None
```

### `ResourceTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for triggers that may filter by the labels of resources.

**Methods:**

#### `actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
actions(self) -> List[ActionTypes]
```

#### `as_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_automation(self) -> 'AutomationCore'
```

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `owner_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
owner_resource(self) -> Optional[str]
```

#### `set_deployment_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_deployment_id(self, deployment_id: UUID) -> None
```

### `EventTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A trigger that fires based on the presence or absence of events within a given
period of time.

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `enforce_minimum_within_for_proactive_triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_minimum_within_for_proactive_triggers(cls, data: Dict[str, Any]) -> Dict[str, Any]
```

### `MetricTriggerOperator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `PrefectMetric` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `MetricTriggerQuery` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines a subset of the Trigger subclass, which is specific
to Metric automations, that specify the query configurations
and breaching conditions for the Automation

**Methods:**

#### `enforce_minimum_range` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_minimum_range(cls, value: timedelta) -> timedelta
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `MetricTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A trigger that fires based on the results of a metric query.

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

### `CompositeTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Requires some number of triggers to have fired within the given time period.

**Methods:**

#### `actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
actions(self) -> List[ActionTypes]
```

#### `as_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_automation(self) -> 'AutomationCore'
```

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `owner_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
owner_resource(self) -> Optional[str]
```

#### `set_deployment_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_deployment_id(self, deployment_id: UUID) -> None
```

### `CompoundTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L341" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A composite trigger that requires some number of triggers to have
fired within the given time period

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `validate_require` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_require(self) -> Self
```

### `SequenceTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L378" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A composite trigger that requires some number of triggers to have fired
within the given time period in a specific order

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

### `AutomationCore` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines an action a user wants to take when a certain number of events
do or don't happen to the matching resources

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L481" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# deployment_triggers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-schemas-deployment_triggers



# `prefect.events.schemas.deployment_triggers`

Schemas for defining triggers within a Prefect deployment YAML.  This is a separate
parallel hierarchy for representing triggers so that they can also include the
information necessary to create an automation.

These triggers should follow the validation rules of the main Trigger class hierarchy as
closely as possible (because otherwise users will get validation errors creating
triggers), but we can be more liberal with the defaults here to make it simpler to
create them from YAML.

## Functions

### `deployment_trigger_discriminator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/deployment_triggers.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deployment_trigger_discriminator(value: Any) -> str
```

Custom discriminator for deployment triggers that defaults to 'event' if no type is specified.

## Classes

### `BaseDeploymentTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/deployment_triggers.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class describing a set of criteria that must be satisfied in order to trigger
an automation.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `DeploymentEventTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/deployment_triggers.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A trigger that fires based on the presence or absence of events within a given
period of time.

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `enforce_minimum_within_for_proactive_triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_minimum_within_for_proactive_triggers(cls, data: Dict[str, Any]) -> Dict[str, Any]
```

### `DeploymentMetricTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/deployment_triggers.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A trigger that fires based on the results of a metric query.

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

### `DeploymentCompoundTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/deployment_triggers.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A composite trigger that requires some number of triggers to have
fired within the given time period

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `validate_require` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_require(self) -> Self
```

### `DeploymentSequenceTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/deployment_triggers.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A composite trigger that requires some number of triggers to have fired
within the given time period in a specific order

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI


# events
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-schemas-events



# `prefect.events.schemas.events`

## Functions

### `matches` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches(expected: str, value: Optional[str]) -> bool
```

Returns true if the given value matches the expected string, which may
include a a negation prefix ("!this-value") or a wildcard suffix
("any-value-starting-with\*")

## Classes

### `Resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An observable business object of interest to the user

**Methods:**

#### `as_label_value_array` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_label_value_array(self) -> List[Dict[str, str]]
```

#### `enforce_maximum_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_maximum_labels(self) -> Self
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, label: str, default: Optional[str] = None) -> Optional[str]
```

#### `has_all_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
has_all_labels(self, labels: Dict[str, str]) -> bool
```

#### `id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
id(self) -> str
```

#### `items` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
items(self) -> Iterable[Tuple[str, str]]
```

#### `keys` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keys(self) -> Iterable[str]
```

#### `labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
labels(self) -> LabelDiver
```

#### `name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
name(self) -> Optional[str]
```

#### `prefect_object_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_object_id(self, kind: str) -> UUID
```

Extracts the UUID from an event's resource ID if it's the expected kind
of prefect resource

#### `requires_resource_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_resource_id(self) -> Self
```

### `RelatedResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Resource with a specific role in an Event

**Methods:**

#### `enforce_maximum_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_maximum_labels(self) -> Self
```

#### `id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
id(self) -> str
```

#### `name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
name(self) -> Optional[str]
```

#### `prefect_object_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_object_id(self, kind: str) -> UUID
```

Extracts the UUID from an event's resource ID if it's the expected kind
of prefect resource

#### `requires_resource_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_resource_id(self) -> Self
```

#### `requires_resource_role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_resource_role(self) -> Self
```

#### `role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
role(self) -> str
```

### `Event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The client-side view of an event that has happened to a Resource

**Methods:**

#### `find_resource_label` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
find_resource_label(self, label: str) -> Optional[str]
```

Finds the value of the given label in this event's resource or one of its
related resources.  If the label starts with `related:<role>:`, search for the
first matching label in a related resource with that role.

#### `involved_resources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
involved_resources(self) -> Sequence[Resource]
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `resource_in_role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resource_in_role(self) -> Mapping[str, RelatedResource]
```

Returns a mapping of roles to the first related resource in that role

#### `resources_in_role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resources_in_role(self) -> Mapping[str, Sequence[RelatedResource]]
```

Returns a mapping of roles to related resources in that role

### `ReceivedEvent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The server-side view of an event that has happened to a Resource after it has
been received by the server

**Methods:**

#### `is_set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/concurrency/primitives.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_set(self)
```

#### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/concurrency/primitives.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self) -> None
```

Set the flag, notifying all waiters.

Unlike `asyncio.Event`, waiters may not be notified immediately when this is
called; instead, notification will be placed on the owning loop of each waiter
for thread safety.

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/concurrency/primitives.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self) -> Literal[True]
```

Block until the internal flag is true.

If the internal flag is true on entry, return True immediately.
Otherwise, block until another `set()` is called, then return True.

### `ResourceSpecification` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L214" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `deepcopy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deepcopy(self) -> 'ResourceSpecification'
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, key: str, default: Optional[Union[str, List[str]]] = None) -> Optional[List[str]]
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, candidates: Iterable[Resource]) -> bool
```

#### `items` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
items(self) -> Iterable[Tuple[str, List[str]]]
```

#### `matches` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches(self, resource: Resource) -> bool
```

#### `matches_every_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches_every_resource(self) -> bool
```

#### `matches_every_resource_of_kind` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches_every_resource_of_kind(self, prefix: str) -> bool
```

#### `pop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pop(self, key: str, default: Optional[Union[str, List[str]]] = None) -> Optional[List[str]]
```


# labelling
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-schemas-labelling



# `prefect.events.schemas.labelling`

## Classes

### `LabelDiver` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L6" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The LabelDiver supports templating use cases for any Labelled object, by
presenting the labels as a graph of objects that may be accessed by attribute.  For
example:

```python
diver = LabelDiver({
    'hello.world': 'foo',
    'hello.world.again': 'bar'
})

assert str(diver.hello.world) == 'foo'
assert str(diver.hello.world.again) == 'bar'
```

### `Labelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `as_label_value_array` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_label_value_array(self) -> List[Dict[str, str]]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, label: str, default: Optional[str] = None) -> Optional[str]
```

#### `has_all_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
has_all_labels(self, labels: Dict[str, str]) -> bool
```

#### `items` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
items(self) -> Iterable[Tuple[str, str]]
```

#### `keys` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keys(self) -> Iterable[str]
```

#### `labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
labels(self) -> LabelDiver
```


# utilities
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-utilities



# `prefect.events.utilities`

## Functions

### `emit_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/utilities.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_event(event: str, resource: dict[str, str], occurred: datetime.datetime | None = None, related: list[dict[str, str]] | list[RelatedResource] | None = None, payload: dict[str, Any] | None = None, id: UUID | None = None, follows: Event | None = None, **kwargs: dict[str, Any] | None) -> Event | None
```

Send an event to Prefect.

**Args:**

* `event`: The name of the event that happened.
* `resource`: The primary Resource this event concerns.
* `occurred`: When the event happened from the sender's perspective.
  Defaults to the current datetime.
* `related`: A list of additional Resources involved in this event.
* `payload`: An open-ended set of data describing what happened.
* `id`: The sender-provided identifier for this event. Defaults to a random
  UUID.
* `follows`: The event that preceded this one. If the preceding event
  happened more than 5 minutes prior to this event the follows
  relationship will not be set.

**Returns:**

* The event that was emitted if worker is using a client that emit
* events, otherwise None


# worker
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-events-worker



# `prefect.events.worker`

## Functions

### `should_emit_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/worker.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
should_emit_events() -> bool
```

### `emit_events_to_cloud` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/worker.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_events_to_cloud() -> bool
```

### `should_emit_events_to_running_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/worker.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
should_emit_events_to_running_server() -> bool
```

### `should_emit_events_to_ephemeral_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/worker.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
should_emit_events_to_ephemeral_server() -> bool
```

## Classes

### `EventsWorker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/worker.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `attach_related_resources_from_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/worker.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
attach_related_resources_from_context(self, event: Event) -> None
```

#### `instance` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/worker.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
instance(cls: Type[Self], client_type: Optional[Type[EventsClient]] = None) -> Self
```


# exceptions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-exceptions



# `prefect.exceptions`

Prefect-specific exceptions.

## Functions

### `exception_traceback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exception_traceback(exc: Exception) -> str
```

Convert an exception to a printable string with a traceback

## Classes

### `PrefectException` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base exception type for Prefect errors.

### `CrashedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the result from a crashed run is retrieved.

This occurs when a string is attached to the state instead of an exception or if
the state's data is null.

### `FailedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the result from a failed run is retrieved and an exception is not
attached.

This occurs when a string is attached to the state instead of an exception or if
the state's data is null.

### `CancelledRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the result from a cancelled run is retrieved and an exception
is not attached.

This occurs when a string is attached to the state instead of an exception
or if the state's data is null.

### `PausedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the result from a paused run is retrieved.

### `UnfinishedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the result from a run that is not finished is retrieved.

For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.

### `MissingFlowError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a given flow name is not found in the expected script.

### `UnspecifiedFlowError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when multiple flows are found in the expected script and no name is given.

### `MissingResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a result is missing from a state; often when result persistence is
disabled and the state is retrieved from the API.

### `ScriptError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a script errors during evaluation while attempting to load data

### `ParameterTypeError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a parameter does not pass Pydantic type validation.

**Methods:**

#### `from_validation_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_validation_error(cls, exc: ValidationError) -> Self
```

### `ParameterBindError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when args and kwargs cannot be converted to parameters.

**Methods:**

#### `from_bind_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_bind_failure(cls, fn: Callable[..., Any], exc: TypeError, call_args: tuple[Any, ...], call_kwargs: dict[str, Any]) -> Self
```

### `SignatureMismatchError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when parameters passed to a function do not match its signature.

**Methods:**

#### `from_bad_params` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_bad_params(cls, expected_params: list[str], provided_params: list[str]) -> Self
```

### `ObjectNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the client receives a 404 (not found) from the API.

### `ObjectAlreadyExists` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the client receives a 409 (conflict) from the API.

### `ObjectLimitReached` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the client receives a 403 (forbidden) from the API due to reaching an object limit (e.g. maximum number of deployments).

### `ObjectUnsupported` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the client receives a 403 (forbidden) from the API due to an unsupported object (i.e. requires a specific Prefect Cloud tier).

### `UpstreamTaskError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a task relies on the result of another task but that task is not
'COMPLETE'

### `MissingContextError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a method is called that requires a task or flow run context to be
active but one cannot be found.

### `MissingProfileError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a profile name does not exist.

### `ReservedArgumentError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a function used with Prefect has an argument with a name that is
reserved for a Prefect feature

### `InvalidNameError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a name contains characters that are not permitted.

### `PrefectSignal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L296" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base type for signal-like exceptions that should never be caught by users.

### `Abort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the API sends an 'ABORT' instruction during state proposal.

Indicates that the run should exit immediately.

### `Pause` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a flow run is PAUSED and needs to exit for resubmission.

### `ExternalSignal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base type for external signal-like exceptions that should never be caught by users.

### `TerminationSignal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a flow run receives a termination signal.

### `PrefectHTTPStatusError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when client receives a `Response` that contains an HTTPStatusError.

Used to include API error details in the error messages that the client provides users.

**Methods:**

#### `from_httpx_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_httpx_error(cls: type[Self], httpx_error: HTTPStatusError) -> Self
```

Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.

### `MappingLengthMismatch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L368" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when attempting to call Task.map with arguments of different lengths.

### `MappingMissingIterable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when attempting to call Task.map with all static arguments

### `BlockMissingCapabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a block does not have required capabilities for a given operation.

### `ProtectedBlockError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when an operation is prevented due to block protection.

### `InvalidRepositoryURLError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L392" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when an incorrect URL is provided to a GitHub filesystem block.

### `InfrastructureError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base class for exceptions related to infrastructure blocks

### `InfrastructureNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when infrastructure is missing, likely because it has exited or been
deleted.

### `InfrastructureNotAvailable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when infrastructure is not accessible from the current machine. For example,
if a process was spawned on another machine it cannot be managed.

### `NotPausedError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when attempting to unpause a run that isn't paused.

### `FlowPauseTimeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L420" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a flow pause times out

### `FlowRunWaitTimeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a flow run takes longer than a given timeout

### `PrefectImportError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L428" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An error raised when a Prefect object cannot be imported due to a move or removal.

### `SerializationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L437" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when an object cannot be serialized.

### `ConfigurationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L443" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a configuration is invalid.

### `ProfileSettingsValidationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a profile settings are invalid.

### `HashError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L458" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when hashing objects fails


# filesystems
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-filesystems



# `prefect.filesystems`

## Classes

### `ReadableFileSystem` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `WritableFileSystem` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> None
```

### `ReadableDeploymentStorage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `WritableDeploymentStorage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.

#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.

#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.

#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**

* The block placeholder for the current block in the format
  `prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**

* `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.

#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `name`: The name or slug of the block document. A block document slug is a
  string with the format `<block_type_slug>/<block_document_name>`
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:

```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:

```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```

#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:

* `{"block_document_id": <block_document_id>}`
* `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**

* `ref`: The reference to the block document. This can be a block document ID,
  or one of supported dictionary reference formats.
* `validate`: If False, the block document will be loaded without Pydantic
  validating the block schema. This is useful if the block schema has
  changed client-side since the block document referred to by `name` was saved.
* `client`: The client to use to load the block document. If not provided, the
  default client will be injected.

**Raises:**

* `ValueError`: If invalid reference format is provided.
* `ValueError`: If the requested block document is not found.

**Returns:**

* An instance of the current class hydrated with the data stored in the
* block document with the specified name.

#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1585" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**

* `client`: Optional client to use for registering type and schema with the
  Prefect API. A new client will be created and used if one is not
  provided.

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**

* `name`: User specified name to give saved block document which can later be used to load the
  block document.
* `overwrite`: Boolean value specifying if values should be overwritten if a block document with
  the specified name already exists.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

### `LocalFileSystem` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Store data as a file on a local file system.

**Methods:**

#### `aget_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

Copies a directory from one place to another on the local filesystem.

Defaults to copying the entire contents of the block's basepath to the current working directory.

#### `aput_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aput_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
```

Copies a directory from one place to another on the local filesystem.

Defaults to copying the entire contents of the current working directory to the block's basepath.
An `ignore_file` path may be provided that can include gitignore style expressions for filepaths to ignore.

#### `aread_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aread_path(self, path: str) -> bytes
```

#### `awrite_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L334" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
awrite_path(self, path: str, content: bytes) -> str
```

#### `cast_pathlib` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cast_pathlib(cls, value: str | Path | None) -> str | None
```

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

Copies a directory from one place to another on the local filesystem.

Defaults to copying the entire contents of the block's basepath to the current working directory.

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
```

Copies a directory from one place to another on the local filesystem.

Defaults to copying the entire contents of the current working directory to the block's basepath.
An `ignore_file` path may be provided that can include gitignore style expressions for filepaths to ignore.

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> str
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> None
```

### `RemoteFileSystem` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L366" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Store data as a file on a remote file system.

Supports any remote file system supported by `fsspec`. The file system is specified
using a protocol. For example, "s3://my-bucket/my-folder/" will use S3.

**Methods:**

#### `check_basepath` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_basepath(cls, value: str) -> str
```

#### `filesystem` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filesystem(self) -> fsspec.AbstractFileSystem
```

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L428" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

Downloads a directory from a given remote path to a local directory.

Defaults to downloading the entire contents of the block's basepath to the current working directory.

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L451" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None, overwrite: bool = True) -> int
```

Uploads a directory from a given local path to a remote directory.

Defaults to uploading the entire contents of the current working directory to the block's basepath.

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L505" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L514" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> str
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> None
```

### `SMB` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Store data as a file on a SMB share.

**Methods:**

#### `basepath` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
basepath(self) -> str
```

#### `filesystem` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L593" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filesystem(self) -> RemoteFileSystem
```

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L610" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> bytes
```

Downloads a directory from a given remote path to a local directory.
Defaults to downloading the entire contents of the block's basepath to the current working directory.

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L622" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> int
```

Uploads a directory from a given local path to a remote directory.
Defaults to uploading the entire contents of the current working directory to the block's basepath.

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L640" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> bytes
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L644" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> str
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> None
```

### `NullFileSystem` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L648" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A file system that does not store any data.

**Methods:**

#### `get_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L659" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
```

#### `put_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L664" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
```

#### `read_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L653" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_path(self, path: str) -> None
```

#### `write_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/filesystems.py#L656" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_path(self, path: str, content: bytes) -> None
```


# flow_engine
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-flow_engine



# `prefect.flow_engine`

## Functions

### `load_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_flow_run(flow_run_id: UUID) -> FlowRun
```

### `load_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_flow(flow_run: FlowRun) -> Flow[..., Any]
```

### `load_flow_and_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_flow_and_flow_run(flow_run_id: UUID) -> tuple[FlowRun, Flow[..., Any]]
```

### `run_flow_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1376" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_flow_sync(flow: Flow[P, R], flow_run: Optional[FlowRun] = None, parameters: Optional[Dict[str, Any]] = None, wait_for: Optional[Iterable[PrefectFuture[Any]]] = None, return_type: Literal['state', 'result'] = 'result', context: Optional[dict[str, Any]] = None) -> Union[R, State, None]
```

### `run_flow_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_flow_async(flow: Flow[P, R], flow_run: Optional[FlowRun] = None, parameters: Optional[Dict[str, Any]] = None, wait_for: Optional[Iterable[PrefectFuture[Any]]] = None, return_type: Literal['state', 'result'] = 'result', context: Optional[dict[str, Any]] = None) -> Union[R, State, None]
```

### `run_generator_flow_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_generator_flow_sync(flow: Flow[P, R], flow_run: Optional[FlowRun] = None, parameters: Optional[Dict[str, Any]] = None, wait_for: Optional[Iterable[PrefectFuture[Any]]] = None, return_type: Literal['state', 'result'] = 'result', context: Optional[dict[str, Any]] = None) -> Generator[R, None, None]
```

### `run_generator_flow_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1465" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_generator_flow_async(flow: Flow[P, R], flow_run: Optional[FlowRun] = None, parameters: Optional[Dict[str, Any]] = None, wait_for: Optional[Iterable[PrefectFuture[R]]] = None, return_type: Literal['state', 'result'] = 'result', context: Optional[dict[str, Any]] = None) -> AsyncGenerator[R, None]
```

### `run_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1508" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_flow(flow: Flow[P, R], flow_run: Optional[FlowRun] = None, parameters: Optional[Dict[str, Any]] = None, wait_for: Optional[Iterable[PrefectFuture[R]]] = None, return_type: Literal['state', 'result'] = 'result', error_logger: Optional[logging.Logger] = None, context: Optional[dict[str, Any]] = None) -> R | State | None | Coroutine[Any, Any, R | State | None] | Generator[R, None, None] | AsyncGenerator[R, None]
```

### `run_flow_in_subprocess` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1581" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_flow_in_subprocess(flow: 'Flow[..., Any]', flow_run: 'FlowRun | None' = None, parameters: dict[str, Any] | None = None, wait_for: Iterable[PrefectFuture[Any]] | None = None, context: dict[str, Any] | None = None) -> multiprocessing.context.SpawnProcess
```

Run a flow in a subprocess.

Note the result of the flow will only be accessible if the flow is configured to
persist its result.

**Args:**

* `flow`: The flow to run.
* `flow_run`: The flow run object containing run metadata.
* `parameters`: The parameters to use when invoking the flow.
* `wait_for`: The futures to wait for before starting the flow.
* `context`: A serialized context to hydrate before running the flow. If not provided,
  the current context will be used. A serialized context should be provided if
  this function is called in a separate memory space from the parent run (e.g.
  in a subprocess or on another machine).

**Returns:**

* A multiprocessing.context.SpawnProcess representing the process that is running the flow.

## Classes

### `FlowRunTimeoutError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a flow run exceeds its defined timeout.

### `BaseFlowRunEngine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `cancel_all_tasks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cancel_all_tasks(self) -> None
```

#### `is_pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_pending(self) -> bool
```

#### `is_running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_running(self) -> bool
```

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

### `FlowRunEngine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `begin_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_run(self) -> State
```

#### `call_flow_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L788" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_flow_fn(self) -> Union[R, Coroutine[Any, Any, R]]
```

Convenience method to call the flow function. Returns a coroutine if the
flow is async.

#### `call_hooks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L536" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_hooks(self, state: Optional[State] = None) -> None
```

#### `client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client(self) -> SyncPrefectClient
```

#### `create_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L501" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run(self, client: SyncPrefectClient) -> FlowRun
```

#### `handle_crash` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L443" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_crash(self, exc: BaseException) -> None
```

#### `handle_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L392" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_exception(self, exc: Exception, msg: Optional[str] = None, result_store: Optional[ResultStore] = None) -> State
```

#### `handle_success` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L372" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_success(self, result: R) -> R
```

#### `handle_timeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L425" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_timeout(self, exc: TimeoutError) -> None
```

#### `initialize_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L681" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
initialize_run(self)
```

Enters a client context and creates a flow run if needed.

#### `load_subflow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L452" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_subflow_run(self, parent_task_run: TaskRun, client: SyncPrefectClient, context: FlowRunContext) -> Union[FlowRun, None]
```

This method attempts to load an existing flow run for a subflow task
run, if appropriate.

If the parent task run is in a final but not COMPLETED state, and not
being rerun, then we attempt to load an existing flow run instead of
creating a new one. This will prevent the engine from running the
subflow again.

If no existing flow run is found, or if the subflow should be rerun,
then no flow run is returned.

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: bool = True) -> 'Union[R, State, None]'
```

#### `run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L769" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_context(self)
```

#### `set_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state(self, state: State, force: bool = False) -> State
```

#### `setup_run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L593" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_run_context(self, client: Optional[SyncPrefectClient] = None)
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L757" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> Generator[None, None, None]
```

### `AsyncFlowRunEngine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L806" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Async version of the flow run engine.

NOTE: This has not been fully asyncified yet which may lead to async flows
not being fully asyncified.

**Methods:**

#### `begin_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L863" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_run(self) -> State
```

#### `call_flow_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_flow_fn(self) -> Coroutine[Any, Any, R]
```

Convenience method to call the flow function. Returns a coroutine if the
flow is async.

#### `call_hooks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_hooks(self, state: Optional[State] = None) -> None
```

#### `client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L819" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client(self) -> PrefectClient
```

#### `create_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1073" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run(self, client: PrefectClient) -> FlowRun
```

#### `handle_crash` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1011" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_crash(self, exc: BaseException) -> None
```

#### `handle_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L961" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_exception(self, exc: Exception, msg: Optional[str] = None, result_store: Optional[ResultStore] = None) -> State
```

#### `handle_success` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L944" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_success(self, result: R) -> R
```

#### `handle_timeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L992" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_timeout(self, exc: TimeoutError) -> None
```

#### `initialize_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
initialize_run(self)
```

Enters a client context and creates a flow run if needed.

#### `load_subflow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1024" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_subflow_run(self, parent_task_run: TaskRun, client: PrefectClient, context: FlowRunContext) -> Union[FlowRun, None]
```

This method attempts to load an existing flow run for a subflow task
run, if appropriate.

If the parent task run is in a final but not COMPLETED state, and not
being rerun, then we attempt to load an existing flow run instead of
creating a new one. This will prevent the engine from running the
subflow again.

If no existing flow run is found, or if the subflow should be rerun,
then no flow run is returned.

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L919" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: bool = True) -> 'Union[R, State, None]'
```

#### `run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_context(self)
```

#### `set_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L902" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state(self, state: State, force: bool = False) -> State
```

#### `setup_run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_run_context(self, client: Optional[PrefectClient] = None)
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_engine.py#L1333" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> AsyncGenerator[None, None]
```


# flow_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-flow_runs



# `prefect.flow_runs`

## Functions

### `wait_for_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_runs.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_flow_run(flow_run_id: UUID, timeout: int | None = 10800, poll_interval: int | None = None, client: 'PrefectClient | None' = None, log_states: bool = False) -> FlowRun
```

Waits for the prefect flow run to finish and returns the FlowRun

**Args:**

* `flow_run_id`: The flow run ID for the flow run to wait for.
* `timeout`: The wait timeout in seconds. Defaults to 10800 (3 hours).
* `poll_interval`: Deprecated; polling is no longer used to wait for flow runs.
* `client`: Optional Prefect client. If not provided, one will be injected.
* `log_states`: If True, log state changes. Defaults to False.

**Returns:**

* The finished flow run.

**Raises:**

* `prefect.exceptions.FlowWaitTimeout`: If flow run goes over the timeout.

**Examples:**

Create a flow run for a deployment and wait for it to finish:

```python
import asyncio

from prefect.client.orchestration import get_client
from prefect.flow_runs import wait_for_flow_run

async def main():
    async with get_client() as client:
        flow_run = await client.create_flow_run_from_deployment(deployment_id="my-deployment-id")
        flow_run = await wait_for_flow_run(flow_run_id=flow_run.id)
        print(flow_run.state)

if __name__ == "__main__":
    asyncio.run(main())

```

Trigger multiple flow runs and wait for them to finish:

```python
import asyncio

from prefect.client.orchestration import get_client
from prefect.flow_runs import wait_for_flow_run

async def main(num_runs: int):
    async with get_client() as client:
        flow_runs = [
            await client.create_flow_run_from_deployment(deployment_id="my-deployment-id")
            for _
            in range(num_runs)
        ]
        coros = [wait_for_flow_run(flow_run_id=flow_run.id) for flow_run in flow_runs]
        finished_flow_runs = await asyncio.gather(*coros)
        print([flow_run.state for flow_run in finished_flow_runs])

if __name__ == "__main__":
    asyncio.run(main(num_runs=10))

```

### `pause_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_runs.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause_flow_run(wait_for_input: Type[T] | None = None, timeout: int = 3600, poll_interval: int = 10, key: str | None = None) -> T | None
```

Pauses the current flow run by blocking execution until resumed.

When called within a flow run, execution will block and no downstream tasks will
run until the flow is resumed. Task runs that have already started will continue
running. A timeout parameter can be passed that will fail the flow run if it has not
been resumed within the specified time.

**Args:**

* `timeout`: the number of seconds to wait for the flow to be resumed before
  failing. Defaults to 1 hour (3600 seconds). If the pause timeout exceeds
  any configured flow-level timeout, the flow might fail even after resuming.
* `poll_interval`: The number of seconds between checking whether the flow has been
  resumed. Defaults to 10 seconds.
* `key`: An optional key to prevent calling pauses more than once. This defaults to
  the number of pauses observed by the flow so far, and prevents pauses that
  use the "reschedule" option from running the same pause twice. A custom key
  can be supplied for custom pausing behavior.
* `wait_for_input`: a subclass of `RunInput` or any type supported by
  Pydantic. If provided when the flow pauses, the flow will wait for the
  input to be provided before resuming. If the flow is resumed without
  providing the input, the flow will fail. If the flow is resumed with the
  input, the flow will resume and the input will be loaded and returned
  from this function.

Example:

```python
@task
def task_one():
    for i in range(3):
        sleep(1)

@flow
def my_flow():
    terminal_state = task_one.submit(return_state=True)
    if terminal_state.type == StateType.COMPLETED:
        print("Task one succeeded! Pausing flow run..")
        pause_flow_run(timeout=2)
    else:
        print("Task one failed. Skipping pause flow run..")
```

### `suspend_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_runs.py#L356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
suspend_flow_run(wait_for_input: Type[T] | None = None, flow_run_id: UUID | None = None, timeout: int | None = 3600, key: str | None = None, client: 'PrefectClient | None' = None) -> T | None
```

Suspends a flow run by stopping code execution until resumed.

When suspended, the flow run will continue execution until the NEXT task is
orchestrated, at which point the flow will exit. Any tasks that have
already started will run until completion. When resumed, the flow run will
be rescheduled to finish execution. In order suspend a flow run in this
way, the flow needs to have an associated deployment and results need to be
configured with the `persist_result` option.

**Args:**

* `flow_run_id`: a flow run id. If supplied, this function will attempt to
  suspend the specified flow run. If not supplied will attempt to
  suspend the current flow run.
* `timeout`: the number of seconds to wait for the flow to be resumed before
  failing. Defaults to 1 hour (3600 seconds). If the pause timeout
  exceeds any configured flow-level timeout, the flow might fail even
  after resuming.
* `key`: An optional key to prevent calling suspend more than once. This
  defaults to a random string and prevents suspends from running the
  same suspend twice. A custom key can be supplied for custom
  suspending behavior.
* `wait_for_input`: a subclass of `RunInput` or any type supported by
  Pydantic. If provided when the flow suspends, the flow will remain
  suspended until receiving the input before resuming. If the flow is
  resumed without providing the input, the flow will fail. If the flow is
  resumed with the input, the flow will resume and the input will be
  loaded and returned from this function.

### `resume_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flow_runs.py#L464" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_flow_run(flow_run_id: UUID, run_input: dict[str, Any] | None = None) -> None
```

Resumes a paused flow.

**Args:**

* `flow_run_id`: the flow\_run\_id to resume
* `run_input`: a dictionary of inputs to provide to the flow run.


# flows
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-flows



# `prefect.flows`

Module containing the base workflow class and decorator - for most use cases, using the `@flow` decorator is preferred.

## Functions

### `bind_flow_to_infrastructure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2394" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bind_flow_to_infrastructure(flow: Flow[P, R], work_pool: str, worker_cls: type['BaseWorker[Any, Any, Any]'], job_variables: dict[str, Any] | None = None) -> InfrastructureBoundFlow[P, R]
```

### `select_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2429" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
select_flow(flows: Iterable[Flow[P, R]], flow_name: Optional[str] = None, from_message: Optional[str] = None) -> Flow[P, R]
```

Select the only flow in an iterable or a flow specified by name.

Returns
A single flow object

**Raises:**

* `MissingFlowError`: If no flows exist in the iterable
* `MissingFlowError`: If a flow name is provided and that flow does not exist
* `UnspecifiedFlowError`: If multiple flows exist but no flow name was provided

### `load_flow_from_entrypoint` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2475" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_flow_from_entrypoint(entrypoint: str, use_placeholder_flow: bool = True) -> Flow[P, Any]
```

Extract a flow object from a script at an entrypoint by running all of the code in the file.

**Args:**

* `entrypoint`: a string in the format `<path_to_script>\:<flow_func_name>`
  or a string in the format `<path_to_script>\:<class_name>.<flow_method_name>`
  or a module path to a flow function
* `use_placeholder_flow`: if True, use a placeholder Flow object if the actual flow object
  cannot be loaded from the entrypoint (e.g. dependencies are missing)

**Returns:**

* The flow object from the script

**Raises:**

* `ScriptError`: If an exception is encountered while running the script
* `MissingFlowError`: If the flow function specified in the entrypoint does not exist

### `load_function_and_convert_to_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2527" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_function_and_convert_to_flow(entrypoint: str) -> Flow[P, Any]
```

Loads a function from an entrypoint and converts it to a flow if it is not already a flow.

### `serve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2550" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve(*args: 'RunnerDeployment', **kwargs: Any) -> None
```

Serve the provided list of deployments.

**Args:**

* `*args`: A list of deployments to serve.
* `pause_on_shutdown`: A boolean for whether or not to automatically pause
  deployment schedules on shutdown.
* `print_starting_message`: Whether or not to print message to the console
  on startup.
* `limit`: The maximum number of runs that can be executed concurrently.
* `**kwargs`: Additional keyword arguments to pass to the runner.

**Examples:**

Prepare two deployments and serve them:

```python
import datetime

from prefect import flow, serve

@flow
def my_flow(name):
    print(f"hello {name}")

@flow
def my_other_flow(name):
    print(f"goodbye {name}")

if __name__ == "__main__":
    # Run once a day
    hello_deploy = my_flow.to_deployment(
        "hello", tags=["dev"], interval=datetime.timedelta(days=1)
    )

    # Run every Sunday at 4:00 AM
    bye_deploy = my_other_flow.to_deployment(
        "goodbye", tags=["dev"], cron="0 4 * * sun"
    )

    serve(hello_deploy, bye_deploy)
```

### `aserve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2628" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aserve(*args: 'RunnerDeployment', **kwargs: Any) -> None
```

Asynchronously serve the provided list of deployments.

Use `serve` instead if calling from a synchronous context.

**Args:**

* `*args`: A list of deployments to serve.
* `pause_on_shutdown`: A boolean for whether or not to automatically pause
  deployment schedules on shutdown.
* `print_starting_message`: Whether or not to print message to the console
  on startup.
* `limit`: The maximum number of runs that can be executed concurrently.
* `**kwargs`: Additional keyword arguments to pass to the runner.

**Examples:**

Prepare deployment and asynchronous initialization function and serve them:

````python
import asyncio
import datetime

from prefect import flow, aserve, get_client


async def init():
    await set_concurrency_limit()


async def set_concurrency_limit():
    async with get_client() as client:
        await client.create_concurrency_limit(tag='dev', concurrency_limit=3)


@flow
async def my_flow(name):
    print(f"hello {name}")


async def main():
    # Initialization function
    await init()

    # Run once a day
    hello_deploy = await my_flow.to_deployment(
        "hello", tags=["dev"], interval=datetime.timedelta(days=1)
    )

    await aserve(hello_deploy)


if __name__ == "__main__":
    asyncio.run(main())


### `load_flow_from_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2736" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_flow_from_flow_run(client: 'PrefectClient', flow_run: 'FlowRun', ignore_storage: bool = False, storage_base_path: Optional[str] = None, use_placeholder_flow: bool = True) -> Flow[..., Any]
````

Load a flow from the location/script provided in a deployment's storage document.

If `ignore_storage=True` is provided, no pull from remote storage occurs.  This flag
is largely for testing, and assumes the flow is already available locally.

### `load_placeholder_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2840" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_placeholder_flow(entrypoint: str, raises: Exception) -> Flow[P, Any]
```

Load a placeholder flow that is initialized with the same arguments as the
flow specified in the entrypoint. If called the flow will raise `raises`.

This is useful when a flow can't be loaded due to missing dependencies or
other issues but the base metadata defining the flow is still needed.

**Args:**

* `entrypoint`: a string in the format `<path_to_script>\:<flow_func_name>`
  or a module path to a flow function
* `raises`: an exception to raise when the flow is called

### `safe_load_flow_from_entrypoint` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2875" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
safe_load_flow_from_entrypoint(entrypoint: str) -> Optional[Flow[P, Any]]
```

Safely load a Prefect flow from an entrypoint string. Returns None if loading fails.

**Args:**

* `entrypoint`: A string identifying the flow to load. Can be in one of the following formats:
* `<path_to_script>\:<flow_func_name>`
* `<path_to_script>\:<class_name>.<flow_method_name>`
* `<module_path>.<flow_func_name>`

**Returns:**

* Optional\[Flow]: The loaded Prefect flow object, or None if loading fails due to errors
* (e.g. unresolved dependencies, syntax errors, or missing objects).

### `load_flow_arguments_from_entrypoint` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L3045" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_flow_arguments_from_entrypoint(entrypoint: str, arguments: Optional[Union[list[str], set[str]]] = None) -> dict[str, Any]
```

Extract flow arguments from an entrypoint string.

Loads the source code of the entrypoint and extracts the flow arguments
from the `flow` decorator.

**Args:**

* `entrypoint`: a string in the format `<path_to_script>\:<flow_func_name>`
  or a module path to a flow function

### `is_entrypoint_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L3125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_entrypoint_async(entrypoint: str) -> bool
```

Determine if the function specified in the entrypoint is asynchronous.

**Args:**

* `entrypoint`: A string in the format `<path_to_script>\:<func_name>` or
  a module path to a function.

**Returns:**

* True if the function is asynchronous, False otherwise.

## Classes

### `FlowStateHook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A callable that is invoked when a flow enters a given state.

### `Flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect workflow definition.

Wraps a function with an entrypoint to the Prefect engine. To preserve the input
and output types, we use the generic type variables `P` and `R` for "Parameters" and
"Returns" respectively.

**Args:**

* `fn`: The function defining the workflow.
* `name`: An optional name for the flow; if not provided, the name will be inferred
  from the given function.
* `version`: An optional version string for the flow; if not provided, we will
  attempt to create a version string as a hash of the file containing the
  wrapped function; if the file cannot be located, the version will be null.
* `flow_run_name`: An optional name to distinguish runs of this flow; this name can
  be provided as a string template with the flow's parameters as variables,
  or a function that returns a string.
* `task_runner`: An optional task runner to use for task execution within the flow;
  if not provided, a `ThreadPoolTaskRunner` will be used.
* `description`: An optional string description for the flow; if not provided, the
  description will be pulled from the docstring for the decorated function.
* `timeout_seconds`: An optional number of seconds indicating a maximum runtime for
  the flow. If the flow exceeds this runtime, it will be marked as failed.
  Flow execution may continue until the next task is called.
* `validate_parameters`: By default, parameters passed to flows are validated by
  Pydantic. This will check that input values conform to the annotated types
  on the function. Where possible, values will be coerced into the correct
  type; for example, if a parameter is defined as `x\: int` and "5" is passed,
  it will be resolved to `5`. If set to `False`, no validation will be
  performed on flow parameters.
* `retries`: An optional number of times to retry on flow run failure.
* `retry_delay_seconds`: An optional number of seconds to wait before retrying the
  flow after failure. This is only applicable if `retries` is nonzero.
* `persist_result`: An optional toggle indicating whether the result of this flow
  should be persisted to result storage. Defaults to `None`, which indicates
  that Prefect should choose whether the result should be persisted depending on
  the features being used.
* `result_storage`: An optional block to use to persist the result of this flow.
  This value will be used as the default for any tasks in this flow.
  If not provided, the local file system will be used unless called as
  a subflow, at which point the default will be loaded from the parent flow.
* `result_serializer`: An optional serializer to use to serialize the result of this
  flow for persistence. This value will be used as the default for any tasks
  in this flow. If not provided, the value of `PREFECT_RESULTS_DEFAULT_SERIALIZER`
  will be used unless called as a subflow, at which point the default will be
  loaded from the parent flow.
* `on_failure`: An optional list of callables to run when the flow enters a failed state.
* `on_completion`: An optional list of callables to run when the flow enters a completed state.
* `on_cancellation`: An optional list of callables to run when the flow enters a cancelling state.
* `on_crashed`: An optional list of callables to run when the flow enters a crashed state.
* `on_running`: An optional list of callables to run when the flow enters a running state.

**Methods:**

#### `afrom_source` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L1153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
afrom_source(cls, source: Union[str, Path, 'RunnerStorage', ReadableDeploymentStorage], entrypoint: str) -> 'Flow[..., Any]'
```

Loads a flow from a remote source asynchronously.

**Args:**

* `source`: Either a URL to a git repository or a storage object.
* `entrypoint`: The path to a file containing a flow and the name of the flow function in
  the format `./path/to/file.py\:flow_func_name`.

**Returns:**

* A new `Flow` instance.

**Examples:**

Load a flow from a public git repository:

```python
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect.blocks.system import Secret

my_flow = flow.from_source(
    source="https://github.com/org/repo.git",
    entrypoint="flows.py:my_flow",
)

my_flow()
```

Load a flow from a private git repository using an access token stored in a `Secret` block:

```python
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect.blocks.system import Secret

my_flow = flow.from_source(
    source=GitRepository(
        url="https://github.com/org/repo.git",
        credentials={"access_token": Secret.load("github-access-token")}
    ),
    entrypoint="flows.py:my_flow",
)

my_flow()
```

Load a flow from a local directory:

```python
# from_local_source.py

from pathlib import Path
from prefect import flow

@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a Python script!")

if __name__ == "__main__":
    my_flow.from_source(
        source=str(Path(__file__).parent),
        entrypoint="from_local_source.py:my_flow",
    ).deploy(
        name="my-deployment",
        parameters=dict(name="Marvin"),
        work_pool_name="local",
    )
```

#### `ato_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L693" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ato_deployment(self, name: str, interval: Optional[Union[Iterable[Union[int, float, datetime.timedelta]], int, float, datetime.timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, parameters: Optional[dict[str, Any]] = None, triggers: Optional[list[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, description: Optional[str] = None, tags: Optional[list[str]] = None, version: Optional[str] = None, version_type: Optional[VersionType] = None, enforce_parameter_schema: bool = True, work_pool_name: Optional[str] = None, work_queue_name: Optional[str] = None, job_variables: Optional[dict[str, Any]] = None, entrypoint_type: EntrypointType = EntrypointType.FILE_PATH, _sla: Optional[Union[SlaTypes, list[SlaTypes]]] = None) -> 'RunnerDeployment'
```

Asynchronously creates a runner deployment object for this flow.

**Args:**

* `name`: The name to give the created deployment.
* `interval`: An interval on which to execute the new deployment. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `cron`: A cron schedule of when to execute runs of this deployment.
* `rrule`: An rrule schedule of when to execute runs of this deployment.
* `paused`: Whether or not to set this deployment as paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to define multiple schedules or additional scheduling options such as `timezone`.
* `concurrency_limit`: The maximum number of runs of this deployment that can run at the same time.
* `parameters`: A dictionary of default parameter values to pass to runs of this deployment.
* `triggers`: A list of triggers that will kick off runs of this deployment.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `version_type`: The type of version to use for the created deployment. The version type
  will be inferred if not provided.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for the created deployment.
* `work_pool_name`: The name of the work pool to use for this deployment.
* `work_queue_name`: The name of the work queue to use for this deployment's scheduled runs.
  If not provided the default work queue for the work pool will be used.
* `job_variables`: Settings used to override the values specified default base job template
  of the chosen work pool. Refer to the base job template of the chosen work pool for
* `entrypoint_type`: Type of entrypoint to use for the deployment. When using a module path
  entrypoint, ensure that the module will be importable in the execution environment.
* `_sla`: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.

**Examples:**

Prepare two deployments and serve them:

```python
from prefect import flow, serve

@flow
def my_flow(name):
    print(f"hello {name}")

@flow
def my_other_flow(name):
    print(f"goodbye {name}")

if __name__ == "__main__":
    hello_deploy = my_flow.to_deployment("hello", tags=["dev"])
    bye_deploy = my_other_flow.to_deployment("goodbye", tags=["dev"])
    serve(hello_deploy, bye_deploy)
```

#### `deploy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L1375" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deploy(self, name: str, work_pool_name: Optional[str] = None, image: Optional[Union[str, 'DockerImage']] = None, build: bool = True, push: bool = True, work_queue_name: Optional[str] = None, job_variables: Optional[dict[str, Any]] = None, interval: Optional[Union[int, float, datetime.timedelta]] = None, cron: Optional[str] = None, rrule: Optional[str] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional[list[Schedule]] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, triggers: Optional[list[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, parameters: Optional[dict[str, Any]] = None, description: Optional[str] = None, tags: Optional[list[str]] = None, version: Optional[str] = None, version_type: Optional[VersionType] = None, enforce_parameter_schema: bool = True, entrypoint_type: EntrypointType = EntrypointType.FILE_PATH, print_next_steps: bool = True, ignore_warnings: bool = False, _sla: Optional[Union[SlaTypes, list[SlaTypes]]] = None) -> UUID
```

Deploys a flow to run on dynamic infrastructure via a work pool.

By default, calling this method will build a Docker image for the flow, push it to a registry,
and create a deployment via the Prefect API that will run the flow on the given schedule.

If you want to use an existing image, you can pass `build=False` to skip building and pushing
an image.

**Args:**

* `name`: The name to give the created deployment.
* `work_pool_name`: The name of the work pool to use for this deployment. Defaults to
  the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.
* `image`: The name of the Docker image to build, including the registry and
  repository. Pass a DockerImage instance to customize the Dockerfile used
  and build arguments.
* `build`: Whether or not to build a new image for the flow. If False, the provided
  image will be used as-is and pulled at runtime.
* `push`: Whether or not to skip pushing the built image to a registry.
* `work_queue_name`: The name of the work queue to use for this deployment's scheduled runs.
  If not provided the default work queue for the work pool will be used.
* `job_variables`: Settings used to override the values specified default base job template
  of the chosen work pool. Refer to the base job template of the chosen work pool for
  available settings.
* `interval`: An interval on which to execute the deployment. Accepts a number or a
  timedelta object to create a single schedule. If a number is given, it will be
  interpreted as seconds. Also accepts an iterable of numbers or timedelta to create
  multiple schedules.
* `cron`: A cron schedule string of when to execute runs of this deployment.
  Also accepts an iterable of cron schedule strings to create multiple schedules.
* `rrule`: An rrule schedule string of when to execute runs of this deployment.
  Also accepts an iterable of rrule schedule strings to create multiple schedules.
* `triggers`: A list of triggers that will kick off runs of this deployment.
* `paused`: Whether or not to set this deployment as paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to define multiple schedules or additional scheduling options like `timezone`.
* `concurrency_limit`: The maximum number of runs that can be executed concurrently.
* `parameters`: A dictionary of default parameter values to pass to runs of this deployment.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `version_type`: The type of version to use for the created deployment. The version type
  will be inferred if not provided.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for the created deployment.
* `entrypoint_type`: Type of entrypoint to use for the deployment. When using a module path
  entrypoint, ensure that the module will be importable in the execution environment.
* `print_next_steps_message`: Whether or not to print a message with next steps
  after deploying the deployments.
* `ignore_warnings`: Whether or not to ignore warnings about the work pool type.
* `_sla`: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.

Returns:
The ID of the created/updated deployment.

**Examples:**

Deploy a local flow to a work pool:

```python
from prefect import flow

@flow
def my_flow(name):
    print(f"hello {name}")

if __name__ == "__main__":
    my_flow.deploy(
        "example-deployment",
        work_pool_name="my-work-pool",
        image="my-repository/my-image:dev",
    )
```

Deploy a remotely stored flow to a work pool:

```python
from prefect import flow

if __name__ == "__main__":
    flow.from_source(
        source="https://github.com/org/repo.git",
        entrypoint="flows.py:my_flow",
    ).deploy(
        "example-deployment",
        work_pool_name="my-work-pool",
        image="my-repository/my-image:dev",
    )
```

#### `from_source` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L1267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_source(cls, source: Union[str, Path, 'RunnerStorage', ReadableDeploymentStorage], entrypoint: str) -> 'Flow[..., Any]'
```

Loads a flow from a remote source.

**Args:**

* `source`: Either a URL to a git repository or a storage object.
* `entrypoint`: The path to a file containing a flow and the name of the flow function in
  the format `./path/to/file.py\:flow_func_name`.

**Returns:**

* A new `Flow` instance.

**Examples:**

Load a flow from a public git repository:

```python
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect.blocks.system import Secret

my_flow = flow.from_source(
    source="https://github.com/org/repo.git",
    entrypoint="flows.py:my_flow",
)

my_flow()
```

Load a flow from a private git repository using an access token stored in a `Secret` block:

```python
from prefect import flow
from prefect.runner.storage import GitRepository
from prefect.blocks.system import Secret

my_flow = flow.from_source(
    source=GitRepository(
        url="https://github.com/org/repo.git",
        credentials={"access_token": Secret.load("github-access-token")}
    ),
    entrypoint="flows.py:my_flow",
)

my_flow()
```

Load a flow from a local directory:

```python
# from_local_source.py

from pathlib import Path
from prefect import flow

@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a Python script!")

if __name__ == "__main__":
    my_flow.from_source(
        source=str(Path(__file__).parent),
        entrypoint="from_local_source.py:my_flow",
    ).deploy(
        name="my-deployment",
        parameters=dict(name="Marvin"),
        work_pool_name="local",
    )
```

#### `isclassmethod` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L412" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
isclassmethod(self) -> bool
```

#### `ismethod` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L408" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ismethod(self) -> bool
```

#### `isstaticmethod` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
isstaticmethod(self) -> bool
```

#### `on_cancellation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L982" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_cancellation(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]
```

#### `on_completion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L978" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_completion(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]
```

#### `on_crashed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L986" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_crashed(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]
```

#### `on_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_failure(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]
```

#### `on_running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L990" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_running(self, fn: FlowStateHook[P, R]) -> FlowStateHook[P, R]
```

#### `serialize_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L656" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize_parameters(self, parameters: dict[str, Any | PrefectFuture[Any] | State]) -> dict[str, Any]
```

Convert parameters to a serializable form.

Uses FastAPI's `jsonable_encoder` to convert to JSON compatible objects without
converting everything directly to a string. This maintains basic types like
integers during API roundtrips.

#### `serve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L998" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve(self, name: Optional[str] = None, interval: Optional[Union[Iterable[Union[int, float, datetime.timedelta]], int, float, datetime.timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, global_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, triggers: Optional[list[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, parameters: Optional[dict[str, Any]] = None, description: Optional[str] = None, tags: Optional[list[str]] = None, version: Optional[str] = None, enforce_parameter_schema: bool = True, pause_on_shutdown: bool = True, print_starting_message: bool = True, limit: Optional[int] = None, webserver: bool = False, entrypoint_type: EntrypointType = EntrypointType.FILE_PATH) -> None
```

Creates a deployment for this flow and starts a runner to monitor for scheduled work.

**Args:**

* `name`: The name to give the created deployment. Defaults to the name of the flow.
* `interval`: An interval on which to execute the deployment. Accepts a number or a
  timedelta object to create a single schedule. If a number is given, it will be
  interpreted as seconds. Also accepts an iterable of numbers or timedelta to create
  multiple schedules.
* `cron`: A cron schedule string of when to execute runs of this deployment.
  Also accepts an iterable of cron schedule strings to create multiple schedules.
* `rrule`: An rrule schedule string of when to execute runs of this deployment.
  Also accepts an iterable of rrule schedule strings to create multiple schedules.
* `triggers`: A list of triggers that will kick off runs of this deployment.
* `paused`: Whether or not to set this deployment as paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to define multiple schedules or additional scheduling options like `timezone`.
* `global_limit`: The maximum number of concurrent runs allowed across all served flow instances associated with the same deployment.
* `parameters`: A dictionary of default parameter values to pass to runs of this deployment.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for the created deployment.
* `pause_on_shutdown`: If True, provided schedule will be paused when the serve function is stopped.
  If False, the schedules will continue running.
* `print_starting_message`: Whether or not to print the starting message when flow is served.
* `limit`: The maximum number of runs that can be executed concurrently by the created runner; only applies to this served flow. To apply a limit across multiple served flows, use `global_limit`.
* `webserver`: Whether or not to start a monitoring webserver for this flow.
* `entrypoint_type`: Type of entrypoint to use for the deployment. When using a module path
  entrypoint, ensure that the module will be importable in the execution environment.

**Examples:**

Serve a flow:

```python
from prefect import flow

@flow
def my_flow(name):
    print(f"hello {name}")

if __name__ == "__main__":
    my_flow.serve("example-deployment")
```

Serve a flow and run it every hour:

```python
from prefect import flow

@flow
def my_flow(name):
    print(f"hello {name}")

if __name__ == "__main__":
    my_flow.serve("example-deployment", interval=3600)
```

#### `to_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L834" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_deployment(self, name: str, interval: Optional[Union[Iterable[Union[int, float, datetime.timedelta]], int, float, datetime.timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, parameters: Optional[dict[str, Any]] = None, triggers: Optional[list[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, description: Optional[str] = None, tags: Optional[list[str]] = None, version: Optional[str] = None, version_type: Optional[VersionType] = None, enforce_parameter_schema: bool = True, work_pool_name: Optional[str] = None, work_queue_name: Optional[str] = None, job_variables: Optional[dict[str, Any]] = None, entrypoint_type: EntrypointType = EntrypointType.FILE_PATH, _sla: Optional[Union[SlaTypes, list[SlaTypes]]] = None) -> 'RunnerDeployment'
```

Creates a runner deployment object for this flow.

**Args:**

* `name`: The name to give the created deployment.
* `interval`: An interval on which to execute the new deployment. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `cron`: A cron schedule of when to execute runs of this deployment.
* `rrule`: An rrule schedule of when to execute runs of this deployment.
* `paused`: Whether or not to set this deployment as paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this deployment.
  Used to define multiple schedules or additional scheduling options such as `timezone`.
* `concurrency_limit`: The maximum number of runs of this deployment that can run at the same time.
* `parameters`: A dictionary of default parameter values to pass to runs of this deployment.
* `triggers`: A list of triggers that will kick off runs of this deployment.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `version_type`: The type of version to use for the created deployment. The version type
  will be inferred if not provided.
* `enforce_parameter_schema`: Whether or not the Prefect API should enforce the
  parameter schema for the created deployment.
* `work_pool_name`: The name of the work pool to use for this deployment.
* `work_queue_name`: The name of the work queue to use for this deployment's scheduled runs.
  If not provided the default work queue for the work pool will be used.
* `job_variables`: Settings used to override the values specified default base job template
  of the chosen work pool. Refer to the base job template of the chosen work pool for
* `entrypoint_type`: Type of entrypoint to use for the deployment. When using a module path
  entrypoint, ensure that the module will be importable in the execution environment.
* `_sla`: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.

**Examples:**

Prepare two deployments and serve them:

```python
from prefect import flow, serve

@flow
def my_flow(name):
    print(f"hello {name}")

@flow
def my_other_flow(name):
    print(f"goodbye {name}")

if __name__ == "__main__":
    hello_deploy = my_flow.to_deployment("hello", tags=["dev"])
    bye_deploy = my_other_flow.to_deployment("goodbye", tags=["dev"])
    serve(hello_deploy, bye_deploy)
```

#### `validate_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_parameters(self, parameters: dict[str, Any]) -> dict[str, Any]
```

Validate parameters for compatibility with the flow by attempting to cast the inputs to the
associated types specified by the function's type annotations.

**Returns:**

* A new dict of parameters that have been cast to the appropriate types

**Raises:**

* `ParameterTypeError`: if the provided parameters are not valid

#### `visualize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L1710" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
visualize(self, *args: 'P.args', **kwargs: 'P.kwargs')
```

Generates a graphviz object representing the current flow. In IPython notebooks,
it's rendered inline, otherwise in a new window as a PNG.

**Raises:**

* `- ImportError`: If `graphviz` isn't installed.
* `- GraphvizExecutableNotFoundError`: If the `dot` executable isn't found.
* `- FlowVisualizationError`: If the flow can't be visualized for any other reason.

#### `with_options` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L440" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_options(self) -> 'Flow[P, R]'
```

Create a new flow from the current object, updating provided options.

**Args:**

* `name`: A new name for the flow.
* `version`: A new version for the flow.
* `description`: A new description for the flow.
* `flow_run_name`: An optional name to distinguish runs of this flow; this name
  can be provided as a string template with the flow's parameters as variables,
  or a function that returns a string.
* `task_runner`: A new task runner for the flow.
* `timeout_seconds`: A new number of seconds to fail the flow after if still
  running.
* `validate_parameters`: A new value indicating if flow calls should validate
  given parameters.
* `retries`: A new number of times to retry on flow run failure.
* `retry_delay_seconds`: A new number of seconds to wait before retrying the
  flow after failure. This is only applicable if `retries` is nonzero.
* `persist_result`: A new option for enabling or disabling result persistence.
* `result_storage`: A new storage type to use for results.
* `result_serializer`: A new serializer to use for results.
* `cache_result_in_memory`: A new value indicating if the flow's result should
  be cached in memory.
* `on_failure`: A new list of callables to run when the flow enters a failed state.
* `on_completion`: A new list of callables to run when the flow enters a completed state.
* `on_cancellation`: A new list of callables to run when the flow enters a cancelling state.
* `on_crashed`: A new list of callables to run when the flow enters a crashed state.
* `on_running`: A new list of callables to run when the flow enters a running state.

**Returns:**

* A new `Flow` instance.

Examples:

Create a new flow from an existing flow and update the name:

```python
from prefect import flow

@flow(name="My flow")
def my_flow():
    return 1

new_flow = my_flow.with_options(name="My new flow")
```

Create a new flow from an existing flow, update the task runner, and call
it without an intermediate variable:

```python
from prefect.task_runners import ThreadPoolTaskRunner

@flow
def my_flow(x, y):
    return x + y

state = my_flow.with_options(task_runner=ThreadPoolTaskRunner)(1, 3)
assert state.result() == 4
```

### `FlowDecorator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L1769" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `InfrastructureBoundFlow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2029" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A flow that is bound to running on a specific infrastructure.

**Methods:**

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, *args: P.args, **kwargs: P.kwargs) -> PrefectFlowRunFuture[R]
```

Submit the flow to run on remote infrastructure.

This method will spin up a local worker to submit the flow to remote infrastructure. To
submit the flow to remote infrastructure without spinning up a local worker, use
`submit_to_work_pool` instead.

**Args:**

* `*args`: Positional arguments to pass to the flow.
* `**kwargs`: Keyword arguments to pass to the flow.

**Returns:**

* A `PrefectFlowRunFuture` that can be used to retrieve the result of the flow run.

**Examples:**

Submit a flow to run on Kubernetes:

```python
from prefect import flow
from prefect_kubernetes.experimental import kubernetes

@kubernetes(work_pool="my-kubernetes-work-pool")
@flow
def my_flow(x: int, y: int):
    return x + y

future = my_flow.submit(x=1, y=2)
result = future.result()
print(result)
```

#### `submit_to_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit_to_work_pool(self, *args: P.args, **kwargs: P.kwargs) -> PrefectFlowRunFuture[R]
```

Submits the flow to run on remote infrastructure.

This method will create a flow run for an existing worker to submit to remote infrastructure.
If you don't have a worker available, use `submit` instead.

**Args:**

* `*args`: Positional arguments to pass to the flow.
* `**kwargs`: Keyword arguments to pass to the flow.

**Returns:**

* A `PrefectFlowRunFuture` that can be used to retrieve the result of the flow run.

**Examples:**

Dispatch a flow to run on Kubernetes:

```python
from prefect import flow
from prefect_kubernetes.experimental import kubernetes

@kubernetes(work_pool="my-kubernetes-work-pool")
@flow
def my_flow(x: int, y: int):
    return x + y

future = my_flow.submit_to_work_pool(x=1, y=2)
result = future.result()
print(result)
```

#### `with_options` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py#L2336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_options(self) -> 'InfrastructureBoundFlow[P, R]'
```


# futures
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-futures



# `prefect.futures`

## Functions

### `as_completed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L506" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_completed(futures: list[PrefectFuture[R]], timeout: float | None = None) -> Generator[PrefectFuture[R], None]
```

### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L557" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(futures: list[PrefectFuture[R]], timeout: float | None = None) -> DoneAndNotDoneFutures[R]
```

Wait for the futures in the given sequence to complete.

**Args:**

* `futures`: The sequence of Futures to wait upon.
* `timeout`: The maximum number of seconds to wait. If None, then there
  is no limit on the wait time.

**Returns:**

* A named 2-tuple of sets. The first set, named 'done', contains the
* futures that completed (is finished or cancelled) before the wait
* completed. The second set, named 'not\_done', contains uncompleted
* futures. Duplicate futures given to *futures* are removed and will be
* returned only once.

**Examples:**

```python
@task
def sleep_task(seconds):
    sleep(seconds)
    return 42

@flow
def flow():
    futures = random_task.map(range(10))
    done, not_done = wait(futures, timeout=5)
    print(f"Done: {len(done)}")
    print(f"Not Done: {len(not_done)}")
```

### `resolve_futures_to_states` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L641" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_futures_to_states(expr: PrefectFuture[R] | Any) -> PrefectFuture[R] | Any
```

Given a Python built-in collection, recursively find `PrefectFutures` and build a
new collection with the same structure with futures resolved to their final states.
Resolving futures to their final states may wait for execution to complete.

Unsupported object types will be returned without modification.

### `resolve_futures_to_results` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L662" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_futures_to_results(expr: PrefectFuture[R] | Any) -> Any
```

Given a Python built-in collection, recursively find `PrefectFutures` and build a
new collection with the same structure with futures resolved to their final results.
Resolving futures to their final result may wait for execution to complete.

Unsupported object types will be returned without modification.

## Classes

### `PrefectFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Abstract base class for Prefect futures. A Prefect future is a handle to the
asynchronous execution of a run. It provides methods to wait for the
to complete and to retrieve the result of the run.

**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[['PrefectFuture[R]'], None]) -> None
```

Add a callback to be run when the future completes or is cancelled.

**Args:**

* `fn`: A callable that will be called with this future as its only argument when the future completes or is cancelled.

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

The current state of the task run associated with this future

#### `task_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_id(self) -> uuid.UUID
```

The ID of the task run associated with this future

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

### `PrefectTaskRunFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect future that represents the eventual execution of a task run.

**Methods:**

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

The current state of the task run associated with this future

#### `task_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_id(self) -> uuid.UUID
```

The ID of the task run associated with this future

### `PrefectWrappedFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect future that wraps another future object.

**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None
```

Add a callback to be executed when the future completes.

#### `wrapped_future` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wrapped_future(self) -> F
```

The underlying future object wrapped by this Prefect future

### `PrefectConcurrentFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect future that wraps a concurrent.futures.Future. This future is used
when the task run is submitted to a ThreadPoolExecutor.

**Methods:**

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

### `PrefectDistributedFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents the result of a computation happening anywhere.

This class is typically used to interact with the result of a task run
scheduled to run in a Prefect task worker but can be used to interact with
any task run scheduled in Prefect's API.

**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `result_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result_async(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

#### `wait_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_async(self, timeout: float | None = None) -> None
```

### `PrefectFlowRunFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect future that represents the eventual execution of a flow run.

**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None
```

#### `aresult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aresult(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `flow_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_id(self) -> uuid.UUID
```

The ID of the flow run associated with this future

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

The current state of the flow run associated with this future

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

#### `wait_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_async(self, timeout: float | None = None) -> None
```

### `PrefectFutureList` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L455" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A list of Prefect futures.

This class provides methods to wait for all futures
in the list to complete and to retrieve the results of all task runs.

**Methods:**

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L473" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self: Self, timeout: float | None = None, raise_on_failure: bool = True) -> list[R]
```

Get the results of all task runs associated with the futures in the list.

**Args:**

* `timeout`: The maximum number of seconds to wait for all futures to
  complete.
* `raise_on_failure`: If `True`, an exception will be raised if any task run fails.

**Returns:**

* A list of results of the task runs.

**Raises:**

* `TimeoutError`: If the timeout is reached before all futures complete.

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L463" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

Wait for all futures in the list to complete.

**Args:**

* `timeout`: The maximum number of seconds to wait for all futures to
  complete. This method will not raise if the timeout is reached.

### `DoneAndNotDoneFutures` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A named 2-tuple of sets.

multiple inheritance supported in 3.11+, use typing\_extensions.NamedTuple


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-__init__



# `prefect.infrastructure`

2024-06-27: This surfaces an actionable error message for moved or removed objects in Prefect 3.0 upgrade.


# base
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-base



# `prefect.infrastructure.base`

2024-06-27: This surfaces an actionable error message for moved or removed objects in Prefect 3.0 upgrade.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-provisioners-__init__



# `prefect.infrastructure.provisioners`

## Functions

### `get_infrastructure_provisioner_for_work_pool_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/__init__.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_infrastructure_provisioner_for_work_pool_type(work_pool_type: str) -> Type[Provisioner]
```

Retrieve an instance of the infrastructure provisioner for the given work pool type.

**Args:**

* `work_pool_type`: the work pool type

**Returns:**

* an instance of the infrastructure provisioner for the given work pool type

**Raises:**

* `ValueError`: if the work pool type is not supported

## Classes

### `Provisioner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/__init__.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/__init__.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self) -> rich.console.Console
```

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/__init__.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self, value: rich.console.Console) -> None
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/__init__.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, work_pool_name: str, base_job_template: Dict[str, Any], client: Optional['PrefectClient'] = None) -> Dict[str, Any]
```


# cloud_run
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-provisioners-cloud_run



# `prefect.infrastructure.provisioners.cloud_run`

## Classes

### `CloudRunPushProvisioner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/cloud_run.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/cloud_run.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self) -> Console
```

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/cloud_run.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self, value: Console) -> None
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/cloud_run.py#L299" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, work_pool_name: str, base_job_template: dict, client: Optional['PrefectClient'] = None) -> Dict[str, Any]
```


# coiled
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-provisioners-coiled



# `prefect.infrastructure.provisioners.coiled`

## Classes

### `CoiledPushProvisioner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/coiled.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A infrastructure provisioner for Coiled push work pools.

**Methods:**

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/coiled.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self) -> Console
```

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/coiled.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self, value: Console) -> None
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/coiled.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, work_pool_name: str, base_job_template: Dict[str, Any], client: Optional['PrefectClient'] = None) -> Dict[str, Any]
```

Provisions resources necessary for a Coiled push work pool.

**Args:**

* `work_pool_name`: The name of the work pool to provision resources for
* `base_job_template`: The base job template to update

**Returns:**

* A copy of the provided base job template with the provisioned resources


# container_instance
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-provisioners-container_instance



# `prefect.infrastructure.provisioners.container_instance`

This module defines the ContainerInstancePushProvisioner class, which is responsible for provisioning
infrastructure using Azure Container Instances for Prefect work pools.

The ContainerInstancePushProvisioner class provides methods for provisioning infrastructure and
interacting with Azure Container Instances.

Classes:
AzureCLI: A class to handle Azure CLI commands.
ContainerInstancePushProvisioner: A class for provisioning infrastructure using Azure Container Instances.

## Classes

### `AzureCLI` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/container_instance.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A class for executing Azure CLI commands and handling their output.

**Args:**

* `console`: A Rich console object for displaying messages.

**Methods:**

#### `run_command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/container_instance.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_command(self, command: str, success_message: Optional[str] = None, failure_message: Optional[str] = None, ignore_if_exists: bool = False, return_json: bool = False) -> str | dict[str, Any] | None
```

Runs an Azure CLI command and processes the output.

**Args:**

* `command`: The Azure CLI command to execute.
* `success_message`: Message to print on success.
* `failure_message`: Message to print on failure.
* `ignore_if_exists`: Whether to ignore errors if a resource already exists.
* `return_json`: Whether to return the output as JSON.

**Returns:**

* A tuple with two elements:
* str: Status, either 'created', 'exists', or 'error'.
* str or dict or None: The command output or None if an error occurs (depends on return\_json).

**Raises:**

* `subprocess.CalledProcessError`: If the command execution fails.
* `json.JSONDecodeError`: If output cannot be decoded as JSON when return\_json is True.

### `ContainerInstancePushProvisioner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/container_instance.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A class responsible for provisioning Azure resources and setting up a push work pool.

**Methods:**

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/container_instance.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self) -> Console
```

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/container_instance.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self, value: Console) -> None
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/container_instance.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, work_pool_name: str, base_job_template: Dict[str, Any], client: Optional['PrefectClient'] = None) -> Dict[str, Any]
```

Orchestrates the provisioning of Azure resources and setup for the push work pool.

**Args:**

* `work_pool_name`: The name of the work pool.
* `base_job_template`: The base template for job creation.
* `client`: An instance of PrefectClient. If None, it will be injected.

**Returns:**

* Dict\[str, Any]: The updated job template with necessary references and configurations.

**Raises:**

* `RuntimeError`: If client injection fails or the Azure CLI command execution fails.

#### `set_location` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/container_instance.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_location(self) -> None
```

Set the Azure resource deployment location to the default or 'eastus' on failure.

**Raises:**

* `RuntimeError`: If unable to execute the Azure CLI command.


# ecs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-provisioners-ecs



# `prefect.infrastructure.provisioners.ecs`

## Functions

### `console_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console_context(value: Console) -> Generator[None, None, None]
```

## Classes

### `IamPolicyResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents an IAM policy resource for managing ECS tasks.

**Args:**

* `policy_name`: The name of the IAM policy. Defaults to "prefect-ecs-policy".

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, policy_document: dict[str, Any], advance: Callable[[], None]) -> str
```

Provisions an IAM policy.

**Args:**

* `advance`: A callback function to indicate progress.

**Returns:**

* The ARN (Amazon Resource Name) of the created IAM policy.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self) -> bool
```

Check if this resource requires provisioning.

**Returns:**

* True if provisioning is required, False otherwise.

### `IamUserResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents an IAM user resource for managing ECS tasks.

**Args:**

* `user_name`: The desired name of the IAM user.

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L239" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L220" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, advance: Callable[[], None]) -> None
```

Provisions an IAM user.

**Args:**

* `advance`: A callback function to indicate progress.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self) -> bool
```

Check if this resource requires provisioning.

**Returns:**

* True if provisioning is required, False otherwise.

### `CredentialsBlockResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, base_job_template: Dict[str, Any], advance: Callable[[], None], client: Optional['PrefectClient'] = None)
```

Provisions an AWS credentials block.

Will generate new credentials if the block does not already exist. Updates
the `aws_credentials` variable in the job template to reference the block.

**Args:**

* `base_job_template`: The base job template.
* `advance`: A callback function to indicate progress.
* `client`: A Prefect client to use for interacting with the Prefect API.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self, client: Optional['PrefectClient'] = None) -> bool
```

### `AuthenticationResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L457" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L437" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L519" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L471" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, base_job_template: dict[str, Any], advance: Callable[[], None]) -> None
```

Provisions the authentication resources.

**Args:**

* `base_job_template`: The base job template of the work pool to provision
  infrastructure for.
* `advance`: A callback function to indicate progress.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L446" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self) -> bool
```

Check if this resource requires provisioning.

**Returns:**

* True if provisioning is required, False otherwise.

#### `resources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L425" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resources(self) -> list['ExecutionRoleResource | IamUserResource | IamPolicyResource | CredentialsBlockResource']
```

### `ClusterResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L527" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L561" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L533" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L604" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L576" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, base_job_template: dict[str, Any], advance: Callable[[], None]) -> None
```

Provisions an ECS cluster.

Will update the `cluster` variable in the job template to reference the cluster.

**Args:**

* `base_job_template`: The base job template of the work pool to provision
  infrastructure for.
* `advance`: A callback function to indicate progress.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L542" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self) -> bool
```

Check if this resource requires provisioning.

**Returns:**

* True if provisioning is required, False otherwise.

### `VpcResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L608" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L704" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L620" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L842" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L720" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, base_job_template: dict[str, Any], advance: Callable[[], None]) -> None
```

Provisions a VPC.

Chooses a CIDR block to avoid conflicting with any existing VPCs. Will update
the `vpc_id` variable in the job template to reference the VPC.

**Args:**

* `base_job_template`: The base job template of the work pool to provision
  infrastructure for.
* `advance`: A callback function to indicate progress.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L683" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self) -> bool
```

Check if this resource requires provisioning.

**Returns:**

* True if provisioning is required, False otherwise.

### `ContainerRepositoryResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L846" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L892" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L854" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L992" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str | Panel]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L907" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, base_job_template: dict[str, Any], advance: Callable[[], None]) -> None
```

Provisions an ECR repository.

**Args:**

* `base_job_template`: The base job template of the work pool to provision
  infrastructure for.
* `advance`: A callback function to indicate progress.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L875" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self) -> bool
```

Check if this resource requires provisioning.

**Returns:**

* True if provisioning is required, False otherwise.

### `ExecutionRoleResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L996" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get_planned_actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1043" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_planned_actions(self) -> List[str]
```

Returns a description of the planned actions for provisioning this resource.

**Returns:**

* Optional\[str]: A description of the planned actions for provisioning the resource,
  or None if provisioning is not required.

#### `get_task_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1014" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_count(self) -> int
```

Returns the number of tasks that will be executed to provision this resource.

**Returns:**

* The number of tasks to be provisioned.

#### `next_steps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_steps(self) -> list[str]
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1058" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, base_job_template: dict[str, Any], advance: Callable[[], None]) -> str
```

Provisions an IAM role.

**Args:**

* `base_job_template`: The base job template of the work pool to provision
  infrastructure for.
* `advance`: A callback function to indicate progress.

#### `requires_provisioning` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1023" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_provisioning(self) -> bool
```

Check if this resource requires provisioning.

**Returns:**

* True if provisioning is required, False otherwise.

### `ElasticContainerServicePushProvisioner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An infrastructure provisioner for ECS push work pools.

**Methods:**

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self) -> Console
```

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self, value: Console) -> None
```

#### `is_boto3_installed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_boto3_installed() -> bool
```

Check if boto3 is installed.

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/ecs.py#L1166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, work_pool_name: str, base_job_template: dict[str, Any]) -> dict[str, Any]
```

Provisions the infrastructure for an ECS push work pool.

**Args:**

* `work_pool_name`: The name of the work pool to provision infrastructure for.
* `base_job_template`: The base job template of the work pool to provision
  infrastructure for.

**Returns:**

* An updated copy base job template.


# modal
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-infrastructure-provisioners-modal



# `prefect.infrastructure.provisioners.modal`

## Classes

### `ModalPushProvisioner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/modal.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A infrastructure provisioner for Modal push work pools.

**Methods:**

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/modal.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self) -> Console
```

#### `console` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/modal.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
console(self, value: Console) -> None
```

#### `provision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/infrastructure/provisioners/modal.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provision(self, work_pool_name: str, base_job_template: Dict[str, Any], client: Optional['PrefectClient'] = None) -> Dict[str, Any]
```

Provisions resources necessary for a Modal push work pool.

**Args:**

* `work_pool_name`: The name of the work pool to provision resources for
* `base_job_template`: The base job template to update

**Returns:**

* A copy of the provided base job template with the provisioned resources


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-input-__init__



# `prefect.input`

*This module is empty or contains only private/internal implementations.*


# actions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-input-actions



# `prefect.input.actions`

## Functions

### `ensure_flow_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/actions.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ensure_flow_run_id(flow_run_id: Optional[UUID] = None) -> UUID
```

### `create_flow_run_input_from_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/actions.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run_input_from_model(key: str, model_instance: pydantic.BaseModel, flow_run_id: Optional[UUID] = None, sender: Optional[str] = None)
```

### `create_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/actions.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run_input(client: 'PrefectClient', key: str, value: Any, flow_run_id: Optional[UUID] = None, sender: Optional[str] = None)
```

Create a new flow run input. The given `value` will be serialized to JSON
and stored as a flow run input value.

**Args:**

* `- key`: the flow run input key
* `- value`: the flow run input value
* `- flow_run_id`: the, optional, flow run ID. If not given will
  default to pulling the flow run ID from the current context.

### `filter_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/actions.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter_flow_run_input(client: 'PrefectClient', key_prefix: str, limit: int = 1, exclude_keys: Optional[Set[str]] = None, flow_run_id: Optional[UUID] = None)
```

### `read_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/actions.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_input(client: 'PrefectClient', key: str, flow_run_id: Optional[UUID] = None) -> Any
```

Read a flow run input.

**Args:**

* `- key`: the flow run input key
* `- flow_run_id`: the flow run ID

### `delete_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/actions.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow_run_input(client: 'PrefectClient', key: str, flow_run_id: Optional[UUID] = None)
```

Delete a flow run input.

**Args:**

* `- flow_run_id`: the flow run ID
* `- key`: the flow run input key


# run_input
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-input-run_input



# `prefect.input.run_input`

This module contains functions that allow sending type-checked `RunInput` data
to flows at runtime. Flows can send back responses, establishing two-way
channels with senders. These functions are particularly useful for systems that
require ongoing data transfer or need to react to input quickly.
real-time interaction and efficient data handling. It's designed to facilitate
dynamic communication within distributed or microservices-oriented systems,
making it ideal for scenarios requiring continuous data synchronization and
processing. It's particularly useful for systems that require ongoing data
input and output.

The following is an example of two flows. One sends a random number to the
other and waits for a response. The other receives the number, squares it, and
sends the result back. The sender flow then prints the result.

Sender flow:

```python
import random
from uuid import UUID
from prefect import flow
from prefect.logging import get_run_logger
from prefect.input import RunInput

class NumberData(RunInput):
    number: int


@flow
async def sender_flow(receiver_flow_run_id: UUID):
    logger = get_run_logger()

    the_number = random.randint(1, 100)

    await NumberData(number=the_number).send_to(receiver_flow_run_id)

    receiver = NumberData.receive(flow_run_id=receiver_flow_run_id)
    squared = await receiver.next()

    logger.info(f"{the_number} squared is {squared.number}")
```

Receiver flow:

```python
import random
from uuid import UUID
from prefect import flow
from prefect.logging import get_run_logger
from prefect.input import RunInput

class NumberData(RunInput):
    number: int


@flow
async def receiver_flow():
    async for data in NumberData.receive():
        squared = data.number ** 2
        data.respond(NumberData(number=squared))
```

## Functions

### `keyset_from_paused_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keyset_from_paused_state(state: 'State') -> Keyset
```

Get the keyset for the given Paused state.

**Args:**

* `- state`: the state to get the keyset for

### `keyset_from_base_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keyset_from_base_key(base_key: str) -> Keyset
```

Get the keyset for the given base key.

**Args:**

* `- base_key`: the base key to get the keyset for

**Returns:**

* * Dict\[str, str]: the keyset

### `run_input_subclass_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_input_subclass_from_type(_type: Union[Type[R], Type[T], pydantic.BaseModel]) -> Union[Type[AutomaticRunInput[T]], Type[R]]
```

Create a new `RunInput` subclass from the given type.

### `send_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L643" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
send_input(run_input: Any, flow_run_id: UUID, sender: Optional[str] = None, key_prefix: Optional[str] = None)
```

### `receive_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L683" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
receive_input(input_type: Union[Type[R], Type[T], pydantic.BaseModel], timeout: Optional[float] = 3600, poll_interval: float = 10, raise_timeout_error: bool = False, exclude_keys: Optional[Set[str]] = None, key_prefix: Optional[str] = None, flow_run_id: Optional[UUID] = None, with_metadata: bool = False) -> Union[GetAutomaticInputHandler[T], GetInputHandler[R]]
```

## Classes

### `RunInputMetadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BaseRunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `keyset_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keyset_from_type(cls) -> Keyset
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -> Self
```

Load the run input response from the given key.

**Args:**

* `- keyset`: the keyset to load the input for
* `- flow_run_id`: the flow run ID to load the input for

#### `load_from_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_flow_run_input(cls, flow_run_input: 'FlowRunInput') -> Self
```

Load the run input from a FlowRunInput object.

**Args:**

* `- flow_run_input`: the flow run input to load the input for

#### `metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
metadata(self) -> RunInputMetadata
```

#### `respond` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
respond(self, run_input: 'RunInput', sender: Optional[str] = None, key_prefix: Optional[str] = None)
```

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None)
```

Save the run input response to the given key.

**Args:**

* `- keyset`: the keyset to save the input for
* `- flow_run_id`: the flow run ID to save the input for

#### `send_to` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
send_to(self, flow_run_id: UUID, sender: Optional[str] = None, key_prefix: Optional[str] = None)
```

#### `with_initial_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_initial_data(cls: Type[R], description: Optional[str] = None, **kwargs: Any) -> Type[R]
```

Create a new `RunInput` subclass with the given initial data as field
defaults.

**Args:**

* `- description`: a description to show when resuming
  a flow run that requires input
* `- kwargs`: the initial data to populate the subclass

### `RunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L299" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `keyset_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keyset_from_type(cls) -> Keyset
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -> Self
```

Load the run input response from the given key.

**Args:**

* `- keyset`: the keyset to load the input for
* `- flow_run_id`: the flow run ID to load the input for

#### `load_from_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_flow_run_input(cls, flow_run_input: 'FlowRunInput') -> Self
```

Load the run input from a FlowRunInput object.

**Args:**

* `- flow_run_input`: the flow run input to load the input for

#### `metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
metadata(self) -> RunInputMetadata
```

#### `receive` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
receive(cls, timeout: Optional[float] = 3600, poll_interval: float = 10, raise_timeout_error: bool = False, exclude_keys: Optional[Set[str]] = None, key_prefix: Optional[str] = None, flow_run_id: Optional[UUID] = None) -> GetInputHandler[Self]
```

#### `respond` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
respond(self, run_input: 'RunInput', sender: Optional[str] = None, key_prefix: Optional[str] = None)
```

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None)
```

Save the run input response to the given key.

**Args:**

* `- keyset`: the keyset to save the input for
* `- flow_run_id`: the flow run ID to save the input for

#### `send_to` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
send_to(self, flow_run_id: UUID, sender: Optional[str] = None, key_prefix: Optional[str] = None)
```

#### `subclass_from_base_model_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
subclass_from_base_model_type(cls, model_cls: Type[pydantic.BaseModel]) -> Type['RunInput']
```

Create a new `RunInput` subclass from the given `pydantic.BaseModel`
subclass.

**Args:**

* `- model_cls`: the class from which
  to create the new `RunInput` subclass

#### `with_initial_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_initial_data(cls: Type[R], description: Optional[str] = None, **kwargs: Any) -> Type[R]
```

Create a new `RunInput` subclass with the given initial data as field
defaults.

**Args:**

* `- description`: a description to show when resuming
  a flow run that requires input
* `- kwargs`: the initial data to populate the subclass

### `AutomaticRunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L338" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `keyset_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keyset_from_type(cls) -> Keyset
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L343" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -> Self
```

Load the run input response from the given key.

**Args:**

* `- keyset`: the keyset to load the input for
* `- flow_run_id`: the flow run ID to load the input for

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -> Self
```

Load the run input response from the given key.

**Args:**

* `- keyset`: the keyset to load the input for
* `- flow_run_id`: the flow run ID to load the input for

#### `load_from_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_flow_run_input(cls, flow_run_input: 'FlowRunInput') -> Self
```

Load the run input from a FlowRunInput object.

**Args:**

* `- flow_run_input`: the flow run input to load the input for

#### `metadata` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
metadata(self) -> RunInputMetadata
```

#### `receive` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
receive(cls, timeout: Optional[float] = 3600, poll_interval: float = 10, raise_timeout_error: bool = False, exclude_keys: Optional[Set[str]] = None, key_prefix: Optional[str] = None, flow_run_id: Optional[UUID] = None, with_metadata: bool = False) -> GetAutomaticInputHandler[T]
```

#### `respond` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
respond(self, run_input: 'RunInput', sender: Optional[str] = None, key_prefix: Optional[str] = None)
```

#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None)
```

Save the run input response to the given key.

**Args:**

* `- keyset`: the keyset to save the input for
* `- flow_run_id`: the flow run ID to save the input for

#### `send_to` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
send_to(self, flow_run_id: UUID, sender: Optional[str] = None, key_prefix: Optional[str] = None)
```

#### `subclass_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
subclass_from_type(cls, _type: Type[T]) -> Type['AutomaticRunInput[T]']
```

Create a new `AutomaticRunInput` subclass from the given type.

This method uses the type's name as a key prefix to identify related
flow run inputs. This helps in ensuring that values saved under a type
(like List\[int]) are retrievable under the generic type name (like "list").

#### `with_initial_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_initial_data(cls: Type[R], description: Optional[str] = None, **kwargs: Any) -> Type[R]
```

Create a new `RunInput` subclass with the given initial data as field
defaults.

**Args:**

* `- description`: a description to show when resuming
  a flow run that requires input
* `- kwargs`: the initial data to populate the subclass

### `GetInputHandler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L440" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `filter_for_inputs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L487" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter_for_inputs(self) -> list['FlowRunInput']
```

#### `next` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L508" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next(self) -> R
```

#### `to_instance` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L504" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_instance(self, flow_run_input: 'FlowRunInput') -> R
```

### `GetAutomaticInputHandler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L521" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `filter_for_inputs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L573" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter_for_inputs(self) -> list['FlowRunInput']
```

#### `next` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L591" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next(self) -> Union[T, AutomaticRunInput[T]]
```

#### `to_instance` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/input/run_input.py#L603" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_instance(self, flow_run_input: 'FlowRunInput') -> Union[T, AutomaticRunInput[T]]
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-locking-__init__



# `prefect.locking`

*This module is empty or contains only private/internal implementations.*


# filesystem
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-locking-filesystem



# `prefect.locking.filesystem`

## Classes

### `FileSystemLockManager` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A lock manager that implements locking using local files.

**Methods:**

#### `aacquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aacquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

#### `aacquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aacquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

Acquire a lock for a transaction record with the given key. Will block other
actors from updating this transaction record until the lock is
released.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.
* `acquire_timeout`: Max number of seconds to wait for the record to become
  available if it is locked while attempting to acquire a lock. Pass 0
  to attempt to acquire a lock without waiting. Blocks indefinitely by
  default.
* `hold_timeout`: Max number of seconds to hold the lock for. Holds the lock
  indefinitely by default.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `acquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

#### `acquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L6" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

Acquire a lock for a transaction record with the given key. Will block other
actors from updating this transaction record until the lock is
released.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.
* `acquire_timeout`: Max number of seconds to wait for the record to become
  available if it is locked while attempting to acquire a lock. Pass 0
  to attempt to acquire a lock without waiting. Blocks indefinitely by
  default.
* `hold_timeout`: Max number of seconds to hold the lock for. Holds the lock
  indefinitely by default.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `await_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L239" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
await_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

#### `await_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
await_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

Wait for the corresponding transaction record to become free.

**Args:**

* `key`: Unique identifier for the transaction record.
* `timeout`: Maximum time to wait. None means to wait indefinitely.

**Returns:**

* True if the lock becomes free within the timeout; False
  otherwise.

#### `is_lock_holder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L220" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_lock_holder(self, key: str, holder: str) -> bool
```

#### `is_lock_holder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_lock_holder(self, key: str, holder: str) -> bool
```

Check if the current holder is the lock holder for the transaction record.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.

**Returns:**

* True if the current holder is the lock holder; False otherwise.

#### `is_locked` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_locked(self, key: str, use_cache: bool = False) -> bool
```

#### `is_locked` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_locked(self, key: str) -> bool
```

Simple check to see if the corresponding record is currently locked.

**Args:**

* `key`: Unique identifier for the transaction record.

**Returns:**

* True is the record is locked; False otherwise.

#### `release_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
release_lock(self, key: str, holder: str) -> None
```

#### `release_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
release_lock(self, key: str, holder: str) -> None
```

Releases the lock on the corresponding transaction record.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock. Must match the
  holder provided when acquiring the lock.

#### `wait_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/filesystem.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

#### `wait_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

Wait for the corresponding transaction record to become free.

**Args:**

* `key`: Unique identifier for the transaction record.
* `timeout`: Maximum time to wait. None means to wait indefinitely.

**Returns:**

* True if the lock becomes free within the timeout; False
  otherwise.


# memory
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-locking-memory



# `prefect.locking.memory`

## Classes

### `MemoryLockManager` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A lock manager that stores lock information in memory.

Note: because this lock manager stores data in memory, it is not suitable for
use in a distributed environment or across different processes.

**Methods:**

#### `aacquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aacquire_lock(self, key: str, holder: str, acquire_timeout: float | None = None, hold_timeout: float | None = None) -> bool
```

#### `aacquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aacquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

Acquire a lock for a transaction record with the given key. Will block other
actors from updating this transaction record until the lock is
released.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.
* `acquire_timeout`: Max number of seconds to wait for the record to become
  available if it is locked while attempting to acquire a lock. Pass 0
  to attempt to acquire a lock without waiting. Blocks indefinitely by
  default.
* `hold_timeout`: Max number of seconds to hold the lock for. Holds the lock
  indefinitely by default.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `acquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire_lock(self, key: str, holder: str, acquire_timeout: float | None = None, hold_timeout: float | None = None) -> bool
```

#### `acquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L6" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

Acquire a lock for a transaction record with the given key. Will block other
actors from updating this transaction record until the lock is
released.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.
* `acquire_timeout`: Max number of seconds to wait for the record to become
  available if it is locked while attempting to acquire a lock. Pass 0
  to attempt to acquire a lock without waiting. Blocks indefinitely by
  default.
* `hold_timeout`: Max number of seconds to hold the lock for. Holds the lock
  indefinitely by default.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `await_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
await_for_lock(self, key: str, timeout: float | None = None) -> bool
```

#### `await_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
await_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

Wait for the corresponding transaction record to become free.

**Args:**

* `key`: Unique identifier for the transaction record.
* `timeout`: Maximum time to wait. None means to wait indefinitely.

**Returns:**

* True if the lock becomes free within the timeout; False
  otherwise.

#### `is_lock_holder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_lock_holder(self, key: str, holder: str) -> bool
```

#### `is_lock_holder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_lock_holder(self, key: str, holder: str) -> bool
```

Check if the current holder is the lock holder for the transaction record.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.

**Returns:**

* True if the current holder is the lock holder; False otherwise.

#### `is_locked` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_locked(self, key: str) -> bool
```

#### `is_locked` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_locked(self, key: str) -> bool
```

Simple check to see if the corresponding record is currently locked.

**Args:**

* `key`: Unique identifier for the transaction record.

**Returns:**

* True is the record is locked; False otherwise.

#### `release_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
release_lock(self, key: str, holder: str) -> None
```

#### `release_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
release_lock(self, key: str, holder: str) -> None
```

Releases the lock on the corresponding transaction record.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock. Must match the
  holder provided when acquiring the lock.

#### `wait_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/memory.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_lock(self, key: str, timeout: float | None = None) -> bool
```

#### `wait_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

Wait for the corresponding transaction record to become free.

**Args:**

* `key`: Unique identifier for the transaction record.
* `timeout`: Maximum time to wait. None means to wait indefinitely.

**Returns:**

* True if the lock becomes free within the timeout; False
  otherwise.


# protocol
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-locking-protocol



# `prefect.locking.protocol`

## Classes

### `LockManager` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L5" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `aacquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aacquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

Acquire a lock for a transaction record with the given key. Will block other
actors from updating this transaction record until the lock is
released.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.
* `acquire_timeout`: Max number of seconds to wait for the record to become
  available if it is locked while attempting to acquire a lock. Pass 0
  to attempt to acquire a lock without waiting. Blocks indefinitely by
  default.
* `hold_timeout`: Max number of seconds to hold the lock for. Holds the lock
  indefinitely by default.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `acquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L6" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire_lock(self, key: str, holder: str, acquire_timeout: Optional[float] = None, hold_timeout: Optional[float] = None) -> bool
```

Acquire a lock for a transaction record with the given key. Will block other
actors from updating this transaction record until the lock is
released.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.
* `acquire_timeout`: Max number of seconds to wait for the record to become
  available if it is locked while attempting to acquire a lock. Pass 0
  to attempt to acquire a lock without waiting. Blocks indefinitely by
  default.
* `hold_timeout`: Max number of seconds to hold the lock for. Holds the lock
  indefinitely by default.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `await_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
await_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

Wait for the corresponding transaction record to become free.

**Args:**

* `key`: Unique identifier for the transaction record.
* `timeout`: Maximum time to wait. None means to wait indefinitely.

**Returns:**

* True if the lock becomes free within the timeout; False
  otherwise.

#### `is_lock_holder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_lock_holder(self, key: str, holder: str) -> bool
```

Check if the current holder is the lock holder for the transaction record.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock.

**Returns:**

* True if the current holder is the lock holder; False otherwise.

#### `is_locked` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_locked(self, key: str) -> bool
```

Simple check to see if the corresponding record is currently locked.

**Args:**

* `key`: Unique identifier for the transaction record.

**Returns:**

* True is the record is locked; False otherwise.

#### `release_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
release_lock(self, key: str, holder: str) -> None
```

Releases the lock on the corresponding transaction record.

**Args:**

* `key`: Unique identifier for the transaction record.
* `holder`: Unique identifier for the holder of the lock. Must match the
  holder provided when acquiring the lock.

#### `wait_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/locking/protocol.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_lock(self, key: str, timeout: Optional[float] = None) -> bool
```

Wait for the corresponding transaction record to become free.

**Args:**

* `key`: Unique identifier for the transaction record.
* `timeout`: Maximum time to wait. None means to wait indefinitely.

**Returns:**

* True if the lock becomes free within the timeout; False
  otherwise.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-__init__



# `prefect.logging`

*This module is empty or contains only private/internal implementations.*


# clients
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-clients



# `prefect.logging.clients`

## Functions

### `http_to_ws` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/clients.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
http_to_ws(url: str) -> str
```

### `logs_out_socket_from_api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/clients.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logs_out_socket_from_api_url(url: str) -> str
```

### `get_logs_subscriber` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/clients.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_logs_subscriber(filter: Optional['LogFilter'] = None, reconnection_attempts: int = 10) -> 'PrefectLogsSubscriber'
```

Get a logs subscriber based on the current Prefect configuration.

Similar to get\_events\_subscriber, this automatically detects whether
you're using Prefect Cloud or OSS and returns the appropriate subscriber.

## Classes

### `PrefectLogsSubscriber` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/clients.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Subscribes to a Prefect logs stream, yielding logs as they occur.

Example:

from prefect.logging.clients import PrefectLogsSubscriber
from prefect.client.schemas.filters import LogFilter, LogFilterLevel
import logging

filter = LogFilter(level=LogFilterLevel(ge\_=logging.INFO))

async with PrefectLogsSubscriber(filter=filter) as subscriber:
async for log in subscriber:
print(log.timestamp, log.level, log.message)

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/clients.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

### `PrefectCloudLogsSubscriber` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/clients.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Logs subscriber for Prefect Cloud

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/clients.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```


# configuration
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-configuration



# `prefect.logging.configuration`

## Functions

### `load_logging_config` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/configuration.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_logging_config(path: Path) -> dict[str, Any]
```

Loads logging configuration from a path allowing override from the environment

### `setup_logging` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/configuration.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_logging(incremental: bool | None = None) -> dict[str, Any]
```

Sets up logging.

Returns the config used.


# filters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-filters



# `prefect.logging.filters`

## Functions

### `redact_substr` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/filters.py#L8" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
redact_substr(obj: Any, substr: str) -> Any
```

Redact a string from a potentially nested object.

**Args:**

* `obj`: The object to redact the string from
* `substr`: The string to redact.

**Returns:**

* The object with the API key redacted.

## Classes

### `ObfuscateApiKeyFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/filters.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A logging filter that obfuscates any string that matches the obfuscate\_string function.

**Methods:**

#### `filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/filters.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter(self, record: logging.LogRecord) -> bool
```


# formatters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-formatters



# `prefect.logging.formatters`

## Functions

### `format_exception_info` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/formatters.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format_exception_info(exc_info: ExceptionInfoType) -> dict[str, Any]
```

## Classes

### `JsonFormatter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/formatters.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Formats log records as a JSON string.

The format may be specified as "pretty" to format the JSON with indents and
newlines.

**Methods:**

#### `format` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/formatters.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format(self, record: logging.LogRecord) -> str
```

### `PrefectFormatter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/formatters.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `formatMessage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/formatters.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
formatMessage(self, record: logging.LogRecord) -> str
```


# handlers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-handlers



# `prefect.logging.handlers`

## Classes

### `APILogWorker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `instance` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
instance(cls: Type[Self], *args: Any) -> Self
```

#### `max_batch_size` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
max_batch_size(self) -> int
```

#### `min_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
min_interval(self) -> float | None
```

### `APILogHandler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A logging handler that sends logs to the Prefect API.

Sends log records to the `APILogWorker` which manages sending batches of logs in
the background.

**Methods:**

#### `aflush` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aflush(cls) -> None
```

Tell the `APILogWorker` to send any currently enqueued logs and block until
completion.

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, record: logging.LogRecord) -> None
```

Send a log to the `APILogWorker`

#### `flush` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flush(self) -> None
```

Tell the `APILogWorker` to send any currently enqueued logs and block until
completion.

Use `aflush` from async contexts instead.

#### `handleError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handleError(self, record: logging.LogRecord) -> None
```

#### `prepare` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare(self, record: logging.LogRecord) -> Dict[str, Any]
```

Convert a `logging.LogRecord` to the API `LogCreate` schema and serialize.

This infers the linked flow or task run from the log record or the current
run context.

If a flow run id cannot be found, the log will be dropped.

Logs exceeding the maximum size will be dropped.

### `WorkerAPILogHandler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `aflush` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aflush(cls) -> None
```

Tell the `APILogWorker` to send any currently enqueued logs and block until
completion.

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, record: logging.LogRecord) -> None
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, record: logging.LogRecord) -> None
```

Send a log to the `APILogWorker`

#### `flush` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flush(self) -> None
```

Tell the `APILogWorker` to send any currently enqueued logs and block until
completion.

Use `aflush` from async contexts instead.

#### `handleError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handleError(self, record: logging.LogRecord) -> None
```

#### `prepare` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare(self, record: logging.LogRecord) -> Dict[str, Any]
```

Convert a `logging.LogRecord` to the API `LogCreate` schema and serialize.

This will add in the worker id to the log.

Logs exceeding the maximum size will be dropped.

#### `prepare` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare(self, record: logging.LogRecord) -> Dict[str, Any]
```

Convert a `logging.LogRecord` to the API `LogCreate` schema and serialize.

This infers the linked flow or task run from the log record or the current
run context.

If a flow run id cannot be found, the log will be dropped.

Logs exceeding the maximum size will be dropped.

### `PrefectConsoleHandler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/handlers.py#L352" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, record: logging.LogRecord) -> None
```


# highlighters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-highlighters



# `prefect.logging.highlighters`

## Classes

### `LevelHighlighter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/highlighters.py#L6" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Apply style to log levels.

### `UrlHighlighter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/highlighters.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Apply style to urls.

### `NameHighlighter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/highlighters.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Apply style to names.

### `StateHighlighter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/highlighters.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Apply style to states.

### `PrefectConsoleHighlighter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/highlighters.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Applies style from multiple highlighters.


# loggers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-logging-loggers



# `prefect.logging.loggers`

## Functions

### `get_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_logger(name: str | None = None) -> logging.Logger
```

Get a `prefect` logger. These loggers are intended for internal use within the
`prefect` package.

See `get_run_logger` for retrieving loggers for use within task or flow runs.
By default, only run-related loggers are connected to the `APILogHandler`.

### `get_run_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_run_logger(context: Optional['RunContext'] = None, **kwargs: Any) -> Union[logging.Logger, LoggingAdapter]
```

Get a Prefect logger for the current task run or flow run.

The logger will be named either `prefect.task_runs` or `prefect.flow_runs`.
Contextual data about the run will be attached to the log records.

These loggers are connected to the `APILogHandler` by default to send log records to
the API.

**Args:**

* `context`: A specific context may be provided as an override. By default, the
  context is inferred from global state and this should not be needed.
* `**kwargs`: Additional keyword arguments will be attached to the log records in
  addition to the run metadata

**Raises:**

* `MissingContextError`: If no context can be found

### `flow_run_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_logger(flow_run: 'FlowRun', flow: Optional['Flow[Any, Any]'] = None, **kwargs: str) -> PrefectLogAdapter
```

Create a flow run logger with the run's metadata attached.

Additional keyword arguments can be provided to attach custom data to the log
records.

If the flow run context is available, see `get_run_logger` instead.

### `task_run_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_logger(task_run: 'TaskRun', task: Optional['Task[Any, Any]'] = None, flow_run: Optional['FlowRun'] = None, flow: Optional['Flow[Any, Any]'] = None, **kwargs: Any) -> LoggingAdapter
```

Create a task run logger with the run's metadata attached.

Additional keyword arguments can be provided to attach custom data to the log
records.

If the task run context is available, see `get_run_logger` instead.

If only the flow run context is available, it will be used for default values
of `flow_run` and `flow`.

### `get_worker_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_worker_logger(worker: 'BaseWorker[Any, Any, Any]', name: Optional[str] = None) -> logging.Logger | LoggingAdapter
```

Create a worker logger with the worker's metadata attached.

If the worker has a backend\_id, it will be attached to the log records.
If the worker does not have a backend\_id a basic logger will be returned.
If the worker does not have a backend\_id attribute, a basic logger will be returned.

### `disable_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable_logger(name: str)
```

Get a logger by name and disables it within the context manager.
Upon exiting the context manager, the logger is returned to its
original state.

### `disable_run_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable_run_logger()
```

Gets both `prefect.flow_run` and `prefect.task_run` and disables them
within the context manager. Upon exiting the context manager, both loggers
are returned to their original state.

### `print_as_log` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
print_as_log(*args: Any, **kwargs: Any) -> None
```

A patch for `print` to send printed messages to the Prefect run logger.

If no run is active, `print` will behave as if it were not patched.

If `print` sends data to a file other than `sys.stdout` or `sys.stderr`, it will
not be forwarded to the Prefect logger either.

### `patch_print` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
patch_print()
```

Patches the Python builtin `print` method to use `print_as_log`

## Classes

### `PrefectLogAdapter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Adapter that ensures extra kwargs are passed through correctly; without this
the `extra` fields set on the adapter would overshadow any provided on a
log-by-log basis.

See [https://bugs.python.org/issue32732](https://bugs.python.org/issue32732) — the Python team has declared that this is
not a bug in the LoggingAdapter and subclassing is the intended workaround.

**Methods:**

#### `getChild` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
getChild(self, suffix: str, extra: dict[str, Any] | None = None) -> 'PrefectLogAdapter'
```

#### `process` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, MutableMapping[str, Any]]
```

### `LogEavesdropper` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A context manager that collects logs for the duration of the context

Example:

````python
import logging
from prefect.logging import LogEavesdropper

with LogEavesdropper("my_logger") as eavesdropper:
    logging.getLogger("my_logger").info("Hello, world!")
    logging.getLogger("my_logger.child_module").info("Another one!")

print(eavesdropper.text())

# Outputs: "Hello, world!
Another one!"


**Methods:**

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, record: LogRecord) -> None
````

The logging.Handler implementation, not intended to be called directly.

#### `text` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/logging/loggers.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
text(self) -> str
```

Return the collected logs as a single newline-delimited string


# main
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-main



# `prefect.main`

*This module is empty or contains only private/internal implementations.*


# plugins
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-plugins



# `prefect.plugins`

Utilities for loading plugins that extend Prefect's functionality.

Plugins are detected by entry point definitions in package setup files.

Currently supported entrypoints:

* prefect.collections: Identifies this package as a Prefect collection that
  should be imported when Prefect is imported.

## Functions

### `safe_load_entrypoints` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/plugins.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
safe_load_entrypoints(entrypoints: EntryPoints) -> dict[str, Union[Exception, Any]]
```

Load entry points for a group capturing any exceptions that occur.

### `load_prefect_collections` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/plugins.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_prefect_collections() -> dict[str, Union[ModuleType, Exception]]
```

Load all Prefect collections that define an entrypoint in the group
`prefect.collections`.


# results
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-results



# `prefect.results`

## Functions

### `DEFAULT_STORAGE_KEY_FN` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
DEFAULT_STORAGE_KEY_FN() -> str
```

### `aget_default_result_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget_default_result_storage() -> WritableFileSystem
```

Generate a default file system for result storage.

### `get_default_result_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_default_result_storage() -> WritableFileSystem
```

Generate a default file system for result storage.

### `aresolve_result_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aresolve_result_storage(result_storage: ResultStorage | UUID | Path) -> WritableFileSystem
```

Resolve one of the valid `ResultStorage` input types into a saved block
document id and an instance of the block.

### `resolve_result_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_result_storage(result_storage: ResultStorage | UUID | Path) -> WritableFileSystem
```

Resolve one of the valid `ResultStorage` input types into a saved block
document id and an instance of the block.

### `resolve_serializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_serializer(serializer: ResultSerializer) -> Serializer
```

Resolve one of the valid `ResultSerializer` input types into a serializer
instance.

### `get_or_create_default_task_scheduling_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_or_create_default_task_scheduling_storage() -> ResultStorage
```

Generate a default file system for background task parameter/result storage.

### `get_default_result_serializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_default_result_serializer() -> Serializer
```

Generate a default file system for result storage.

### `get_default_persist_setting` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_default_persist_setting() -> bool
```

Return the default option for result persistence.

### `get_default_persist_setting_for_tasks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L252" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_default_persist_setting_for_tasks() -> bool
```

Return the default option for result persistence for tasks.

### `should_persist_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
should_persist_result() -> bool
```

Return the default option for result persistence determined by the current run context.

If there is no current run context, the value of `results.persist_by_default` on the
current settings will be returned.

### `default_cache` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_cache() -> LRUCache[str, 'ResultRecord[Any]']
```

### `result_storage_discriminator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result_storage_discriminator(x: Any) -> str
```

### `get_result_store` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L1023" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_result_store() -> ResultStore
```

Get the current result store.

## Classes

### `ResultStore` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Manages the storage and retrieval of results.

**Methods:**

#### `aacquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L883" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aacquire_lock(self, key: str, holder: str | None = None, timeout: float | None = None) -> bool
```

Acquire a lock for a result record.

**Args:**

* `key`: The key to acquire the lock for.
* `holder`: The holder of the lock. If not provided, a default holder based on the
  current host, process, and thread will be used.
* `timeout`: The timeout for the lock.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `acquire_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L860" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
acquire_lock(self, key: str, holder: str | None = None, timeout: float | None = None) -> bool
```

Acquire a lock for a result record.

**Args:**

* `key`: The key to acquire the lock for.
* `holder`: The holder of the lock. If not provided, a default holder based on the
  current host, process, and thread will be used.
* `timeout`: The timeout for the lock.

**Returns:**

* True if the lock was successfully acquired; False otherwise.

#### `aexists` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L528" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aexists(self, key: str) -> bool
```

Check if a result record exists in storage.

**Args:**

* `key`: The key to check for the existence of a result record.

**Returns:**

* True if the result record exists, False otherwise.

#### `apersist_result_record` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L827" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
apersist_result_record(self, result_record: 'ResultRecord[Any]', holder: str | None = None) -> None
```

Persist a result record to storage.

**Args:**

* `result_record`: The result record to persist.

#### `aread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L639" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aread(self, key: str, holder: str | None = None) -> 'ResultRecord[Any]'
```

Read a result record from storage.

**Args:**

* `key`: The key to read the result record from.
* `holder`: The holder of the lock if a lock was set on the record.

**Returns:**

* A result record.

#### `await_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L967" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
await_for_lock(self, key: str, timeout: float | None = None) -> bool
```

Wait for the corresponding transaction record to become free.

#### `awrite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
awrite(self, obj: Any, key: str | None = None, expiration: DateTime | None = None, holder: str | None = None) -> None
```

Write a result to storage.

**Args:**

* `key`: The key to write the result record to.
* `obj`: The object to write to storage.
* `expiration`: The expiration time for the result record.
* `holder`: The holder of the lock if a lock was set on the record.

#### `create_result_record` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L657" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_result_record(self, obj: Any, key: str | None = None, expiration: DateTime | None = None) -> 'ResultRecord[Any]'
```

Create a result record.

**Args:**

* `key`: The key to create the result record for.
* `obj`: The object to create the result record for.
* `expiration`: The expiration time for the result record.

#### `exists` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exists(self, key: str) -> bool
```

Check if a result record exists in storage.

**Args:**

* `key`: The key to check for the existence of a result record.

**Returns:**

* True if the result record exists, False otherwise.

#### `generate_default_holder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L452" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_default_holder() -> str
```

Generate a default holder string using hostname, PID, and thread ID.

**Returns:**

* A unique identifier string.

#### `is_lock_holder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L936" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_lock_holder(self, key: str, holder: str | None = None) -> bool
```

Check if the current holder is the lock holder for the result record.

**Args:**

* `key`: The key to check the lock for.
* `holder`: The holder of the lock. If not provided, a default holder based on the
  current host, process, and thread will be used.

**Returns:**

* True if the current holder is the lock holder; False otherwise.

#### `is_locked` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L925" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_locked(self, key: str) -> bool
```

Check if a result record is locked.

#### `persist_result_record` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L813" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
persist_result_record(self, result_record: 'ResultRecord[Any]', holder: str | None = None) -> None
```

Persist a result record to storage.

**Args:**

* `result_record`: The result record to persist.

#### `read` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L621" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read(self, key: str, holder: str | None = None) -> 'ResultRecord[Any]'
```

Read a result record from storage.

**Args:**

* `key`: The key to read the result record from.
* `holder`: The holder of the lock if a lock was set on the record.

**Returns:**

* A result record.

#### `read_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L1007" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_parameters(self, identifier: UUID) -> dict[str, Any]
```

#### `release_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L907" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
release_lock(self, key: str, holder: str | None = None) -> None
```

Release a lock for a result record.

**Args:**

* `key`: The key to release the lock for.
* `holder`: The holder of the lock. Must match the holder that acquired the lock.
  If not provided, a default holder based on the current host, process, and
  thread will be used.

#### `result_storage_block_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L344" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result_storage_block_id(self) -> UUID | None
```

#### `store_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L986" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
store_parameters(self, identifier: UUID, parameters: dict[str, Any])
```

#### `supports_isolation_level` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L841" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
supports_isolation_level(self, level: 'IsolationLevel') -> bool
```

Check if the result store supports a given isolation level.

**Args:**

* `level`: The isolation level to check.

**Returns:**

* True if the isolation level is supported, False otherwise.

#### `update_for_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L375" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_for_flow(self, flow: 'Flow[..., Any]') -> Self
```

Create a new result store for a flow with updated settings.

**Args:**

* `flow`: The flow to update the result store for.

**Returns:**

* An updated result store.

#### `update_for_task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L399" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_for_task(self: Self, task: 'Task[P, R]') -> Self
```

Create a new result store for a task.

**Args:**

* `task`: The task to update the result store for.

**Returns:**

* An updated result store.

#### `wait_for_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L956" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_lock(self, key: str, timeout: float | None = None) -> bool
```

Wait for the corresponding transaction record to become free.

#### `write` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/results.py#L694" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write(self, obj: Any, key: str | None = None, expiration: DateTime | None = None, holder: str | None = None) -> None
```

Write a result to storage.

Handles the creation of a `ResultRecord` and its serialization to storage.

**Args:**

* `key`: The key to write the result record to.
* `obj`: The object to write to storage.
* `expiration`: The expiration time for the result record.
* `holder`: The holder of the lock if a lock was set on the record.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runner-__init__



# `prefect.runner`

*This module is empty or contains only private/internal implementations.*


# runner
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runner-runner



# `prefect.runner.runner`

Runners are responsible for managing the execution of all deployments.

When creating a deployment using either `flow.serve` or the `serve` utility,
they also will poll for scheduled runs.

Example:

```python
import time
from prefect import flow, serve


@flow
def slow_flow(sleep: int = 60):
    "Sleepy flow - sleeps the provided amount of time (in seconds)."
    time.sleep(sleep)


@flow
def fast_flow():
    "Fastest flow this side of the Mississippi."
    return


if __name__ == "__main__":
    slow_deploy = slow_flow.to_deployment(name="sleeper", interval=45)
    fast_deploy = fast_flow.to_deployment(name="fast")

    # serve generates a Runner instance
    serve(slow_deploy, fast_deploy)
```

## Classes

### `ProcessMapEntry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Runner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `add_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L282" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_deployment(self, deployment: 'RunnerDeployment') -> UUID
```

Registers the deployment with the Prefect API and will monitor for work once
the runner is started.

**Args:**

* `deployment`: A deployment for the runner to register.

#### `add_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_flow(self, flow: Flow[Any, Any], name: Optional[str] = None, interval: Optional[Union[Iterable[Union[int, float, datetime.timedelta]], int, float, datetime.timedelta]] = None, cron: Optional[Union[Iterable[str], str]] = None, rrule: Optional[Union[Iterable[str], str]] = None, paused: Optional[bool] = None, schedule: Optional[Schedule] = None, schedules: Optional['FlexibleScheduleList'] = None, concurrency_limit: Optional[Union[int, ConcurrencyLimitConfig, None]] = None, parameters: Optional[dict[str, Any]] = None, triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None, description: Optional[str] = None, tags: Optional[List[str]] = None, version: Optional[str] = None, enforce_parameter_schema: bool = True, entrypoint_type: EntrypointType = EntrypointType.FILE_PATH) -> UUID
```

Provides a flow to the runner to be run based on the provided configuration.

Will create a deployment for the provided flow and register the deployment
with the runner.

**Args:**

* `flow`: A flow for the runner to run.
* `name`: The name to give the created deployment. Will default to the name
  of the runner.
* `interval`: An interval on which to execute the current flow. Accepts either a number
  or a timedelta object. If a number is given, it will be interpreted as seconds.
* `cron`: A cron schedule of when to execute runs of this flow.
* `rrule`: An rrule schedule of when to execute runs of this flow.
* `paused`: Whether or not to set the created deployment as paused.
* `schedule`: A schedule object defining when to execute runs of this deployment.
  Used to provide additional scheduling options like `timezone` or `parameters`.
* `schedules`: A list of schedule objects defining when to execute runs of this flow.
  Used to define multiple schedules or additional scheduling options like `timezone`.
* `concurrency_limit`: The maximum number of concurrent runs of this flow to allow.
* `triggers`: A list of triggers that should kick of a run of this flow.
* `parameters`: A dictionary of default parameter values to pass to runs of this flow.
* `description`: A description for the created deployment. Defaults to the flow's
  description if not provided.
* `tags`: A list of tags to associate with the created deployment for organizational
  purposes.
* `version`: A version for the created deployment. Defaults to the flow's version.
* `entrypoint_type`: Type of entrypoint to use for the deployment. When using a module path
  entrypoint, ensure that the module will be importable in the execution environment.

#### `cancel_all` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L533" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cancel_all(self) -> None
```

#### `execute_bundle` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
execute_bundle(self, bundle: SerializedBundle, cwd: Path | str | None = None, env: dict[str, str | None] | None = None) -> None
```

Executes a bundle in a subprocess.

#### `execute_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L568" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
execute_flow_run(self, flow_run_id: UUID, entrypoint: str | None = None, command: str | None = None, cwd: Path | str | None = None, env: dict[str, str | None] | None = None, task_status: anyio.abc.TaskStatus[int] = anyio.TASK_STATUS_IGNORED, stream_output: bool = True) -> anyio.abc.Process | None
```

Executes a single flow run with the given ID.

Execution will wait to monitor for cancellation requests. Exits once
the flow run process has exited.

**Returns:**

* The flow run process.

#### `execute_in_background` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L522" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
execute_in_background(self, func: Callable[..., Any], *args: Any, **kwargs: Any) -> 'concurrent.futures.Future[Any]'
```

Executes a function in the background.

#### `handle_sigterm` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_sigterm(self, *args: Any, **kwargs: Any) -> None
```

Gracefully shuts down the runner when a SIGTERM is received.

#### `has_slots_available` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L1168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
has_slots_available(self) -> bool
```

Determine if the flow run limit has been reached.

**Returns:**

* * bool: True if the limit has not been reached, False otherwise.

#### `reschedule_current_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L921" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reschedule_current_flow_runs(self) -> None
```

Reschedules all flow runs that are currently running.

This should only be called when the runner is shutting down because it kill all
child processes and short-circuit the crash detection logic.

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, run_once: bool = False, webserver: Optional[bool] = None) -> None
```

Starts a runner.

The runner will begin monitoring for and executing any scheduled work for all added flows.

**Args:**

* `run_once`: If True, the runner will through one query loop and then exit.
* `webserver`: a boolean for whether to start a webserver for this runner. If provided,
  overrides the default on the runner

**Examples:**

Initialize a Runner, add two flows, and serve them by starting the Runner:

```python
import asyncio
from prefect import flow, Runner

@flow
def hello_flow(name):
    print(f"hello {name}")

@flow
def goodbye_flow(name):
    print(f"goodbye {name}")

if __name__ == "__main__"
    runner = Runner(name="my-runner")

    # Will be runnable via the API
    runner.add_flow(hello_flow)

    # Run on a cron schedule
    runner.add_flow(goodbye_flow, schedule={"cron": "0 * * * *"})

    asyncio.run(runner.start())
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/runner.py#L550" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self)
```

Stops the runner's polling cycle.


# server
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runner-server



# `prefect.runner.server`

## Functions

### `perform_health_check` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
perform_health_check(runner: 'Runner', delay_threshold: int | None = None) -> Callable[..., JSONResponse]
```

### `run_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_count(runner: 'Runner') -> Callable[..., int]
```

### `shutdown` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
shutdown(runner: 'Runner') -> Callable[..., JSONResponse]
```

### `get_deployment_router` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_deployment_router(runner: 'Runner') -> tuple[APIRouter, dict[Hashable, Any]]
```

### `get_subflow_schemas` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_subflow_schemas(runner: 'Runner') -> dict[str, dict[str, Any]]
```

Load available subflow schemas by filtering for only those subflows in the
deployment entrypoint's import space.

### `build_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_server(runner: 'Runner') -> FastAPI
```

Build a FastAPI server for a runner.

**Args:**

* `runner`: the runner this server interacts with and monitors
* `log_level`: the log level to use for the server

### `start_webserver` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_webserver(runner: 'Runner', log_level: str | None = None) -> None
```

Run a FastAPI server for a runner.

**Args:**

* `runner`: the runner this server interacts with and monitors
* `log_level`: the log level to use for the server

## Classes

### `RunnerGenericFlowRunRequest` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/server.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# storage
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runner-storage



# `prefect.runner.storage`

## Functions

### `create_storage_from_source` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L787" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_storage_from_source(source: str, pull_interval: Optional[int] = 60) -> RunnerStorage
```

Creates a storage object from a URL.

**Args:**

* `url`: The URL to create a storage object from. Supports git and `fsspec`
  URLs.
* `pull_interval`: The interval at which to pull contents from remote storage to
  local storage

**Returns:**

* A runner storage compatible object

## Classes

### `RunnerStorage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A storage interface for a runner to use to retrieve
remotely stored flow code.

**Methods:**

#### `destination` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
destination(self) -> Path
```

The local file path to pull contents from remote storage to.

#### `pull_code` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_code(self) -> None
```

Pulls contents from remote storage to the local filesystem.

#### `pull_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_interval(self) -> Optional[int]
```

The interval at which contents from remote storage should be pulled to
local storage. If None, remote storage will perform a one-time sync.

#### `set_base_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_base_path(self, path: Path) -> None
```

Sets the base path to use when pulling contents from remote storage to
local storage.

#### `to_pull_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_pull_step(self) -> dict[str, Any] | list[dict[str, Any]]
```

Returns a dictionary representation of the storage object that can be
used as a deployment pull step.

### `GitCredentials` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `GitRepository` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pulls the contents of a git repository to the local filesystem.

**Args:**

* `url`: The URL of the git repository to pull from
* `credentials`: A dictionary of credentials to use when pulling from the
  repository. If a username is provided, an access token must also be
  provided.
* `name`: The name of the repository. If not provided, the name will be
  inferred from the repository URL.
* `branch`: The branch to pull from. Defaults to "main".
* `pull_interval`: The interval in seconds at which to pull contents from
  remote storage to local storage. If None, remote storage will perform
  a one-time sync.
* `directories`: The directories to pull from the Git repository (uses git sparse-checkout)

**Examples:**

Pull the contents of a private git repository to the local filesystem:

```python
from prefect.runner.storage import GitRepository

storage = GitRepository(
    url="https://github.com/org/repo.git",
    credentials={"username": "oauth2", "access_token": "my-access-token"},
)

await storage.pull_code()
```

**Methods:**

#### `destination` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
destination(self) -> Path
```

#### `is_current_commit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_current_commit(self) -> bool
```

Check if the current commit is the same as the commit SHA

#### `is_shallow_clone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_shallow_clone(self) -> bool
```

Check if the repository is a shallow clone

#### `is_sparsely_checked_out` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_sparsely_checked_out(self) -> bool
```

Check if existing repo is sparsely checked out

#### `pull_code` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_code(self) -> None
```

Pulls the contents of the configured repository to the local filesystem.

#### `pull_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_interval(self) -> Optional[int]
```

#### `set_base_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_base_path(self, path: Path) -> None
```

#### `to_pull_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_pull_step(self) -> dict[str, Any]
```

### `RemoteStorage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L472" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pulls the contents of a remote storage location to the local filesystem.

**Args:**

* `url`: The URL of the remote storage location to pull from. Supports
  `fsspec` URLs. Some protocols may require an additional `fsspec`
  dependency to be installed. Refer to the
  [`fsspec` docs](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations)
  for more details.
* `pull_interval`: The interval in seconds at which to pull contents from
  remote storage to local storage. If None, remote storage will perform
  a one-time sync.
* `**settings`: Any additional settings to pass the `fsspec` filesystem class.

**Examples:**

Pull the contents of a remote storage location to the local filesystem:

```python
from prefect.runner.storage import RemoteStorage

storage = RemoteStorage(url="s3://my-bucket/my-folder")

await storage.pull_code()
```

Pull the contents of a remote storage location to the local filesystem
with additional settings:

```python
from prefect.runner.storage import RemoteStorage
from prefect.blocks.system import Secret

storage = RemoteStorage(
    url="s3://my-bucket/my-folder",
    # Use Secret blocks to keep credentials out of your code
    key=Secret.load("my-aws-access-key"),
    secret=Secret.load("my-aws-secret-key"),
)

await storage.pull_code()
```

**Methods:**

#### `destination` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
destination(self) -> Path
```

The local file path to pull contents from remote storage to.

#### `pull_code` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L592" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_code(self) -> None
```

Pulls contents from remote storage to the local filesystem.

#### `pull_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L570" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_interval(self) -> Optional[int]
```

The interval at which contents from remote storage should be pulled to
local storage. If None, remote storage will perform a one-time sync.

#### `set_base_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L566" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_base_path(self, path: Path) -> None
```

#### `to_pull_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L622" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_pull_step(self) -> dict[str, Any]
```

Returns a dictionary representation of the storage object that can be
used as a deployment pull step.

### `BlockStorageAdapter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L663" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A storage adapter for a storage block object to allow it to be used as a
runner storage object.

**Methods:**

#### `destination` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L694" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
destination(self) -> Path
```

#### `pull_code` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L697" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_code(self) -> None
```

#### `pull_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L690" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_interval(self) -> Optional[int]
```

#### `set_base_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L686" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_base_path(self, path: Path) -> None
```

#### `to_pull_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L702" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_pull_step(self) -> dict[str, Any]
```

### `LocalStorage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L725" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Sets the working directory in the local filesystem.
Parameters:
Path: Local file path to set the working directory for the flow
Examples:
Sets the working directory for the local path to the flow:

```python
from prefect.runner.storage import Localstorage
storage = LocalStorage(
    path="/path/to/local/flow_directory",
)
```

**Methods:**

#### `destination` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L751" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
destination(self) -> Path
```

#### `pull_code` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L761" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_code(self) -> None
```

#### `pull_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L758" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pull_interval(self) -> Optional[int]
```

#### `set_base_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L754" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_base_path(self, path: Path) -> None
```

#### `to_pull_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/storage.py#L766" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_pull_step(self) -> dict[str, Any]
```

Returns a dictionary representation of the storage object that can be
used as a deployment pull step.


# submit
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runner-submit



# `prefect.runner.submit`

## Functions

### `submit_to_runner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/submit.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit_to_runner(prefect_callable: Flow[Any, Any], parameters: dict[str, Any] | list[dict[str, Any]] | None = None, retry_failed_submissions: bool = True) -> FlowRun | list[FlowRun]
```

Submit a callable in the background via the runner webserver one or more times.

**Args:**

* `prefect_callable`: the callable to run (only flows are supported for now, but eventually tasks)
* `parameters`: keyword arguments to pass to the callable. May be a list of dictionaries where
  each dictionary represents a discrete invocation of the callable
* `retry_failed_submissions`: Whether to retry failed submissions to the runner webserver.

### `wait_for_submitted_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/submit.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_submitted_runs(flow_run_filter: FlowRunFilter | None = None, task_run_filter: TaskRunFilter | None = None, timeout: float | None = None, poll_interval: float = 3.0) -> uuid.UUID | None
```

Wait for completion of any provided flow runs (eventually task runs), as well as subflow runs
of the current flow run (if called from within a flow run and subflow runs exist).

**Args:**

* `flow_run_filter`: A filter to apply to the flow runs to wait for.
* `task_run_filter`: A filter to apply to the task runs to wait for. # TODO: /task/run
* `timeout`: How long to wait for completion of all runs (seconds).
* `poll_interval`: How long to wait between polling each run's state (seconds).


# utils
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runner-utils



# `prefect.runner.utils`

## Functions

### `inject_schemas_into_openapi` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/utils.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inject_schemas_into_openapi(webserver: FastAPI, schemas_to_inject: dict[Hashable, Any]) -> dict[str, Any]
```

Augments the webserver's OpenAPI schema with additional schemas from deployments / flows / tasks.

**Args:**

* `webserver`: The FastAPI instance representing the webserver.
* `schemas_to_inject`: A dictionary of OpenAPI schemas to integrate.

**Returns:**

* The augmented OpenAPI schema dictionary.

### `merge_definitions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/utils.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
merge_definitions(injected_schemas: dict[Hashable, Any], openapi_schema: dict[str, Any]) -> dict[str, Any]
```

Integrates definitions from injected schemas into the OpenAPI components.

**Args:**

* `injected_schemas`: A dictionary of deployment-specific schemas.
* `openapi_schema`: The base OpenAPI schema to update.

### `update_refs_in_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/utils.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_refs_in_schema(schema_item: dict[str, Any] | list[Any], new_ref: str) -> None
```

Recursively replaces `$ref` with a new reference base in a schema item.

**Args:**

* `schema_item`: A schema or part of a schema to update references in.
* `new_ref`: The new base string to replace in `$ref` values.

### `update_refs_to_components` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runner/utils.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_refs_to_components(openapi_schema: dict[str, Any]) -> dict[str, Any]
```

Updates all `$ref` fields in the OpenAPI schema to reference the components section.

**Args:**

* `openapi_schema`: The OpenAPI schema to modify `$ref` fields in.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runtime-__init__



# `prefect.runtime`

Module for easily accessing dynamic attributes for a given run, especially those generated from deployments.

Example usage:

```python
from prefect.runtime import deployment

print(f"This script is running from deployment {deployment.id} with parameters {deployment.parameters}")
```


# deployment
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runtime-deployment



# `prefect.runtime.deployment`

Access attributes of the current deployment run dynamically.

Note that if a deployment is not currently being run, all attributes will return empty values.

You can mock the runtime attributes for testing purposes by setting environment variables
prefixed with `PREFECT__RUNTIME__DEPLOYMENT`.

Example usage:

```python
from prefect.runtime import deployment

def get_task_runner():
    task_runner_config = deployment.parameters.get("runner_config", "default config here")
    return DummyTaskRunner(task_runner_specs=task_runner_config)
```

Available attributes:

* `id`: the deployment's unique ID
* `name`: the deployment's name
* `version`: the deployment's version
* `flow_run_id`: the current flow run ID for this deployment
* `parameters`: the parameters that were passed to this run; note that these do not necessarily
  include default values set on the flow function, only the parameter values set on the deployment
  object or those directly provided via API for this run

## Functions

### `get_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/deployment.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_id() -> Optional[str]
```

### `get_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/deployment.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parameters() -> dict[str, Any]
```

### `get_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/deployment.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_name() -> Optional[str]
```

### `get_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/deployment.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_version() -> Optional[str]
```

### `get_flow_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/deployment.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_flow_run_id() -> Optional[str]
```


# flow_run
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runtime-flow_run



# `prefect.runtime.flow_run`

Access attributes of the current flow run dynamically.

Note that if a flow run cannot be discovered, all attributes will return empty values.

You can mock the runtime attributes for testing purposes by setting environment variables
prefixed with `PREFECT__RUNTIME__FLOW_RUN`.

Available attributes:

* `id`: the flow run's unique ID
* `tags`: the flow run's set of tags
* `scheduled_start_time`: the flow run's expected scheduled start time; defaults to now if not present
* `name`: the name of the flow run
* `flow_name`: the name of the flow
* `flow_version`: the version of the flow
* `parameters`: the parameters that were passed to this run; note that these do not necessarily
  include default values set on the flow function, only the parameter values explicitly passed for the run
* `parent_flow_run_id`: the ID of the flow run that triggered this run, if any
* `parent_deployment_id`: the ID of the deployment that triggered this run, if any
* `run_count`: the number of times this flow run has been run

## Functions

### `get_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_id() -> Optional[str]
```

### `get_tags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_tags() -> List[str]
```

### `get_run_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_run_count() -> int
```

### `get_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_name() -> Optional[str]
```

### `get_flow_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_flow_name() -> Optional[str]
```

### `get_flow_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_flow_version() -> Optional[str]
```

### `get_scheduled_start_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_start_time() -> DateTime
```

### `get_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parameters() -> Dict[str, Any]
```

### `get_parent_flow_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parent_flow_run_id() -> Optional[str]
```

### `get_parent_deployment_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parent_deployment_id() -> Optional[str]
```

### `get_root_flow_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_root_flow_run_id() -> str
```

### `get_flow_run_api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_flow_run_api_url() -> Optional[str]
```

### `get_flow_run_ui_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L325" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_flow_run_ui_url() -> Optional[str]
```

### `get_job_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_job_variables() -> Optional[Dict[str, Any]]
```


# task_run
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-runtime-task_run



# `prefect.runtime.task_run`

Access attributes of the current task run dynamically.

Note that if a task run cannot be discovered, all attributes will return empty values.

You can mock the runtime attributes for testing purposes by setting environment variables
prefixed with `PREFECT__RUNTIME__TASK_RUN`.

Available attributes:

* `id`: the task run's unique ID
* `name`: the name of the task run
* `tags`: the task run's set of tags
* `parameters`: the parameters the task was called with
* `run_count`: the number of times this task run has been run
* `task_name`: the name of the task

## Functions

### `get_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_id() -> str | None
```

### `get_tags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_tags() -> list[str]
```

### `get_run_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_run_count() -> int
```

### `get_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_name() -> str | None
```

### `get_task_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_name() -> str | None
```

### `get_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parameters() -> dict[str, Any]
```

### `get_task_run_api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_run_api_url() -> str | None
```

### `get_task_run_ui_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/task_run.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_run_ui_url() -> str | None
```


# schedules
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-schedules



# `prefect.schedules`

This module contains functionality for creating schedules for deployments.

## Functions

### `Cron` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/schedules.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Cron(timezone: str | None = None, day_or: bool = True, active: bool = True, parameters: dict[str, Any] | None = None, slug: str | None = None) -> Schedule
```

Creates a cron schedule.

**Args:**

* `cron`: A valid cron string (e.g. "0 0 \* \* \*").
* `timezone`: A valid timezone string in IANA tzdata format (e.g. America/New\_York).
* `day_or`: Control how `day` and `day_of_week` entries are handled.
  Defaults to True, matching cron which connects those values using
  OR. If the switch is set to False, the values are connected using AND.
  This behaves like fcron and enables you to e.g. define a job that
  executes each 2nd friday of a month by setting the days of month and
  the weekday.
* `active`: Whether or not the schedule is active.
* `parameters`: A dictionary containing parameter overrides for the schedule.
* `slug`: A unique identifier for the schedule.

**Returns:**

* A cron schedule.

**Examples:**

Create a cron schedule that runs every day at 12:00 AM UTC:

```python
from prefect.schedules import Cron

Cron("0 0 * * *")
```

Create a cron schedule that runs every Monday at 8:00 AM in the America/New\_York timezone:

```python
from prefect.schedules import Cron

Cron("0 8 * * 1", timezone="America/New_York")
```

### `Interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/schedules.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Interval(anchor_date: datetime.datetime | None = None, timezone: str | None = None, active: bool = True, parameters: dict[str, Any] | None = None, slug: str | None = None) -> Schedule
```

Creates an interval schedule.

**Args:**

* `interval`: The interval to use for the schedule. If an integer is provided,
  it will be interpreted as seconds.
* `anchor_date`: The anchor date to use for the schedule.
* `timezone`: A valid timezone string in IANA tzdata format (e.g. America/New\_York).
* `active`: Whether or not the schedule is active.
* `parameters`: A dictionary containing parameter overrides for the schedule.
* `slug`: A unique identifier for the schedule.

**Returns:**

* An interval schedule.

**Examples:**

Create an interval schedule that runs every hour:

```python
from datetime import timedelta

from prefect.schedules import Interval

Interval(timedelta(hours=1))
```

Create an interval schedule that runs every 60 seconds starting at a specific date:

```python
from datetime import datetime

from prefect.schedules import Interval

Interval(60, anchor_date=datetime(2024, 1, 1))
```

### `RRule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/schedules.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
RRule(timezone: str | None = None, active: bool = True, parameters: dict[str, Any] | None = None, slug: str | None = None) -> Schedule
```

Creates an RRule schedule.

**Args:**

* `rrule`: A valid RRule string (e.g. "RRULE:FREQ=DAILY;INTERVAL=1").
* `timezone`: A valid timezone string in IANA tzdata format (e.g. America/New\_York).
* `active`: Whether or not the schedule is active.
* `parameters`: A dictionary containing parameter overrides for the schedule.
* `slug`: A unique identifier for the schedule.

**Returns:**

* An RRule schedule.

**Examples:**

Create an RRule schedule that runs every day at 12:00 AM UTC:

```python
from prefect.schedules import RRule

RRule("RRULE:FREQ=DAILY;INTERVAL=1")
```

Create an RRule schedule that runs every 2nd friday of the month in the America/Chicago timezone:

```python
from prefect.schedules import RRule

RRule("RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=2FR", timezone="America/Chicago")
```

## Classes

### `Schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/schedules.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A dataclass representing a schedule.

Note that only one of `interval`, `cron`, or `rrule` can be defined at a time.


# serializers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-serializers



# `prefect.serializers`

Serializer implementations for converting objects to bytes and bytes to objects.

All serializers are based on the `Serializer` class and include a `type` string that
allows them to be referenced without referencing the actual class. For example, you
can get often specify the `JSONSerializer` with the string "json". Some serializers
support additional settings for configuration of serialization. These are stored on
the instance so the same settings can be used to load saved objects.

All serializers must implement `dumps` and `loads` which convert objects to bytes and
bytes to an object respectively.

## Functions

### `prefect_json_object_encoder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_json_object_encoder(obj: Any) -> Any
```

`JSONEncoder.default` for encoding objects into JSON with extended type support.

Raises a `TypeError` to fallback on other encoders on failure.

### `prefect_json_object_decoder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_json_object_decoder(result: dict[str, Any]) -> Any
```

`JSONDecoder.object_hook` for decoding objects from JSON when previously encoded
with `prefect_json_object_encoder`

## Classes

### `Serializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A serializer that can encode objects of type 'D' into bytes.

**Methods:**

#### `dumps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dumps(self, obj: D) -> bytes
```

Encode the object into a blob of bytes.

#### `loads` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
loads(self, blob: bytes) -> D
```

Decode the blob of bytes into an object.

### `PickleSerializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Serializes objects using the pickle protocol.

* Uses `cloudpickle` by default. See `picklelib` for using alternative libraries.
* Stores the version of the pickle library to check for compatibility during
  deserialization.
* Wraps pickles in base64 for safe transmission.

**Methods:**

#### `check_picklelib` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_picklelib(cls, value: str) -> str
```

#### `dumps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dumps(self, obj: D) -> bytes
```

#### `loads` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
loads(self, blob: bytes) -> D
```

### `JSONSerializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Serializes data to JSON.

Input types must be compatible with the stdlib json library.

Wraps the `json` library to serialize to UTF-8 bytes instead of string types.

**Methods:**

#### `dumps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dumps(self, obj: D) -> bytes
```

#### `dumps_kwargs_cannot_contain_default` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dumps_kwargs_cannot_contain_default(cls, value: dict[str, Any]) -> dict[str, Any]
```

#### `loads` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
loads(self, blob: bytes) -> D
```

#### `loads_kwargs_cannot_contain_object_hook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
loads_kwargs_cannot_contain_object_hook(cls, value: dict[str, Any]) -> dict[str, Any]
```

### `CompressedSerializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Wraps another serializer, compressing its output.
Uses `lzma` by default. See `compressionlib` for using alternative libraries.

**Methods:**

#### `check_compressionlib` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_compressionlib(cls, value: str) -> str
```

#### `dumps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dumps(self, obj: D) -> bytes
```

#### `loads` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
loads(self, blob: bytes) -> D
```

#### `validate_serializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_serializer(cls, value: Union[str, Serializer[D]]) -> Serializer[D]
```

### `CompressedPickleSerializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A compressed serializer preconfigured to use the pickle serializer.

### `CompressedJSONSerializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/serializers.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A compressed serializer preconfigured to use the json serializer.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-__init__



# `prefect.server`

*This module is empty or contains only private/internal implementations.*


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-__init__



# `prefect.server.api`

*This module is empty or contains only private/internal implementations.*


# admin
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-admin



# `prefect.server.api.admin`

Routes for admin-level interactions with the Prefect REST API.

## Functions

### `read_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/admin.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_settings() -> prefect.settings.Settings
```

Get the current Prefect REST API settings.

Secret setting values will be obfuscated.

### `read_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/admin.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_version() -> str
```

Returns the Prefect version number

### `clear_database` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/admin.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_database(db: PrefectDBInterface = Depends(provide_database_interface), confirm: bool = Body(False, embed=True, description='Pass confirm=True to confirm you want to modify the database.'), response: Response = None) -> None
```

Clear all database tables without dropping them.

### `drop_database` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/admin.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_database(db: PrefectDBInterface = Depends(provide_database_interface), confirm: bool = Body(False, embed=True, description='Pass confirm=True to confirm you want to modify the database.'), response: Response = None) -> None
```

Drop all database objects.

### `create_database` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/admin.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_database(db: PrefectDBInterface = Depends(provide_database_interface), confirm: bool = Body(False, embed=True, description='Pass confirm=True to confirm you want to modify the database.'), response: Response = None) -> None
```

Create all database objects.


# artifacts
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-artifacts



# `prefect.server.api.artifacts`

Routes for interacting with artifact objects.

## Functions

### `create_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_artifact(artifact: actions.ArtifactCreate, response: Response, db: PrefectDBInterface = Depends(provide_database_interface)) -> core.Artifact
```

Create an artifact.

For more information, see [https://docs.prefect.io/v3/develop/artifacts](https://docs.prefect.io/v3/develop/artifacts).

### `read_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_artifact(artifact_id: UUID = Path(..., description='The ID of the artifact to retrieve.', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> core.Artifact
```

Retrieve an artifact from the database.

### `read_latest_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_latest_artifact(key: str = Path(..., description='The key of the artifact to retrieve.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> core.Artifact
```

Retrieve the latest artifact from the artifact table.

### `read_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_artifacts(sort: sorting.ArtifactSort = Body(sorting.ArtifactSort.ID_DESC), limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), artifacts: filters.ArtifactFilter = None, flow_runs: filters.FlowRunFilter = None, task_runs: filters.TaskRunFilter = None, flows: filters.FlowFilter = None, deployments: filters.DeploymentFilter = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[core.Artifact]
```

Retrieve artifacts from the database.

### `read_latest_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_latest_artifacts(sort: sorting.ArtifactCollectionSort = Body(sorting.ArtifactCollectionSort.ID_DESC), limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), artifacts: filters.ArtifactCollectionFilter = None, flow_runs: filters.FlowRunFilter = None, task_runs: filters.TaskRunFilter = None, flows: filters.FlowFilter = None, deployments: filters.DeploymentFilter = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[core.ArtifactCollection]
```

Retrieve artifacts from the database.

### `count_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_artifacts(artifacts: filters.ArtifactFilter = None, flow_runs: filters.FlowRunFilter = None, task_runs: filters.TaskRunFilter = None, flows: filters.FlowFilter = None, deployments: filters.DeploymentFilter = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

Count artifacts from the database.

### `count_latest_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_latest_artifacts(artifacts: filters.ArtifactCollectionFilter = None, flow_runs: filters.FlowRunFilter = None, task_runs: filters.TaskRunFilter = None, flows: filters.FlowFilter = None, deployments: filters.DeploymentFilter = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

Count artifacts from the database.

### `update_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_artifact(artifact: actions.ArtifactUpdate, artifact_id: UUID = Path(..., description='The ID of the artifact to update.', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Update an artifact in the database.

### `delete_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/artifacts.py#L214" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_artifact(artifact_id: UUID = Path(..., description='The ID of the artifact to delete.', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete an artifact from the database.


# automations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-automations



# `prefect.server.api.automations`

## Functions

### `create_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_automation(automation: AutomationCreate, db: PrefectDBInterface = Depends(provide_database_interface)) -> Automation
```

Create an automation.

For more information, see [https://docs.prefect.io/v3/automate](https://docs.prefect.io/v3/automate).

### `update_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_automation(automation: AutomationUpdate, automation_id: UUID = Path(..., alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `patch_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
patch_automation(automation: AutomationPartialUpdate, automation_id: UUID = Path(..., alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `delete_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_automation(automation_id: UUID = Path(..., alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `read_automations` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_automations(sort: AutomationSort = Body(AutomationSort.NAME_ASC), limit: int = LimitBody(), offset: int = Body(0, ge=0), automations: Optional[AutomationFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> Sequence[Automation]
```

### `count_automations` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_automations(db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

### `read_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_automation(automation_id: UUID = Path(..., alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> Automation
```

### `read_automations_related_to_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_automations_related_to_resource(resource_id: str = Path(..., alias='resource_id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> Sequence[Automation]
```

### `delete_automations_owned_by_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/automations.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_automations_owned_by_resource(resource_id: str = Path(..., alias='resource_id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```


# block_capabilities
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-block_capabilities



# `prefect.server.api.block_capabilities`

Routes for interacting with block capabilities.

## Functions

### `read_available_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_capabilities.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_available_block_capabilities(db: PrefectDBInterface = Depends(provide_database_interface)) -> List[str]
```

Get available block capabilities.

For more information, see [https://docs.prefect.io/v3/develop/blocks](https://docs.prefect.io/v3/develop/blocks).


# block_documents
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-block_documents



# `prefect.server.api.block_documents`

Routes for interacting with block objects.

## Functions

### `create_block_document` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_documents.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_document(block_document: schemas.actions.BlockDocumentCreate, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.BlockDocument
```

Create a new block document.

For more information, see [https://docs.prefect.io/v3/develop/blocks](https://docs.prefect.io/v3/develop/blocks).

### `read_block_documents` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_documents.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_documents(limit: int = dependencies.LimitBody(), block_documents: Optional[schemas.filters.BlockDocumentFilter] = None, block_types: Optional[schemas.filters.BlockTypeFilter] = None, block_schemas: Optional[schemas.filters.BlockSchemaFilter] = None, include_secrets: bool = Body(False, description='Whether to include sensitive values in the block document.'), sort: Optional[schemas.sorting.BlockDocumentSort] = Body(schemas.sorting.BlockDocumentSort.NAME_ASC), offset: int = Body(0, ge=0), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.BlockDocument]
```

Query for block documents.

### `count_block_documents` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_documents.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_block_documents(block_documents: Optional[schemas.filters.BlockDocumentFilter] = None, block_types: Optional[schemas.filters.BlockTypeFilter] = None, block_schemas: Optional[schemas.filters.BlockSchemaFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

Count block documents.

### `read_block_document_by_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_documents.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_document_by_id(block_document_id: UUID = Path(..., description='The block document id', alias='id'), include_secrets: bool = Query(False, description='Whether to include sensitive values in the block document.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.BlockDocument
```

### `delete_block_document` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_documents.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_block_document(block_document_id: UUID = Path(..., description='The block document id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `update_block_document_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_documents.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_block_document_data(block_document: schemas.actions.BlockDocumentUpdate, block_document_id: UUID = Path(..., description='The block document id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```


# block_schemas
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-block_schemas



# `prefect.server.api.block_schemas`

Routes for interacting with block schema objects.

## Functions

### `create_block_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_schemas.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_schema(block_schema: schemas.actions.BlockSchemaCreate, response: Response, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.BlockSchema
```

Create a block schema.

For more information, see [https://docs.prefect.io/v3/develop/blocks](https://docs.prefect.io/v3/develop/blocks).

### `delete_block_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_schemas.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_block_schema(block_schema_id: UUID = Path(..., description='The block schema id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface), api_version: str = Depends(dependencies.provide_request_api_version)) -> None
```

Delete a block schema by id.

### `read_block_schemas` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_schemas.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_schemas(block_schemas: Optional[schemas.filters.BlockSchemaFilter] = None, limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.BlockSchema]
```

Read all block schemas, optionally filtered by type

### `read_block_schema_by_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_schemas.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_schema_by_id(block_schema_id: UUID = Path(..., description='The block schema id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.BlockSchema
```

Get a block schema by id.

### `read_block_schema_by_checksum` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_schemas.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_schema_by_checksum(block_schema_checksum: str = Path(..., description='The block schema checksum', alias='checksum'), db: PrefectDBInterface = Depends(provide_database_interface), version: Optional[str] = Query(None, description='Version of block schema. If not provided the most recently created block schema with the matching checksum will be returned.')) -> schemas.core.BlockSchema
```


# block_types
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-block_types



# `prefect.server.api.block_types`

## Functions

### `create_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_type(block_type: schemas.actions.BlockTypeCreate, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.BlockType
```

Create a new block type.

For more information, see [https://docs.prefect.io/v3/develop/blocks](https://docs.prefect.io/v3/develop/blocks).

### `read_block_type_by_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_type_by_id(block_type_id: UUID = Path(..., description='The block type ID', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.BlockType
```

Get a block type by ID.

### `read_block_type_by_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_type_by_slug(block_type_slug: str = Path(..., description='The block type name', alias='slug'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.BlockType
```

Get a block type by name.

### `read_block_types` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_types(block_types: Optional[schemas.filters.BlockTypeFilter] = None, block_schemas: Optional[schemas.filters.BlockSchemaFilter] = None, limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.BlockType]
```

Gets all block types. Optionally limit return with limit and offset.

### `update_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_block_type(block_type: schemas.actions.BlockTypeUpdate, block_type_id: UUID = Path(..., description='The block type ID', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Update a block type.

### `delete_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_block_type(block_type_id: UUID = Path(..., description='The block type ID', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `read_block_documents_for_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_documents_for_block_type(db: PrefectDBInterface = Depends(provide_database_interface), block_type_slug: str = Path(..., description='The block type name', alias='slug'), include_secrets: bool = Query(False, description='Whether to include sensitive values in the block document.')) -> List[schemas.core.BlockDocument]
```

### `read_block_document_by_name_for_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_document_by_name_for_block_type(db: PrefectDBInterface = Depends(provide_database_interface), block_type_slug: str = Path(..., description='The block type name', alias='slug'), block_document_name: str = Path(..., description='The block type name'), include_secrets: bool = Query(False, description='Whether to include sensitive values in the block document.')) -> schemas.core.BlockDocument
```

### `install_system_block_types` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/block_types.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
install_system_block_types(db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```


# clients
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-clients



# `prefect.server.api.clients`

## Classes

### `BaseClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `OrchestrationClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `create_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run(self, deployment_id: UUID, flow_run_create: DeploymentFlowRunCreate) -> Response
```

#### `pause_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause_deployment(self, deployment_id: UUID) -> Response
```

#### `pause_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause_work_pool(self, work_pool_name: str) -> Response
```

#### `pause_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause_work_queue(self, work_queue_id: UUID) -> Response
```

#### `read_block_document_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_document_raw(self, block_document_id: UUID, include_secrets: bool = True) -> Response
```

#### `read_concurrency_limit_v2_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limit_v2_raw(self, concurrency_limit_id: UUID) -> Response
```

#### `read_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment(self, deployment_id: UUID) -> Optional[DeploymentResponse]
```

#### `read_deployment_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment_raw(self, deployment_id: UUID) -> Response
```

#### `read_flow_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_raw(self, flow_id: UUID) -> Response
```

#### `read_flow_run_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_raw(self, flow_run_id: UUID) -> Response
```

#### `read_task_run_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_raw(self, task_run_id: UUID) -> Response
```

#### `read_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_pool(self, work_pool_id: UUID) -> Optional[WorkPool]
```

#### `read_work_pool_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_pool_raw(self, work_pool_id: UUID) -> Response
```

#### `read_work_queue_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_raw(self, work_queue_id: UUID) -> Response
```

#### `read_work_queue_status_raw` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_status_raw(self, work_queue_id: UUID) -> Response
```

#### `read_workspace_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_workspace_variables(self, names: Optional[List[str]] = None) -> Dict[str, StrictVariableValue]
```

#### `request` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/base.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
request(self, method: HTTP_METHODS, path: 'ServerRoutes', params: dict[str, Any] | None = None, path_params: dict[str, Any] | None = None, **kwargs: Any) -> 'Response'
```

#### `resume_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_deployment(self, deployment_id: UUID) -> Response
```

#### `resume_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_flow_run(self, flow_run_id: UUID) -> OrchestrationResult
```

#### `resume_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_work_pool(self, work_pool_name: str) -> Response
```

#### `resume_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_work_queue(self, work_queue_id: UUID) -> Response
```

#### `set_flow_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_flow_run_state(self, flow_run_id: UUID, state: StateCreate) -> Response
```

### `WorkPoolsOrchestrationClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `read_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/clients.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
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.

#### `request` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/client/orchestration/base.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
request(self, method: HTTP_METHODS, path: 'ServerRoutes', params: dict[str, Any] | None = None, path_params: dict[str, Any] | None = None, **kwargs: Any) -> 'Response'
```


# collections
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-collections



# `prefect.server.api.collections`

## Functions

### `read_view_content` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/collections.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_view_content(view: str) -> Dict[str, Any]
```

Reads the content of a view from the prefect-collection-registry.

### `get_collection_view` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/collections.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_collection_view(view: str) -> dict[str, Any]
```


# concurrency_limits
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-concurrency_limits



# `prefect.server.api.concurrency_limits`

Routes for interacting with concurrency limit objects.

This module provides a V1 API adapter that routes requests to the V2 concurrency
system. After the migration, V1 limits are converted to V2, but the V1 API
continues to work for backward compatibility.

## Functions

### `create_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_concurrency_limit(concurrency_limit: schemas.actions.ConcurrencyLimitCreate, response: Response, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.ConcurrencyLimit
```

Create a task run concurrency limit.

For more information, see [https://docs.prefect.io/v3/develop/task-run-limits](https://docs.prefect.io/v3/develop/task-run-limits).

### `read_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limit(concurrency_limit_id: UUID = Path(..., description='The concurrency limit id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.ConcurrencyLimit
```

Get a concurrency limit by id.

The `active slots` field contains a list of TaskRun IDs currently using a
concurrency slot for the specified tag.

### `read_concurrency_limit_by_tag` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limit_by_tag(tag: str = Path(..., description='The tag name', alias='tag'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.ConcurrencyLimit
```

Get a concurrency limit by tag.

The `active slots` field contains a list of TaskRun IDs currently using a
concurrency slot for the specified tag.

### `read_concurrency_limits` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limits(limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), db: PrefectDBInterface = Depends(provide_database_interface)) -> Sequence[schemas.core.ConcurrencyLimit]
```

Query for concurrency limits.

For each concurrency limit the `active slots` field contains a list of TaskRun IDs
currently using a concurrency slot for the specified tag.

### `reset_concurrency_limit_by_tag` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_concurrency_limit_by_tag(tag: str = Path(..., description='The tag name'), slot_override: Optional[List[UUID]] = Body(None, embed=True, description='Manual override for active concurrency limit slots.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `delete_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_concurrency_limit(concurrency_limit_id: UUID = Path(..., description='The concurrency limit id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `delete_concurrency_limit_by_tag` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_concurrency_limit_by_tag(tag: str = Path(..., description='The tag name'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `increment_concurrency_limits_v1` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L440" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
increment_concurrency_limits_v1(names: List[str] = Body(..., description='The tags to acquire a slot for'), task_run_id: UUID = Body(..., description='The ID of the task run acquiring the slot'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[MinimalConcurrencyLimitResponse]
```

Increment concurrency limits for the given tags.

During migration, this handles both V1 and V2 limits to support mixed states.
Post-migration, it only uses V2 with lease-based concurrency.

### `decrement_concurrency_limits_v1` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L575" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
decrement_concurrency_limits_v1(names: List[str] = Body(..., description='The tags to release a slot for'), task_run_id: UUID = Body(..., description='The ID of the task run releasing the slot'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[MinimalConcurrencyLimitResponse]
```

Decrement concurrency limits for the given tags.

Finds and revokes the lease for V2 limits or decrements V1 active slots.
Returns the list of limits that were decremented.

## Classes

### `Abort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L428" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Delay` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# concurrency_limits_v2
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-concurrency_limits_v2



# `prefect.server.api.concurrency_limits_v2`

## Functions

### `create_concurrency_limit_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_concurrency_limit_v2(concurrency_limit: actions.ConcurrencyLimitV2Create, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.ConcurrencyLimitV2
```

Create a task run concurrency limit.

For more information, see [https://docs.prefect.io/v3/develop/global-concurrency-limits](https://docs.prefect.io/v3/develop/global-concurrency-limits).

### `read_concurrency_limit_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limit_v2(id_or_name: Union[UUID, str] = Path(..., description='The ID or name of the concurrency limit', alias='id_or_name'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.GlobalConcurrencyLimitResponse
```

### `read_all_concurrency_limits_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_all_concurrency_limits_v2(limit: int = LimitBody(), offset: int = Body(0, ge=0), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.GlobalConcurrencyLimitResponse]
```

### `update_concurrency_limit_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_concurrency_limit_v2(concurrency_limit: actions.ConcurrencyLimitV2Update, id_or_name: Union[UUID, str] = Path(..., description='The ID or name of the concurrency limit', alias='id_or_name'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `delete_concurrency_limit_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_concurrency_limit_v2(id_or_name: Union[UUID, str] = Path(..., description='The ID or name of the concurrency limit', alias='id_or_name'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `bulk_increment_active_slots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_increment_active_slots(slots: int = Body(..., gt=0), names: List[str] = Body(..., min_items=1), mode: Literal['concurrency', 'rate_limit'] = Body('concurrency'), create_if_missing: Optional[bool] = Body(None, deprecated='Limits must be explicitly created before acquiring concurrency slots.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[MinimalConcurrencyLimitResponse]
```

### `bulk_increment_active_slots_with_lease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_increment_active_slots_with_lease(slots: int = Body(..., gt=0), names: List[str] = Body(..., min_items=1), mode: Literal['concurrency', 'rate_limit'] = Body('concurrency'), lease_duration: float = Body(300, ge=60, le=60 * 60 * 24, description='The duration of the lease in seconds.'), holder: Optional[ConcurrencyLeaseHolder] = Body(None, description='The holder of the lease with type (flow_run, task_run, or deployment) and id.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> ConcurrencyLimitWithLeaseResponse
```

### `bulk_decrement_active_slots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L343" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_decrement_active_slots(slots: int = Body(..., gt=0), names: List[str] = Body(..., min_items=1), occupancy_seconds: Optional[float] = Body(None, gt=0.0), create_if_missing: bool = Body(None, deprecated='Limits must be explicitly created before decrementing active slots.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[MinimalConcurrencyLimitResponse]
```

### `bulk_decrement_active_slots_with_lease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L377" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_decrement_active_slots_with_lease(lease_id: UUID = Body(..., description='The ID of the lease corresponding to the concurrency limits to decrement.', embed=True), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `renew_concurrency_lease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
renew_concurrency_lease(lease_id: UUID = Path(..., description='The ID of the lease to renew'), lease_duration: float = Body(300, ge=60, le=60 * 60 * 24, description='The duration of the lease in seconds.', embed=True)) -> None
```

## Classes

### `MinimalConcurrencyLimitResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `ConcurrencyLimitWithLeaseResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/concurrency_limits_v2.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# csrf_token
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-csrf_token



# `prefect.server.api.csrf_token`

## Functions

### `create_csrf_token` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/csrf_token.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_csrf_token(db: PrefectDBInterface = Depends(provide_database_interface), client: str = Query(..., description='The client to create a CSRF token for')) -> schemas.core.CsrfToken
```

Create or update a CSRF token for a client


# dependencies
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-dependencies



# `prefect.server.api.dependencies`

Utilities for injecting FastAPI dependencies.

## Functions

### `provide_request_api_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/dependencies.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provide_request_api_version(x_prefect_api_version: str = Header(None)) -> Version | None
```

### `LimitBody` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/dependencies.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
LimitBody() -> Any
```

A `fastapi.Depends` factory for pulling a `limit: int` parameter from the
request body while determining the default from the current settings.

### `get_created_by` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/dependencies.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_created_by(prefect_automation_id: Optional[UUID] = Header(None, include_in_schema=False), prefect_automation_name: Optional[str] = Header(None, include_in_schema=False)) -> Optional[schemas.core.CreatedBy]
```

A dependency that returns the provenance information to use when creating objects
during this API call.

### `get_updated_by` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/dependencies.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_updated_by(prefect_automation_id: Optional[UUID] = Header(None, include_in_schema=False), prefect_automation_name: Optional[str] = Header(None, include_in_schema=False)) -> Optional[schemas.core.UpdatedBy]
```

A dependency that returns the provenance information to use when updating objects
during this API call.

### `is_ephemeral_request` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/dependencies.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_ephemeral_request(request: Request) -> bool
```

A dependency that returns whether the request is to an ephemeral server.

### `get_prefect_client_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/dependencies.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_prefect_client_version(user_agent: Annotated[Optional[str], Header(include_in_schema=False)] = None) -> Optional[str]
```

Attempts to parse out the Prefect client version from the User-Agent header.

## Classes

### `EnforceMinimumAPIVersion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/dependencies.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

FastAPI Dependency used to check compatibility between the version of the api
and a given request.

Looks for the header 'X-PREFECT-API-VERSION' in the request and compares it
to the api's version. Rejects requests that are lower than the minimum version.


# deployments
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-deployments



# `prefect.server.api.deployments`

Routes for interacting with Deployment objects.

## Functions

### `create_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_deployment(deployment: schemas.actions.DeploymentCreate, response: Response, worker_lookups: WorkerLookups = Depends(WorkerLookups), created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by), updated_by: Optional[schemas.core.UpdatedBy] = Depends(dependencies.get_updated_by), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.DeploymentResponse
```

Gracefully creates a new deployment from the provided schema. If a deployment with
the same name and flow\_id already exists, the deployment is updated.

If the deployment has an active schedule, flow runs will be scheduled.
When upserting, any scheduled runs from the existing deployment will be deleted.

For more information, see [https://docs.prefect.io/v3/deploy](https://docs.prefect.io/v3/deploy).

### `update_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_deployment(deployment: schemas.actions.DeploymentUpdate, deployment_id: UUID = Path(..., description='The deployment id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `read_deployment_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L372" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment_by_name(flow_name: str = Path(..., description='The name of the flow'), deployment_name: str = Path(..., description='The name of the deployment'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.DeploymentResponse
```

Get a deployment using the name of the flow and the deployment.

### `read_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L394" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.DeploymentResponse
```

Get a deployment by id.

### `read_deployments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L415" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployments(limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None, sort: schemas.sorting.DeploymentSort = Body(schemas.sorting.DeploymentSort.NAME_ASC), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.DeploymentResponse]
```

Query for deployments.

### `paginate_deployments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L454" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
paginate_deployments(limit: int = dependencies.LimitBody(), page: int = Body(1, ge=1), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None, sort: schemas.sorting.DeploymentSort = Body(schemas.sorting.DeploymentSort.NAME_ASC), db: PrefectDBInterface = Depends(provide_database_interface)) -> DeploymentPaginationResponse
```

Pagination query for flow runs.

### `get_scheduled_flow_runs_for_deployments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L514" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs_for_deployments(background_tasks: BackgroundTasks, deployment_ids: list[UUID] = Body(default=..., description='The deployment IDs to get scheduled runs for'), scheduled_before: DateTime = Body(None, description='The maximum time to look for scheduled flow runs'), limit: int = dependencies.LimitBody(), db: PrefectDBInterface = Depends(provide_database_interface)) -> list[schemas.responses.FlowRunResponse]
```

Get scheduled runs for a set of deployments. Used by a runner to poll for work.

### `count_deployments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L565" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_deployments(flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

Count deployments.

### `delete_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L590" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_deployment(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a deployment by id.

### `schedule_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L608" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schedule_deployment(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), start_time: datetime.datetime = Body(None, description='The earliest date to schedule'), end_time: datetime.datetime = Body(None, description='The latest date to schedule'), min_time: float = Body(None, description='Runs will be scheduled until at least this long after the `start_time`', json_schema_extra={'format': 'time-delta'}), min_runs: int = Body(None, description='The minimum number of runs to schedule'), max_runs: int = Body(None, description='The maximum number of runs to schedule'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Schedule runs for a deployment. For backfills, provide start/end times in the past.

This function will generate the minimum number of runs that satisfy the min
and max times, and the min and max counts. Specifically, the following order
will be respected.

* Runs will be generated starting on or after the `start_time`
* No more than `max_runs` runs will be generated
* No runs will be generated after `end_time` is reached
* At least `min_runs` runs will be generated
* Runs will be generated until at least `start_time + min_time` is reached

### `resume_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L656" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_deployment(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Set a deployment schedule to active. Runs will be scheduled immediately.

### `pause_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L675" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause_deployment(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled
state will be deleted.

### `create_flow_run_from_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L707" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run_from_deployment(flow_run: schemas.actions.DeploymentFlowRunCreate, deployment_id: UUID = Path(..., description='The deployment id', alias='id'), created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by), db: PrefectDBInterface = Depends(provide_database_interface), worker_lookups: WorkerLookups = Depends(WorkerLookups), response: Response = None) -> schemas.responses.FlowRunResponse
```

Create a flow run from a deployment.

Any parameters not provided will be inferred from the deployment's parameters.
If tags are not provided, the deployment's tags will be used.

If no state is provided, the flow run will be created in a SCHEDULED state.

### `work_queue_check_for_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L846" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
work_queue_check_for_deployment(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.WorkQueue]
```

Get list of work-queues that are able to pick up the specified deployment.

This endpoint is intended to be used by the UI to provide users warnings
about deployments that are unable to be executed because there are no work
queues that will pick up their runs, based on existing filter criteria. It
may be deprecated in the future because there is not a strict relationship
between work queues and deployments.

### `read_deployment_schedules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L872" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment_schedules(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.DeploymentSchedule]
```

### `create_deployment_schedules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L893" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_deployment_schedules(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), schedules: List[schemas.actions.DeploymentScheduleCreate] = Body(default=..., description='The schedules to create'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.DeploymentSchedule]
```

### `update_deployment_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L929" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_deployment_schedule(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), schedule_id: UUID = Path(..., description='The schedule id', alias='schedule_id'), schedule: schemas.actions.DeploymentScheduleUpdate = Body(default=..., description='The updated schedule'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `delete_deployment_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/deployments.py#L968" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_deployment_schedule(deployment_id: UUID = Path(..., description='The deployment id', alias='id'), schedule_id: UUID = Path(..., description='The schedule id', alias='schedule_id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```


# events
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-events



# `prefect.server.api.events`

## Functions

### `create_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_events(events: List[Event], ephemeral_request: bool = Depends(is_ephemeral_request)) -> None
```

Record a batch of Events.

For more information, see [https://docs.prefect.io/v3/concepts/events](https://docs.prefect.io/v3/concepts/events).

### `stream_events_in` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stream_events_in(websocket: WebSocket) -> None
```

Open a WebSocket to stream incoming Events

### `stream_workspace_events_out` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stream_workspace_events_out(websocket: WebSocket) -> None
```

Open a WebSocket to stream Events

### `verified_page_token` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
verified_page_token(page_token: str = Query(..., alias='page-token')) -> str
```

### `read_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_events(request: Request, filter: Optional[EventFilter] = Body(None, description='Additional optional filter criteria to narrow down the set of Events'), limit: int = Body(INTERACTIVE_PAGE_SIZE, ge=0, le=INTERACTIVE_PAGE_SIZE, embed=True, description='The number of events to return with each page'), db: PrefectDBInterface = Depends(provide_database_interface)) -> EventPage
```

Queries for Events matching the given filter criteria in the given Account.  Returns
the first page of results, and the URL to request the next page (if there are more
results).

### `read_account_events_page` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_account_events_page(request: Request, page_token: str = Depends(verified_page_token), db: PrefectDBInterface = Depends(provide_database_interface)) -> EventPage
```

Returns the next page of Events for a previous query against the given Account, and
the URL to request the next page (if there are more results).

### `generate_next_page_link` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_next_page_link(request: Request, page_token: Optional[str]) -> Optional[str]
```

### `count_account_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_account_events(filter: EventFilter, countable: Countable = Path(...), time_unit: TimeUnit = Body(default=TimeUnit.day), time_interval: float = Body(default=1.0, ge=0.01), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[EventCount]
```

Returns distinct objects and the count of events associated with them.  Objects
that can be counted include the day the event occurred, the type of event, or
the IDs of the resources associated with the event.

### `handle_event_count_request` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/events.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_event_count_request(session: AsyncSession, filter: EventFilter, countable: Countable, time_unit: TimeUnit, time_interval: float) -> List[EventCount]
```


# flow_run_states
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-flow_run_states



# `prefect.server.api.flow_run_states`

Routes for interacting with flow run state objects.

## Functions

### `read_flow_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_run_states.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_state(flow_run_state_id: UUID = Path(..., description='The flow run state id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.states.State
```

Get a flow run state by id.

For more information, see [https://docs.prefect.io/v3/develop/write-flows#final-state-determination](https://docs.prefect.io/v3/develop/write-flows#final-state-determination).

### `read_flow_run_states` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_run_states.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_states(flow_run_id: UUID, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.states.State]
```

Get states associated with a flow run.


# flow_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-flow_runs



# `prefect.server.api.flow_runs`

Routes for interacting with flow run objects.

## Functions

### `create_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run(flow_run: schemas.actions.FlowRunCreate, db: PrefectDBInterface = Depends(provide_database_interface), response: Response = None, created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by), orchestration_parameters: Dict[str, Any] = Depends(orchestration_dependencies.provide_flow_orchestration_parameters), api_version: str = Depends(dependencies.provide_request_api_version), worker_lookups: WorkerLookups = Depends(WorkerLookups)) -> schemas.responses.FlowRunResponse
```

Create a flow run. If a flow run with the same flow\_id and
idempotency key already exists, the existing flow run will be returned.

If no state is provided, the flow run will be created in a PENDING state.

For more information, see [https://docs.prefect.io/v3/develop/write-flows](https://docs.prefect.io/v3/develop/write-flows).

### `update_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_flow_run(flow_run: schemas.actions.FlowRunUpdate, flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Updates a flow run.

### `count_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_flow_runs(flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

Query for flow runs.

### `average_flow_run_lateness` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
average_flow_run_lateness(flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> Optional[float]
```

Query for average flow-run lateness in seconds.

### `flow_run_history` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_history(history_start: DateTime = Body(..., description="The history's start time."), history_end: DateTime = Body(..., description="The history's end time."), history_interval: float = Body(..., description='The size of each history interval, in seconds. Must be at least 1 second.', json_schema_extra={'format': 'time-delta'}, alias='history_interval_seconds'), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.HistoryResponse]
```

Query for flow run history data across a given range and interval.

### `read_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.FlowRunResponse
```

Get a flow run by id.

### `read_flow_run_graph_v1` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_graph_v1(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[DependencyResult]
```

Get a task run dependency map for a given flow run.

### `read_flow_run_graph_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L354" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_graph_v2(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), since: datetime.datetime = Query(default=jsonable_encoder(earliest_possible_datetime()), description='Only include runs that start or end after this time.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> Graph
```

Get a graph of the tasks and subflow runs for the given flow run

### `resume_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_flow_run(response: Response, flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface), run_input: Optional[dict[str, Any]] = Body(default=None, embed=True), flow_policy: type[FlowRunOrchestrationPolicy] = Depends(orchestration_dependencies.provide_flow_policy), task_policy: type[TaskRunOrchestrationPolicy] = Depends(orchestration_dependencies.provide_task_policy), orchestration_parameters: Dict[str, Any] = Depends(orchestration_dependencies.provide_flow_orchestration_parameters), api_version: str = Depends(dependencies.provide_request_api_version), client_version: Optional[str] = Depends(dependencies.get_prefect_client_version)) -> OrchestrationResult
```

Resume a paused flow run.

### `read_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L533" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_runs(sort: schemas.sorting.FlowRunSort = Body(schemas.sorting.FlowRunSort.ID_DESC), limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.FlowRunResponse]
```

Query for flow runs.

### `delete_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L576" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow_run(background_tasks: BackgroundTasks, flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a flow run by id.

### `delete_flow_run_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L595" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow_run_logs(db: PrefectDBInterface, flow_run_id: UUID) -> None
```

### `set_flow_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L606" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_flow_run_state(response: Response, flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), state: schemas.actions.StateCreate = Body(..., description='The intended state.'), force: bool = Body(False, description='If false, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied.'), db: PrefectDBInterface = Depends(provide_database_interface), flow_policy: type[FlowRunOrchestrationPolicy] = Depends(orchestration_dependencies.provide_flow_policy), orchestration_parameters: Dict[str, Any] = Depends(orchestration_dependencies.provide_flow_orchestration_parameters), api_version: str = Depends(dependencies.provide_request_api_version), client_version: Optional[str] = Depends(dependencies.get_prefect_client_version)) -> OrchestrationResult
```

Set a flow run state, invoking any orchestration rules.

### `create_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L659" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run_input(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), key: str = Body(..., description='The input key'), value: bytes = Body(..., description='The value of the input'), sender: Optional[str] = Body(None, description='The sender of the input'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Create a key/value input for a flow run.

### `filter_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L695" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter_flow_run_input(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), prefix: str = Body(..., description='The input key prefix', embed=True), limit: int = Body(1, description='The maximum number of results to return', embed=True), exclude_keys: List[str] = Body([], description='Exclude inputs with these keys', embed=True), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.FlowRunInput]
```

Filter flow run inputs by key prefix

### `read_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L720" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_input(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), key: str = Path(..., description='The input key', alias='key'), db: PrefectDBInterface = Depends(provide_database_interface)) -> PlainTextResponse
```

Create a value from a flow run input

### `delete_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L743" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow_run_input(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), key: str = Path(..., description='The input key', alias='key'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a flow run input

### `paginate_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L765" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
paginate_flow_runs(sort: schemas.sorting.FlowRunSort = Body(schemas.sorting.FlowRunSort.ID_DESC), limit: int = dependencies.LimitBody(), page: int = Body(1, ge=1), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> FlowRunPaginationResponse
```

Pagination query for flow runs.

### `download_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L832" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
download_logs(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> StreamingResponse
```

Download all flow run logs as a CSV file, collecting all logs until there are no more logs to retrieve.

### `update_flow_run_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flow_runs.py#L898" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_flow_run_labels(flow_run_id: UUID = Path(..., description='The flow run id', alias='id'), labels: Dict[str, Any] = Body(..., description='The labels to update'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Update the labels of a flow run.


# flows
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-flows



# `prefect.server.api.flows`

Routes for interacting with flow objects.

## Functions

### `create_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow(flow: schemas.actions.FlowCreate, response: Response, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.Flow
```

Gracefully creates a new flow from the provided schema. If a flow with the
same name already exists, the existing flow is returned.

For more information, see [https://docs.prefect.io/v3/develop/write-flows](https://docs.prefect.io/v3/develop/write-flows).

### `update_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_flow(flow: schemas.actions.FlowUpdate, flow_id: UUID = Path(..., description='The flow id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Updates a flow.

### `count_flows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_flows(flows: schemas.filters.FlowFilter = None, flow_runs: schemas.filters.FlowRunFilter = None, task_runs: schemas.filters.TaskRunFilter = None, deployments: schemas.filters.DeploymentFilter = None, work_pools: schemas.filters.WorkPoolFilter = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

Count flows.

### `read_flow_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_by_name(name: str = Path(..., description='The name of the flow'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.Flow
```

Get a flow by name.

### `read_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow(flow_id: UUID = Path(..., description='The flow id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.Flow
```

Get a flow by id.

### `read_flows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flows(limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), flows: schemas.filters.FlowFilter = None, flow_runs: schemas.filters.FlowRunFilter = None, task_runs: schemas.filters.TaskRunFilter = None, deployments: schemas.filters.DeploymentFilter = None, work_pools: schemas.filters.WorkPoolFilter = None, sort: schemas.sorting.FlowSort = Body(schemas.sorting.FlowSort.NAME_ASC), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.Flow]
```

Query for flows.

### `delete_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow(flow_id: UUID = Path(..., description='The flow id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a flow by id.

### `paginate_flows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/flows.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
paginate_flows(limit: int = dependencies.LimitBody(), page: int = Body(1, ge=1), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, sort: schemas.sorting.FlowSort = Body(schemas.sorting.FlowSort.NAME_ASC), db: PrefectDBInterface = Depends(provide_database_interface)) -> FlowPaginationResponse
```

Pagination query for flows.


# logs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-logs



# `prefect.server.api.logs`

Routes for interacting with log objects.

## Functions

### `create_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/logs.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_logs(logs: Sequence[LogCreate], db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Create new logs from the provided schema.

For more information, see [https://docs.prefect.io/v3/develop/logging](https://docs.prefect.io/v3/develop/logging).

### `read_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/logs.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_logs(limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), logs: Optional[LogFilter] = None, sort: LogSort = Body(LogSort.TIMESTAMP_ASC), db: PrefectDBInterface = Depends(provide_database_interface)) -> Sequence[Log]
```

Query for logs.

### `stream_logs_out` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/logs.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stream_logs_out(websocket: WebSocket) -> None
```

Serve a WebSocket to stream live logs


# middleware
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-middleware



# `prefect.server.api.middleware`

## Classes

### `CsrfMiddleware` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/middleware.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Middleware for CSRF protection. This middleware will check for a CSRF token
in the headers of any POST, PUT, PATCH, or DELETE request. If the token is
not present or does not match the token stored in the database for the
client, the request will be rejected with a 403 status code.

**Methods:**

#### `dispatch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/middleware.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dispatch(self, request: Request, call_next: NextMiddlewareFunction) -> Response
```

Dispatch method for the middleware. This method will check for the
presence of a CSRF token in the headers of the request and compare it
to the token stored in the database for the client. If the token is not
present or does not match, the request will be rejected with a 403
status code.


# root
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-root



# `prefect.server.api.root`

Contains the `hello` route for testing and healthcheck purposes.

## Functions

### `hello` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/root.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hello() -> str
```

Say hello!

### `perform_readiness_check` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/root.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
perform_readiness_check(db: PrefectDBInterface = Depends(provide_database_interface)) -> JSONResponse
```


# run_history
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-run_history



# `prefect.server.api.run_history`

Utilities for querying flow and task run history.

## Functions

### `run_history` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/run_history.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_history(db: PrefectDBInterface, session: sa.orm.Session, run_type: Literal['flow_run', 'task_run'], history_start: DateTime, history_end: DateTime, history_interval: datetime.timedelta, flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_queues: Optional[schemas.filters.WorkQueueFilter] = None) -> list[schemas.responses.HistoryResponse]
```

Produce a history of runs aggregated by interval and state


# saved_searches
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-saved_searches



# `prefect.server.api.saved_searches`

Routes for interacting with saved search objects.

## Functions

### `create_saved_search` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/saved_searches.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_saved_search(saved_search: schemas.actions.SavedSearchCreate, response: Response, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.SavedSearch
```

Gracefully creates a new saved search from the provided schema.

If a saved search with the same name already exists, the saved search's fields are
replaced.

### `read_saved_search` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/saved_searches.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_saved_search(saved_search_id: UUID = Path(..., description='The saved search id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.SavedSearch
```

Get a saved search by id.

### `read_saved_searches` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/saved_searches.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_saved_searches(limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.SavedSearch]
```

Query for saved searches.

### `delete_saved_search` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/saved_searches.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_saved_search(saved_search_id: UUID = Path(..., description='The saved search id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a saved search by id.


# server
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-server



# `prefect.server.api.server`

Defines the Prefect REST API FastAPI app.

## Functions

### `validation_exception_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse
```

Provide a detailed message for request validation errors.

### `integrity_exception_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L219" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
integrity_exception_handler(request: Request, exc: Exception) -> JSONResponse
```

Capture database integrity errors.

### `is_client_retryable_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_client_retryable_exception(exc: Exception) -> bool
```

### `replace_placeholder_string_in_files` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
replace_placeholder_string_in_files(directory: str, placeholder: str, replacement: str, allowed_extensions: list[str] | None = None) -> None
```

Recursively loops through all files in the given directory and replaces
a placeholder string.

### `copy_directory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
copy_directory(directory: str, path: str) -> None
```

### `custom_internal_exception_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
custom_internal_exception_handler(request: Request, exc: Exception) -> JSONResponse
```

Log a detailed exception for internal server errors before returning.

Send 503 for errors clients can retry on.

### `prefect_object_not_found_exception_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_object_not_found_exception_handler(request: Request, exc: ObjectNotFoundError) -> JSONResponse
```

Return 404 status code on object not found exceptions.

### `create_api_app` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_api_app(dependencies: list[Any] | None = None, health_check_path: str = '/health', version_check_path: str = '/version', fast_api_app_kwargs: dict[str, Any] | None = None, final: bool = False, ignore_cache: bool = False) -> FastAPI
```

Create a FastAPI app that includes the Prefect REST API

**Args:**

* `dependencies`: a list of global dependencies to add to each Prefect REST API router
* `health_check_path`: the health check route path
* `fast_api_app_kwargs`: kwargs to pass to the FastAPI constructor
* `final`: whether this will be the last instance of the Prefect server to be
  created in this process, so that additional optimizations may be applied
* `ignore_cache`: if set, a new app will be created even if the settings and fast\_api\_app\_kwargs match
  an existing app in the cache

**Returns:**

* a FastAPI app that serves the Prefect REST API

### `create_ui_app` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L462" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_ui_app(ephemeral: bool) -> FastAPI
```

### `create_app` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L620" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_app(settings: Optional[prefect.settings.Settings] = None, ephemeral: bool = False, webserver_only: bool = False, final: bool = False, ignore_cache: bool = False) -> FastAPI
```

Create a FastAPI app that includes the Prefect REST API and UI

**Args:**

* `settings`: The settings to use to create the app. If not set, settings are pulled
  from the context.
* `ephemeral`: If set, the application will be treated as ephemeral. The UI
  and services will be disabled.
* `webserver_only`: If set, the webserver and UI will be available but all background
  services will be disabled.
* `final`: whether this will be the last instance of the Prefect server to be
  created in this process, so that additional optimizations may be applied
* `ignore_cache`: If set, a new application will be created even if the settings
  match. Otherwise, an application is returned from the cache.

## Classes

### `SPAStaticFiles` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Implementation of `StaticFiles` for serving single page applications.

Adds `get_response` handling to ensure that when a resource isn't found the
application still returns the index.

**Methods:**

#### `get_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_response(self, path: str, scope: Any) -> Response
```

### `RequestLimitMiddleware` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L185" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A middleware that limits the number of concurrent requests handled by the API.

This is a blunt tool for limiting SQLite concurrent writes which will cause failures
at high volume. Ideally, we would only apply the limit to routes that perform
writes.

### `SubprocessASGIServer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L814" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `address` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
address(self) -> str
```

#### `api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L861" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
api_url(self) -> str
```

#### `find_available_port` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L836" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
find_available_port(self) -> int
```

#### `is_port_available` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L846" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_port_available(port: int) -> bool
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, timeout: Optional[int] = None) -> None
```

Start the server in a separate process. Safe to call multiple times; only starts
the server once.

**Args:**

* `timeout`: The maximum time to wait for the server to start

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/server.py#L958" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```


# task_run_states
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-task_run_states



# `prefect.server.api.task_run_states`

Routes for interacting with task run state objects.

## Functions

### `read_task_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_run_states.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_state(task_run_state_id: UUID = Path(..., description='The task run state id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.states.State
```

Get a task run state by id.

For more information, see [https://docs.prefect.io/v3/develop/write-tasks](https://docs.prefect.io/v3/develop/write-tasks).

### `read_task_run_states` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_run_states.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_states(task_run_id: UUID, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.states.State]
```

Get states associated with a task run.


# task_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-task_runs



# `prefect.server.api.task_runs`

Routes for interacting with task run objects.

## Functions

### `create_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_task_run(task_run: schemas.actions.TaskRunCreate, response: Response, db: PrefectDBInterface = Depends(provide_database_interface), orchestration_parameters: Dict[str, Any] = Depends(orchestration_dependencies.provide_task_orchestration_parameters)) -> schemas.core.TaskRun
```

Create a task run. If a task run with the same flow\_run\_id,
task\_key, and dynamic\_key already exists, the existing task
run will be returned.

If no state is provided, the task run will be created in a PENDING state.

For more information, see [https://docs.prefect.io/v3/develop/write-tasks](https://docs.prefect.io/v3/develop/write-tasks).

### `update_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_task_run(task_run: schemas.actions.TaskRunUpdate, task_run_id: UUID = Path(..., description='The task run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Updates a task run.

### `count_task_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_task_runs(db: PrefectDBInterface = Depends(provide_database_interface), flows: schemas.filters.FlowFilter = None, flow_runs: schemas.filters.FlowRunFilter = None, task_runs: schemas.filters.TaskRunFilter = None, deployments: schemas.filters.DeploymentFilter = None) -> int
```

Count task runs.

### `task_run_history` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_history(history_start: DateTime = Body(..., description="The history's start time."), history_end: DateTime = Body(..., description="The history's end time."), history_interval: float = Body(..., description='The size of each history interval, in seconds. Must be at least 1 second.', json_schema_extra={'format': 'time-delta'}, alias='history_interval_seconds'), flows: schemas.filters.FlowFilter = None, flow_runs: schemas.filters.FlowRunFilter = None, task_runs: schemas.filters.TaskRunFilter = None, deployments: schemas.filters.DeploymentFilter = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.HistoryResponse]
```

Query for task run history data across a given range and interval.

### `read_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run(task_run_id: UUID = Path(..., description='The task run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.TaskRun
```

Get a task run by id.

### `read_task_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_runs(sort: schemas.sorting.TaskRunSort = Body(schemas.sorting.TaskRunSort.ID_DESC), limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.core.TaskRun]
```

Query for task runs.

### `paginate_task_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
paginate_task_runs(sort: schemas.sorting.TaskRunSort = Body(schemas.sorting.TaskRunSort.ID_DESC), limit: int = dependencies.LimitBody(), page: int = Body(1, ge=1), flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> TaskRunPaginationResponse
```

Pagination query for task runs.

### `delete_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_task_run(background_tasks: BackgroundTasks, task_run_id: UUID = Path(..., description='The task run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a task run by id.

### `delete_task_run_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_task_run_logs(db: PrefectDBInterface, task_run_id: UUID) -> None
```

### `set_task_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_task_run_state(task_run_id: UUID = Path(..., description='The task run id', alias='id'), state: schemas.actions.StateCreate = Body(..., description='The intended state.'), force: bool = Body(False, description='If false, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied.'), db: PrefectDBInterface = Depends(provide_database_interface), response: Response = None, task_policy: TaskRunOrchestrationPolicy = Depends(orchestration_dependencies.provide_task_policy), orchestration_parameters: Dict[str, Any] = Depends(orchestration_dependencies.provide_task_orchestration_parameters)) -> OrchestrationResult
```

Set a task run state, invoking any orchestration rules.

### `scheduled_task_subscription` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_runs.py#L346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
scheduled_task_subscription(websocket: WebSocket) -> None
```


# task_workers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-task_workers



# `prefect.server.api.task_workers`

## Functions

### `read_task_workers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_workers.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_workers(task_worker_filter: Optional[TaskWorkerFilter] = Body(default=None, description='The task worker filter', embed=True)) -> List[TaskWorkerResponse]
```

Read active task workers. Optionally filter by task keys.

For more information, see [https://docs.prefect.io/v3/concepts/flows-and-tasks#background-tasks](https://docs.prefect.io/v3/concepts/flows-and-tasks#background-tasks).

## Classes

### `TaskWorkerFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/task_workers.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# templates
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-templates



# `prefect.server.api.templates`

## Functions

### `validate_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/templates.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_template(template: str = Body(default='')) -> Response
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-ui-__init__



# `prefect.server.api.ui`

Routes primarily for use by the UI


# flow_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-ui-flow_runs



# `prefect.server.api.ui.flow_runs`

## Functions

### `read_flow_run_history` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/flow_runs.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_history(sort: schemas.sorting.FlowRunSort = Body(schemas.sorting.FlowRunSort.EXPECTED_START_TIME_DESC), limit: int = Body(1000, le=1000), offset: int = Body(0, ge=0), flows: schemas.filters.FlowFilter = None, flow_runs: schemas.filters.FlowRunFilter = None, task_runs: schemas.filters.TaskRunFilter = None, deployments: schemas.filters.DeploymentFilter = None, work_pools: schemas.filters.WorkPoolFilter = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[SimpleFlowRun]
```

### `count_task_runs_by_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/flow_runs.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_task_runs_by_flow_run(flow_run_ids: list[UUID] = Body(default=..., embed=True, max_items=200), db: PrefectDBInterface = Depends(provide_database_interface)) -> dict[UUID, int]
```

Get task run counts by flow run id.

## Classes

### `SimpleFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/flow_runs.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# flows
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-ui-flows



# `prefect.server.api.ui.flows`

## Functions

### `count_deployments_by_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/flows.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_deployments_by_flow(flow_ids: List[UUID] = Body(default=..., embed=True, max_items=200), db: PrefectDBInterface = Depends(provide_database_interface)) -> Dict[UUID, int]
```

Get deployment counts by flow id.

### `next_runs_by_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/flows.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
next_runs_by_flow(flow_ids: List[UUID] = Body(default=..., embed=True, max_items=200), db: PrefectDBInterface = Depends(provide_database_interface)) -> Dict[UUID, Optional[SimpleNextFlowRun]]
```

Get the next flow run by flow id.

## Classes

### `SimpleNextFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/flows.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `validate_next_scheduled_start_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/flows.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_next_scheduled_start_time(cls, v: DateTime | datetime) -> DateTime
```


# schemas
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-ui-schemas



# `prefect.server.api.ui.schemas`

## Functions

### `validate_obj` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/schemas.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_obj(json_schema: dict[str, Any] = Body(..., embed=True, alias='schema', validation_alias='schema', json_schema_extra={'additionalProperties': True}), values: dict[str, Any] = Body(..., embed=True, json_schema_extra={'additionalProperties': True}), db: PrefectDBInterface = Depends(provide_database_interface)) -> SchemaValuesValidationResponse
```


# task_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-ui-task_runs



# `prefect.server.api.ui.task_runs`

## Functions

### `read_dashboard_task_run_counts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/task_runs.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_dashboard_task_run_counts(task_runs: schemas.filters.TaskRunFilter, flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, work_pools: Optional[schemas.filters.WorkPoolFilter] = None, work_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[TaskRunCount]
```

### `read_task_run_counts_by_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/task_runs.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_counts_by_state(flows: Optional[schemas.filters.FlowFilter] = None, flow_runs: Optional[schemas.filters.FlowRunFilter] = None, task_runs: Optional[schemas.filters.TaskRunFilter] = None, deployments: Optional[schemas.filters.DeploymentFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.states.CountByState
```

### `read_task_run_with_flow_run_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/task_runs.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_with_flow_run_name(task_run_id: UUID = Path(..., description='The task run id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.ui.UITaskRun
```

Get a task run by id.

## Classes

### `TaskRunCount` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/task_runs.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/ui/task_runs.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self) -> dict[str, int]
```


# validation
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-validation



# `prefect.server.api.validation`

This module contains functions for validating job variables for deployments, work pools,
flow runs, and RunDeployment actions. These functions are used to validate that job
variables provided by users conform to the JSON schema defined in the work pool's base job
template.

Note some important details:

1. The order of applying job variables is: work pool's base job template, deployment, flow
   run. This means that flow run job variables override deployment job variables, which
   override work pool job variables.

2. The validation of job variables for work pools and deployments ignores required keys in
   because we don't know if the full set of overrides will include values for any required
   fields.

3. Work pools can include default values for job variables. These can be normal types or
   references to blocks. We have not been validating these values or whether default blocks
   satisfy job variable JSON schemas. To avoid failing validation for existing (otherwise
   working) data, we ignore invalid defaults when validating deployment and flow run
   variables, but not when validating the work pool's base template, e.g. during work pool
   creation or updates. If we find defaults that are invalid, we have to ignore required
   fields when we run the full validation.

4. A flow run is the terminal point for job variables, so it is the only place where
   we validate required variables and default values. Thus,
   `validate_job_variables_for_deployment_flow_run` and
   `validate_job_variables_for_run_deployment_action` check for required fields.

5. We have been using Pydantic v1 to generate work pool base job templates, and it produces
   invalid JSON schemas for some fields, e.g. tuples and optional fields. We try to fix these
   schemas on the fly while validating job variables, but there is a case we can't resolve,
   which is whether or not an optional field supports a None value. In this case, we allow
   None values to be passed in, which means that if an optional field does not actually
   allow None values, the Pydantic model will fail to validate at runtime.

## Functions

### `validate_job_variables_for_deployment_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/validation.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_job_variables_for_deployment_flow_run(session: AsyncSession, deployment: BaseDeployment, flow_run: FlowRunAction) -> None
```

Validate job variables for a flow run created for a deployment.

Flow runs are the terminal point for job variable overlays, so we validate required
job variables because all variables should now be present.

### `validate_job_variables_for_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/validation.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_job_variables_for_deployment(session: AsyncSession, work_pool: WorkPool, deployment: DeploymentAction) -> None
```

Validate job variables for deployment creation and updates.

This validation applies only to deployments that have a work pool. If the deployment
does not have a work pool, we cannot validate job variables because we don't have a
base job template to validate against, so we skip this validation.

Unlike validations for flow runs, validation here ignores required keys in the schema
because we don't know if the full set of overrides will include values for any
required fields. If the full set of job variables when a flow is running, including
the deployment's and flow run's overrides, fails to specify a value for the required
key, that's an error.

### `validate_job_variable_defaults_for_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/validation.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_job_variable_defaults_for_work_pool(session: AsyncSession, work_pool_name: str, base_job_template: Dict[str, Any]) -> None
```

Validate the default job variables for a work pool.

This validation checks that default values for job variables match the JSON schema
defined in the work pool's base job template. It also resolves references to block
documents in the default values and hydrates them to perform the validation.

Unlike validations for flow runs, validation here ignores required keys in the schema
because we're only concerned with default values. The absence of a default for a
required field is not an error, but if the full set of job variables when a flow is
running, including the deployment's and flow run's overrides, fails to specify a value
for the required key, that's an error.

NOTE: This will raise an HTTP 404 error if a referenced block document does not exist.

### `validate_job_variables_for_run_deployment_action` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/validation.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_job_variables_for_run_deployment_action(session: AsyncSession, run_action: RunDeployment) -> None
```

Validate the job variables for a RunDeployment action.

This action is equivalent to creating a flow run for a deployment, so we validate
required job variables because all variables should now be present.


# variables
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-variables



# `prefect.server.api.variables`

Routes for interacting with variable objects

## Functions

### `get_variable_or_404` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_variable_or_404(session: AsyncSession, variable_id: UUID) -> orm_models.Variable
```

Returns a variable or raises 404 HTTPException if it does not exist

### `get_variable_by_name_or_404` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_variable_by_name_or_404(session: AsyncSession, name: str) -> orm_models.Variable
```

Returns a variable or raises 404 HTTPException if it does not exist

### `create_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_variable(variable: actions.VariableCreate, db: PrefectDBInterface = Depends(provide_database_interface)) -> core.Variable
```

Create a variable.

For more information, see [https://docs.prefect.io/v3/develop/variables](https://docs.prefect.io/v3/develop/variables).

### `read_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_variable(variable_id: UUID = Path(..., alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> core.Variable
```

### `read_variable_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_variable_by_name(name: str = Path(...), db: PrefectDBInterface = Depends(provide_database_interface)) -> core.Variable
```

### `read_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_variables(limit: int = LimitBody(), offset: int = Body(0, ge=0), variables: Optional[filters.VariableFilter] = None, sort: sorting.VariableSort = Body(sorting.VariableSort.NAME_ASC), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[core.Variable]
```

### `count_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_variables(variables: Optional[filters.VariableFilter] = Body(None, embed=True), db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

### `update_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_variable(variable: actions.VariableUpdate, variable_id: UUID = Path(..., alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `update_variable_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_variable_by_name(variable: actions.VariableUpdate, name: str = Path(..., alias='name'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `delete_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_variable(variable_id: UUID = Path(..., alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `delete_variable_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/variables.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_variable_by_name(name: str = Path(...), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```


# work_queues
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-work_queues



# `prefect.server.api.work_queues`

Routes for interacting with work queue objects.

## Functions

### `create_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_work_queue(work_queue: schemas.actions.WorkQueueCreate, db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.WorkQueueResponse
```

Creates a new work queue.

If a work queue with the same name already exists, an error
will be raised.

For more information, see [https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues](https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues).

### `update_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_work_queue(work_queue: schemas.actions.WorkQueueUpdate, work_queue_id: UUID = Path(..., description='The work queue id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Updates an existing work queue.

### `read_work_queue_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_by_name(name: str = Path(..., description='The work queue name'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.WorkQueueResponse
```

Get a work queue by id.

### `read_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue(work_queue_id: UUID = Path(..., description='The work queue id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.WorkQueueResponse
```

Get a work queue by id.

### `read_work_queue_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_runs(background_tasks: BackgroundTasks, work_queue_id: UUID = Path(..., description='The work queue id', alias='id'), limit: int = dependencies.LimitBody(), scheduled_before: DateTime = Body(None, description='Only flow runs scheduled to start before this time will be returned.'), x_prefect_ui: Optional[bool] = Header(default=False, description='A header to indicate this request came from the Prefect UI.'), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.FlowRunResponse]
```

Get flow runs from the work queue.

### `read_work_queues` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queues(limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), work_queues: Optional[schemas.filters.WorkQueueFilter] = None, db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.WorkQueueResponse]
```

Query for work queues.

### `delete_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_work_queue(work_queue_id: UUID = Path(..., description='The work queue id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a work queue by id.

### `read_work_queue_status` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/work_queues.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_status(work_queue_id: UUID = Path(..., description='The work queue id', alias='id'), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.core.WorkQueueStatusDetail
```

Get the status of a work queue.


# workers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-api-workers



# `prefect.server.api.workers`

Routes for interacting with work queue objects.

## Functions

### `create_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_work_pool(work_pool: schemas.actions.WorkPoolCreate, db: PrefectDBInterface = Depends(provide_database_interface), prefect_client_version: Optional[str] = Depends(dependencies.get_prefect_client_version)) -> schemas.core.WorkPool
```

Creates a new work pool. If a work pool with the same
name already exists, an error will be raised.

For more information, see [https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools](https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools).

### `read_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_pool(work_pool_name: str = Path(..., description='The work pool name', alias='name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface), prefect_client_version: Optional[str] = Depends(dependencies.get_prefect_client_version)) -> schemas.core.WorkPool
```

Read a work pool by name

### `read_work_pools` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_pools(work_pools: Optional[schemas.filters.WorkPoolFilter] = None, limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), db: PrefectDBInterface = Depends(provide_database_interface), prefect_client_version: Optional[str] = Depends(dependencies.get_prefect_client_version)) -> List[schemas.core.WorkPool]
```

Read multiple work pools

### `count_work_pools` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L279" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_work_pools(work_pools: Optional[schemas.filters.WorkPoolFilter] = Body(None, embed=True), db: PrefectDBInterface = Depends(provide_database_interface)) -> int
```

Count work pools

### `update_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_work_pool(work_pool: schemas.actions.WorkPoolUpdate, work_pool_name: str = Path(..., description='The work pool name', alias='name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Update a work pool

### `delete_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_work_pool(work_pool_name: str = Path(..., description='The work pool name', alias='name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a work pool

### `get_scheduled_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs(background_tasks: BackgroundTasks, work_pool_name: str = Path(..., description='The work pool name', alias='name'), work_queue_names: List[str] = Body(None, description='The names of work pool queues'), scheduled_before: DateTime = Body(None, description='The maximum time to look for scheduled flow runs'), scheduled_after: DateTime = Body(None, description='The minimum time to look for scheduled flow runs'), limit: int = dependencies.LimitBody(), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.WorkerFlowRunResponse]
```

Load scheduled runs for a worker

### `create_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L442" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_work_queue(work_queue: schemas.actions.WorkQueueCreate, work_pool_name: str = Path(..., description='The work pool name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.WorkQueueResponse
```

Creates a new work pool queue. If a work pool queue with the same
name already exists, an error will be raised.

For more information, see [https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues](https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues).

### `read_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L482" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue(work_pool_name: str = Path(..., description='The work pool name'), work_queue_name: str = Path(..., description='The work pool queue name', alias='name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> schemas.responses.WorkQueueResponse
```

Read a work pool queue

### `read_work_queues` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L511" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queues(work_pool_name: str = Path(..., description='The work pool name'), work_queues: schemas.filters.WorkQueueFilter = None, limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.WorkQueueResponse]
```

Read all work pool queues

### `update_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L542" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_work_queue(work_queue: schemas.actions.WorkQueueUpdate, work_pool_name: str = Path(..., description='The work pool name'), work_queue_name: str = Path(..., description='The work pool queue name', alias='name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Update a work pool queue

### `delete_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L573" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_work_queue(work_pool_name: str = Path(..., description='The work pool name'), work_queue_name: str = Path(..., description='The work pool queue name', alias='name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a work pool queue

### `worker_heartbeat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L610" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
worker_heartbeat(work_pool_name: str = Path(..., description='The work pool name'), name: str = Body(..., description='The worker process name', embed=True), heartbeat_interval_seconds: Optional[int] = Body(None, description="The worker's heartbeat interval in seconds", embed=True), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

### `read_workers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L649" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_workers(work_pool_name: str = Path(..., description='The work pool name'), workers: Optional[schemas.filters.WorkerFilter] = None, limit: int = dependencies.LimitBody(), offset: int = Body(0, ge=0), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> List[schemas.responses.WorkerResponse]
```

Read all worker processes

### `delete_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L676" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_worker(work_pool_name: str = Path(..., description='The work pool name'), worker_name: str = Path(..., description="The work pool's worker name", alias='name'), worker_lookups: WorkerLookups = Depends(WorkerLookups), db: PrefectDBInterface = Depends(provide_database_interface)) -> None
```

Delete a work pool's worker

## Classes

### `WorkerLookups` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/api/workers.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-database-__init__



# `prefect.server.database`

*This module is empty or contains only private/internal implementations.*


# alembic_commands
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-database-alembic_commands



# `prefect.server.database.alembic_commands`

## Functions

### `with_alembic_lock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/alembic_commands.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_alembic_lock(fn: Callable[P, R]) -> Callable[P, R]
```

Decorator that prevents alembic commands from running concurrently.
This is necessary because alembic uses a global configuration object
that is not thread-safe.

This issue occurred in [https://github.com/PrefectHQ/prefect-dask/pull/50](https://github.com/PrefectHQ/prefect-dask/pull/50), where
dask threads were simultaneously performing alembic upgrades, and causing
cryptic `KeyError: 'config'` when `del globals_[attr_name]`.

### `alembic_config` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/alembic_commands.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
alembic_config() -> 'Config'
```

### `alembic_upgrade` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/alembic_commands.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
alembic_upgrade(revision: str = 'head', dry_run: bool = False) -> None
```

Run alembic upgrades on Prefect REST API database

**Args:**

* `revision`: The revision passed to `alembic downgrade`. Defaults to 'head', upgrading all revisions.
* `dry_run`: Show what migrations would be made without applying them. Will emit sql statements to stdout.

### `alembic_downgrade` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/alembic_commands.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
alembic_downgrade(revision: str = '-1', dry_run: bool = False) -> None
```

Run alembic downgrades on Prefect REST API database

**Args:**

* `revision`: The revision passed to `alembic downgrade`. Defaults to 'base', downgrading all revisions.
* `dry_run`: Show what migrations would be made without applying them. Will emit sql statements to stdout.

### `alembic_revision` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/alembic_commands.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
alembic_revision(message: Optional[str] = None, autogenerate: bool = False, **kwargs: Any) -> None
```

Create a new revision file for the database.

**Args:**

* `message`: string message to apply to the revision.
* `autogenerate`: whether or not to autogenerate the script from the database.

### `alembic_stamp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/alembic_commands.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
alembic_stamp(revision: Union[str, list[str], tuple[str, ...]]) -> None
```

Stamp the revision table with the given revision; don't run any migrations

**Args:**

* `revision`: The revision passed to `alembic stamp`.


# configurations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-database-configurations



# `prefect.server.database.configurations`

## Classes

### `ConnectionTracker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A test utility which tracks the connections given out by a connection pool, to
make it easy to see which connections are currently checked out and open.

**Methods:**

#### `clear` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear(self) -> None
```

#### `on_close` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_close(self, adapted_connection: AdaptedConnection, connection_record: ConnectionPoolEntry) -> None
```

#### `on_close_detached` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_close_detached(self, adapted_connection: AdaptedConnection) -> None
```

#### `on_connect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_connect(self, adapted_connection: AdaptedConnection, connection_record: ConnectionPoolEntry) -> None
```

#### `track_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
track_pool(self, pool: sa.pool.Pool) -> None
```

### `BaseDatabaseConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Abstract base class used to inject database connection configuration into Prefect.

This configuration is responsible for defining how Prefect REST API creates and manages
database connections and sessions.

**Methods:**

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]
```

Enter a transaction for a session

#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database

#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database

#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Returns a SqlAlchemy engine

#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory

#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

### `AsyncPostgresConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L352" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AsyncGenerator[AsyncSessionTransaction, None]
```

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]
```

Enter a transaction for a session

#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database

#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database

#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database

#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database

#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Retrieves an async SQLAlchemy engine.

**Args:**

* `connection_url`: The database connection string.
  Defaults to self.connection\_url
* `echo`: Whether to echo SQL sent
  to the database. Defaults to self.echo
* `timeout`: The database statement timeout, in seconds.
  Defaults to self.timeout

**Returns:**

* a SQLAlchemy engine

#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Returns a SqlAlchemy engine

#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory

#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory

#### `schedule_engine_disposal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schedule_engine_disposal(self, cache_key: _EngineCacheKey) -> None
```

Dispose of an engine once the event loop is closing.

See caveats at `add_event_loop_shutdown_callback`.

We attempted to lazily clean up old engines when new engines are created, but
if the loop the engine is attached to is already closed then the connections
cannot be cleaned up properly and warnings are displayed.

Engine disposal should only be important when running the application
ephemerally. Notably, this is an issue in our tests where many short-lived event
loops and engines are created which can consume all of the available database
connection slots. Users operating at a scale where connection limits are
encountered should be encouraged to use a standalone server.

#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L342" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.

**Args:**

* `engine`: a sqlalchemy engine

#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

### `AioSqliteConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `begin_sqlite_conn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L520" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_sqlite_conn(self, conn: aiosqlite.AsyncAdapt_aiosqlite_connection) -> None
```

#### `begin_sqlite_stmt` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_sqlite_stmt(self, conn: sa.Connection) -> None
```

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L542" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AsyncGenerator[AsyncSessionTransaction, None]
```

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]
```

Enter a transaction for a session

#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database

#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database

#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database

#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database

#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Retrieves an async SQLAlchemy engine.

**Args:**

* `connection_url`: The database connection string.
  Defaults to self.connection\_url
* `echo`: Whether to echo SQL sent
  to the database. Defaults to self.echo
* `timeout`: The database statement timeout, in seconds.
  Defaults to self.timeout

**Returns:**

* a SQLAlchemy engine

#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Returns a SqlAlchemy engine

#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L576" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory

#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory

#### `schedule_engine_disposal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L445" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schedule_engine_disposal(self, cache_key: _EngineCacheKey) -> None
```

Dispose of an engine once the event loop is closing.

See caveats at `add_event_loop_shutdown_callback`.

We attempted to lazily clean up old engines when new engines are created, but
if the loop the engine is attached to is already closed then the connections
cannot be cleaned up properly and warnings are displayed.

Engine disposal should only be important when running the application
ephemerally. Notably, this is an issue in our tests where many short-lived event
loops and engines are created which can consume all of the available database
connection slots. Users operating at a scale where connection limits are
encountered should be encouraged to use a standalone server.

#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L553" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.

**Args:**

* `engine`: a sqlalchemy engine

#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.

#### `setup_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_sqlite(self, conn: DBAPIConnection, record: ConnectionPoolEntry) -> None
```

Issue PRAGMA statements to SQLITE on connect. PRAGMAs only last for the
duration of the connection. See [https://www.sqlite.org/pragma.html](https://www.sqlite.org/pragma.html) for more info.

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.


# dependencies
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-database-dependencies



# `prefect.server.database.dependencies`

Injected database interface dependencies

## Functions

### `provide_database_interface` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provide_database_interface() -> 'PrefectDBInterface'
```

Get the current Prefect REST API database interface.

If components of the interface are not set, defaults will be inferred
based on the dialect of the connection URL.

### `inject_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
inject_db(fn: Callable[P, R]) -> Callable[P, R]
```

Decorator that provides a database interface to a function.

The decorated function *must* take a `db` kwarg and if a db is passed
when called it will be used instead of creating a new one.

### `db_injector` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
db_injector(func: Union[_DBMethod[T, P, R], _DBFunction[P, R]]) -> Union[_Method[T, P, R], _Function[P, R]]
```

Decorator to inject a PrefectDBInterface instance as the first positional
argument to the decorated function.

Unlike `inject_db`, which injects the database connection as a keyword
argument, `db_injector` adds it explicitly as the first positional
argument. This change enhances type hinting by making the dependency on
PrefectDBInterface explicit in the function signature.

When decorating a coroutine function, the result will continue to pass the
iscoroutinefunction() test.

**Args:**

* `func`: The function or method to decorate.

**Returns:**

* A wrapped descriptor object which injects the PrefectDBInterface instance
* as the first argument to the function or method. This handles method
* binding transparently.

### `temporary_database_config` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_database_config(tmp_database_config: Optional[BaseDatabaseConfiguration]) -> Generator[None, object, None]
```

Temporarily override the Prefect REST API database configuration.
When the context is closed, the existing database configuration will
be restored.

**Args:**

* `tmp_database_config`: Prefect REST API database configuration to inject.

### `temporary_query_components` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_query_components(tmp_queries: Optional['BaseQueryComponents']) -> Generator[None, object, None]
```

Temporarily override the Prefect REST API database query components.
When the context is closed, the existing query components will
be restored.

**Args:**

* `tmp_queries`: Prefect REST API query components to inject.

### `temporary_orm_config` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_orm_config(tmp_orm_config: Optional['BaseORMConfiguration']) -> Generator[None, object, None]
```

Temporarily override the Prefect REST API ORM configuration.
When the context is closed, the existing orm configuration will
be restored.

**Args:**

* `tmp_orm_config`: Prefect REST API ORM configuration to inject.

### `temporary_interface_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_interface_class(tmp_interface_class: Optional[type['PrefectDBInterface']]) -> Generator[None, object, None]
```

Temporarily override the Prefect REST API interface class When the context is closed,
the existing interface will be restored.

**Args:**

* `tmp_interface_class`: Prefect REST API interface class to inject.

### `temporary_database_interface` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L444" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_database_interface(tmp_database_config: Optional[BaseDatabaseConfiguration] = None, tmp_queries: Optional['BaseQueryComponents'] = None, tmp_orm_config: Optional['BaseORMConfiguration'] = None, tmp_interface_class: Optional[type['PrefectDBInterface']] = None) -> Generator[None, object, None]
```

Temporarily override the Prefect REST API database interface.

Any interface components that are not explicitly provided will be
cleared and inferred from the Prefect REST API database connection string
dialect.

When the context is closed, the existing database interface will
be restored.

**Args:**

* `tmp_database_config`: An optional Prefect REST API database configuration to inject.
* `tmp_orm_config`: An optional Prefect REST API ORM configuration to inject.
* `tmp_queries`: Optional Prefect REST API query components to inject.
* `tmp_interface_class`: Optional database interface class to inject

### `set_database_config` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L479" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_database_config(database_config: Optional[BaseDatabaseConfiguration]) -> None
```

Set Prefect REST API database configuration.

### `set_query_components` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L484" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_query_components(query_components: Optional['BaseQueryComponents']) -> None
```

Set Prefect REST API query components.

### `set_orm_config` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L489" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_orm_config(orm_config: Optional['BaseORMConfiguration']) -> None
```

Set Prefect REST API orm configuration.

### `set_interface_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L494" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_interface_class(interface_class: Optional[type['PrefectDBInterface']]) -> None
```

Set Prefect REST API interface class.

## Classes

### `DBInjector` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/dependencies.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# interface
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-database-interface



# `prefect.server.database.interface`

## Classes

### `DBSingleton` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Ensures that only one database interface is created per unique key

### `PrefectDBInterface` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An interface for backend-specific SqlAlchemy actions and ORM models.

The REST API can be configured to run against different databases in order maintain
performance at different scales. This interface integrates database- and dialect-
specific configuration into a unified interface that the orchestration engine runs
against.

**Methods:**

#### `Agent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Agent(self) -> type[orm_models.Agent]
```

An agent model

#### `Artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Artifact(self) -> type[orm_models.Artifact]
```

An artifact orm model

#### `ArtifactCollection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ArtifactCollection(self) -> type[orm_models.ArtifactCollection]
```

An artifact collection orm model

#### `Automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Automation(self) -> type[orm_models.Automation]
```

An automation model

#### `AutomationBucket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
AutomationBucket(self) -> type[orm_models.AutomationBucket]
```

An automation bucket model

#### `AutomationEventFollower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L307" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
AutomationEventFollower(self) -> type[orm_models.AutomationEventFollower]
```

A model capturing one event following another event

#### `AutomationRelatedResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L295" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
AutomationRelatedResource(self) -> type[orm_models.AutomationRelatedResource]
```

An automation related resource model

#### `Base` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Base(self) -> type[orm_models.Base]
```

Base class for orm models

#### `BlockDocument` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
BlockDocument(self) -> type[orm_models.BlockDocument]
```

A block document model

#### `BlockDocumentReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
BlockDocumentReference(self) -> type[orm_models.BlockDocumentReference]
```

A block document reference model

#### `BlockSchema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
BlockSchema(self) -> type[orm_models.BlockSchema]
```

A block schema model

#### `BlockSchemaReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L255" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
BlockSchemaReference(self) -> type[orm_models.BlockSchemaReference]
```

A block schema reference model

#### `BlockType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
BlockType(self) -> type[orm_models.BlockType]
```

A block type model

#### `CompositeTriggerChildFiring` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L300" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
CompositeTriggerChildFiring(self) -> type[orm_models.CompositeTriggerChildFiring]
```

A model capturing a composite trigger's child firing

#### `ConcurrencyLimit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L220" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ConcurrencyLimit(self) -> type[orm_models.ConcurrencyLimit]
```

A concurrency model

#### `ConcurrencyLimitV2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ConcurrencyLimitV2(self) -> type[orm_models.ConcurrencyLimitV2]
```

A v2 concurrency model

#### `Configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Configuration(self) -> type[orm_models.Configuration]
```

An configuration model

#### `CsrfToken` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
CsrfToken(self) -> type[orm_models.CsrfToken]
```

A csrf token model

#### `Deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Deployment(self) -> type[orm_models.Deployment]
```

A deployment orm model

#### `DeploymentSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
DeploymentSchedule(self) -> type[orm_models.DeploymentSchedule]
```

A deployment schedule orm model

#### `Event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Event(self) -> type[orm_models.Event]
```

An event model

#### `EventResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L317" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
EventResource(self) -> type[orm_models.EventResource]
```

An event resource model

#### `Flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Flow(self) -> type[orm_models.Flow]
```

A flow orm model

#### `FlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
FlowRun(self) -> type[orm_models.FlowRun]
```

A flow run orm model

#### `FlowRunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L280" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
FlowRunInput(self) -> type[orm_models.FlowRunInput]
```

A flow run input model

#### `FlowRunState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
FlowRunState(self) -> type[orm_models.FlowRunState]
```

A flow run state orm model

#### `Log` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Log(self) -> type[orm_models.Log]
```

A log orm model

#### `SavedSearch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
SavedSearch(self) -> type[orm_models.SavedSearch]
```

A saved search orm model

#### `TaskRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
TaskRun(self) -> type[orm_models.TaskRun]
```

A task run orm model

#### `TaskRunState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
TaskRunState(self) -> type[orm_models.TaskRunState]
```

A task run state orm model

#### `TaskRunStateCache` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L185" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
TaskRunStateCache(self) -> type[orm_models.TaskRunStateCache]
```

A task run state cache orm model

#### `Variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Variable(self) -> type[orm_models.Variable]
```

A variable model

#### `WorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
WorkPool(self) -> type[orm_models.WorkPool]
```

A work pool orm model

#### `WorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
WorkQueue(self) -> type[orm_models.WorkQueue]
```

A work queue model

#### `Worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Worker(self) -> type[orm_models.Worker]
```

A worker process orm model

#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self) -> None
```

Create the database

#### `dialect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dialect(self) -> type[sa.engine.Dialect]
```

#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self) -> None
```

Drop the database

#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Provides a SqlAlchemy engine against a specific database.

#### `is_db_connectable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_db_connectable(self) -> bool
```

Returns boolean indicating if the database is connectable.
This method is used to determine if the server is ready to accept requests.

#### `run_migrations_downgrade` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_migrations_downgrade(self, revision: str = '-1') -> None
```

Run all downgrade migrations

#### `run_migrations_upgrade` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_migrations_upgrade(self) -> None
```

Run all upgrade migrations

#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self) -> AsyncSession
```

Provides a SQLAlchemy session.

#### `session_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/interface.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session_context(self, begin_transaction: bool = False, with_for_update: bool = False)
```

Provides a SQLAlchemy session and a context manager for opening/closing
the underlying connection.

**Args:**

* `begin_transaction`: if True, the context manager will begin a SQL transaction.
  Exiting the context manager will COMMIT or ROLLBACK any changes.


# orm_models
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-database-orm_models



# `prefect.server.database.orm_models`

## Classes

### `Base` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base SQLAlchemy model that automatically infers the table name
and provides ID, created, and updated columns

### `Flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy mixin of a flow.

### `FlowRunState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy mixin of a flow run state.

**Methods:**

#### `as_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_state(self) -> schemas.states.State
```

#### `data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
data(self) -> Optional[Any]
```

### `TaskRunState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L224" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a task run state.

**Methods:**

#### `as_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_state(self) -> schemas.states.State
```

#### `data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
data(self) -> Optional[Any]
```

### `Artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of artifacts.

### `ArtifactCollection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `TaskRunStateCache` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a task run state cache.

### `Run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Common columns and logic for FlowRun and TaskRun models

**Methods:**

#### `estimated_run_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
estimated_run_time(self) -> datetime.timedelta
```

Total run time is incremented in the database whenever a RUNNING
state is exited. To give up-to-date estimates, we estimate incremental
run time for any runs currently in a RUNNING state.

#### `estimated_start_time_delta` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
estimated_start_time_delta(self) -> datetime.timedelta
```

The delta to the expected start time (or "lateness") is computed as
the difference between the actual start time and expected start time. To
give up-to-date estimates, we estimate lateness for any runs that don't
have a start time and are not in a final state and were expected to
start already.

### `FlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L475" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a flow run.

**Methods:**

#### `estimated_run_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
estimated_run_time(self) -> datetime.timedelta
```

Total run time is incremented in the database whenever a RUNNING
state is exited. To give up-to-date estimates, we estimate incremental
run time for any runs currently in a RUNNING state.

#### `estimated_start_time_delta` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
estimated_start_time_delta(self) -> datetime.timedelta
```

The delta to the expected start time (or "lateness") is computed as
the difference between the actual start time and expected start time. To
give up-to-date estimates, we estimate lateness for any runs that don't
have a start time and are not in a final state and were expected to
start already.

#### `set_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L553" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state(self, state: Optional[FlowRunState]) -> None
```

If a state is assigned to this run, populate its run id.

This would normally be handled by the back-populated SQLAlchemy
relationship, but because this is a one-to-one pointer to a
one-to-many relationship, SQLAlchemy can't figure it out.

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> Optional[FlowRunState]
```

### `TaskRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L654" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a task run.

**Methods:**

#### `estimated_run_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
estimated_run_time(self) -> datetime.timedelta
```

Total run time is incremented in the database whenever a RUNNING
state is exited. To give up-to-date estimates, we estimate incremental
run time for any runs currently in a RUNNING state.

#### `estimated_start_time_delta` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
estimated_start_time_delta(self) -> datetime.timedelta
```

The delta to the expected start time (or "lateness") is computed as
the difference between the actual start time and expected start time. To
give up-to-date estimates, we estimate lateness for any runs that don't
have a start time and are not in a final state and were expected to
start already.

#### `set_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L706" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state(self, state: Optional[TaskRunState]) -> None
```

If a state is assigned to this run, populate its run id.

This would normally be handled by the back-populated SQLAlchemy
relationship, but because this is a one-to-one pointer to a
one-to-many relationship, SQLAlchemy can't figure it out.

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L693" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> Optional[TaskRunState]
```

### `DeploymentSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L777" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L810" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a deployment.

**Methods:**

#### `job_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L831" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
job_variables(self) -> Mapped[dict[str, Any]]
```

### `Log` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L919" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a logging statement.

### `ConcurrencyLimit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L942" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `ConcurrencyLimitV2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L952" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BlockType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L965" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BlockSchema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L986" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BlockSchemaReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1018" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BlockDocument` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1030" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `decrypt_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1070" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
decrypt_data(self, session: AsyncSession) -> dict[str, Any]
```

Retrieve decrypted data from the ORM model.

Note: will only succeed if the caller has sufficient permission.

#### `encrypt_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1062" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
encrypt_data(self, session: AsyncSession, data: dict[str, Any]) -> None
```

Store encrypted data on the ORM model

Note: will only succeed if the caller has sufficient permission.

### `BlockDocumentReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1079" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1091" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `SavedSearch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1098" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a saved search.

### `WorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of a work queue

### `WorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of an worker

### `Worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of an worker

### `Agent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLAlchemy model of an agent

### `Variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `FlowRunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `CsrfToken` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `sort_expression` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
sort_expression(cls, value: AutomationSort) -> sa.ColumnExpressionArgument[Any]
```

Return an expression used to sort Automations

### `AutomationBucket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `AutomationRelatedResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `CompositeTriggerChildFiring` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1351" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `AutomationEventFollower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `EventResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1445" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BaseORMConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1508" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Abstract base class used to inject database-specific ORM configuration into Prefect.

Modifications to core Prefect REST API data structures can have unintended consequences.
Use with caution.

**Methods:**

#### `artifact_collection_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
artifact_collection_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting an ArtifactCollection

#### `block_document_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_document_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockDocument

#### `block_schema_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1554" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_schema_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockSchema

#### `block_type_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1544" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_type_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockType

#### `concurrency_limit_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1534" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
concurrency_limit_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a ConcurrencyLimit

#### `deployment_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deployment_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a Deployment

#### `flow_run_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a FlowRun

#### `flow_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1559" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a Flow

#### `saved_search_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1564" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
saved_search_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a SavedSearch

#### `task_run_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a TaskRun

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

#### `versions_dir` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
versions_dir(self) -> Path
```

Directory containing migrations

### `AsyncPostgresORMConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1583" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Postgres specific orm configuration

**Methods:**

#### `artifact_collection_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
artifact_collection_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting an ArtifactCollection

#### `block_document_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_document_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockDocument

#### `block_schema_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1554" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_schema_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockSchema

#### `block_type_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1544" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_type_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockType

#### `concurrency_limit_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1534" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
concurrency_limit_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a ConcurrencyLimit

#### `deployment_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deployment_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a Deployment

#### `flow_run_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a FlowRun

#### `flow_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1559" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a Flow

#### `saved_search_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1564" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
saved_search_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a SavedSearch

#### `task_run_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a TaskRun

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

#### `versions_dir` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1587" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
versions_dir(self) -> Path
```

Directory containing migrations

#### `versions_dir` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
versions_dir(self) -> Path
```

Directory containing migrations

### `AioSqliteORMConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1599" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

SQLite specific orm configuration

**Methods:**

#### `artifact_collection_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
artifact_collection_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting an ArtifactCollection

#### `block_document_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_document_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockDocument

#### `block_schema_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1554" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_schema_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockSchema

#### `block_type_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1544" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_type_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a BlockType

#### `concurrency_limit_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1534" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
concurrency_limit_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a ConcurrencyLimit

#### `deployment_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deployment_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a Deployment

#### `flow_run_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a FlowRun

#### `flow_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1559" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a Flow

#### `saved_search_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1564" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
saved_search_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a SavedSearch

#### `task_run_unique_upsert_columns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_unique_upsert_columns(self) -> _UpsertColumns
```

Unique columns for upserting a TaskRun

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

#### `versions_dir` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1603" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
versions_dir(self) -> Path
```

Directory containing migrations

#### `versions_dir` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/orm_models.py#L1524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
versions_dir(self) -> Path
```

Directory containing migrations


# query_components
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-database-query_components



# `prefect.server.database.query_components`

## Classes

### `FlowRunGraphV2Node` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BaseQueryComponents` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Abstract base class used to inject dialect-specific SQL operations into Prefect.

**Methods:**

#### `build_json_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_json_object(self, *args: Union[str, sa.ColumnElement[Any]]) -> sa.ColumnElement[Any]
```

builds a JSON object from sequential key-value pairs

#### `cast_to_json` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cast_to_json(self, json_obj: sa.ColumnElement[T]) -> sa.ColumnElement[T]
```

casts to JSON object if necessary

#### `clear_configuration_value_cache_for_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L377" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_configuration_value_cache_for_key(self, key: str) -> None
```

Removes a configuration key from the cache.

#### `flow_run_graph_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L405" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_graph_v2(self, db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID, since: DateTime, max_nodes: int, max_artifacts: int) -> Graph
```

Returns the query that selects all of the nodes and edges for a flow run graph (version 2).

#### `get_scheduled_flow_runs_from_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs_from_work_pool(self, db: PrefectDBInterface, session: AsyncSession, limit: Optional[int] = None, worker_limit: Optional[int] = None, queue_limit: Optional[int] = None, work_pool_ids: Optional[list[UUID]] = None, work_queue_ids: Optional[list[UUID]] = None, scheduled_before: Optional[DateTime] = None, scheduled_after: Optional[DateTime] = None, respect_queue_priorities: bool = False) -> list[schemas.responses.WorkerFlowRunResponse]
```

#### `get_scheduled_flow_runs_from_work_queues` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs_from_work_queues(self, db: PrefectDBInterface, limit_per_queue: Optional[int] = None, work_queue_ids: Optional[list[UUID]] = None, scheduled_before: Optional[DateTime] = None) -> sa.Select[tuple[orm_models.FlowRun, UUID]]
```

Returns all scheduled runs in work queues, subject to provided parameters.

This query returns a `(orm_models.FlowRun, orm_models.WorkQueue.id)` pair; calling
`result.all()` will return both; calling `result.scalars().unique().all()`
will return only the flow run because it grabs the first result.

#### `insert` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
insert(self, obj: type[orm_models.Base]) -> Union[postgresql.Insert, sqlite.Insert]
```

dialect-specific insert statement

#### `json_arr_agg` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_arr_agg(self, json_array: sa.ColumnElement[Any]) -> sa.ColumnElement[Any]
```

aggregates a JSON array

#### `make_timestamp_intervals` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
make_timestamp_intervals(self, start_time: datetime.datetime, end_time: datetime.datetime, interval: datetime.timedelta) -> sa.Select[tuple[datetime.datetime, datetime.datetime]]
```

#### `read_configuration_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_configuration_value(self, db: PrefectDBInterface, session: AsyncSession, key: str) -> Optional[dict[str, Any]]
```

Read a configuration value by key.

Configuration values should not be changed at run time, so retrieved
values are cached in memory.

The main use of configurations is encrypting blocks, this speeds up nested
block document queries.

#### `set_state_id_on_inserted_flow_runs_statement` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state_id_on_inserted_flow_runs_statement(self, inserted_flow_run_ids: Sequence[UUID], insert_flow_run_states: Iterable[dict[str, Any]]) -> sa.Update
```

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

#### `uses_json_strings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
uses_json_strings(self) -> bool
```

specifies whether the configured dialect returns JSON as strings

### `AsyncPostgresQueryComponents` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L542" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_json_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L557" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_json_object(self, *args: Union[str, sa.ColumnElement[Any]]) -> sa.ColumnElement[Any]
```

#### `build_json_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_json_object(self, *args: Union[str, sa.ColumnElement[Any]]) -> sa.ColumnElement[Any]
```

builds a JSON object from sequential key-value pairs

#### `cast_to_json` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L554" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cast_to_json(self, json_obj: sa.ColumnElement[T]) -> sa.ColumnElement[T]
```

#### `cast_to_json` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cast_to_json(self, json_obj: sa.ColumnElement[T]) -> sa.ColumnElement[T]
```

casts to JSON object if necessary

#### `clear_configuration_value_cache_for_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L377" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_configuration_value_cache_for_key(self, key: str) -> None
```

Removes a configuration key from the cache.

#### `flow_run_graph_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L405" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_graph_v2(self, db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID, since: DateTime, max_nodes: int, max_artifacts: int) -> Graph
```

Returns the query that selects all of the nodes and edges for a flow run graph (version 2).

#### `get_scheduled_flow_runs_from_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs_from_work_pool(self, db: PrefectDBInterface, session: AsyncSession, limit: Optional[int] = None, worker_limit: Optional[int] = None, queue_limit: Optional[int] = None, work_pool_ids: Optional[list[UUID]] = None, work_queue_ids: Optional[list[UUID]] = None, scheduled_before: Optional[DateTime] = None, scheduled_after: Optional[DateTime] = None, respect_queue_priorities: bool = False) -> list[schemas.responses.WorkerFlowRunResponse]
```

#### `get_scheduled_flow_runs_from_work_queues` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs_from_work_queues(self, db: PrefectDBInterface, limit_per_queue: Optional[int] = None, work_queue_ids: Optional[list[UUID]] = None, scheduled_before: Optional[DateTime] = None) -> sa.Select[tuple[orm_models.FlowRun, UUID]]
```

Returns all scheduled runs in work queues, subject to provided parameters.

This query returns a `(orm_models.FlowRun, orm_models.WorkQueue.id)` pair; calling
`result.all()` will return both; calling `result.scalars().unique().all()`
will return only the flow run because it grabs the first result.

#### `insert` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L545" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
insert(self, obj: type[orm_models.Base]) -> postgresql.Insert
```

#### `insert` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
insert(self, obj: type[orm_models.Base]) -> Union[postgresql.Insert, sqlite.Insert]
```

dialect-specific insert statement

#### `json_arr_agg` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_arr_agg(self, json_array: sa.ColumnElement[Any]) -> sa.ColumnElement[Any]
```

#### `json_arr_agg` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_arr_agg(self, json_array: sa.ColumnElement[Any]) -> sa.ColumnElement[Any]
```

aggregates a JSON array

#### `make_timestamp_intervals` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L567" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
make_timestamp_intervals(self, start_time: datetime.datetime, end_time: datetime.datetime, interval: datetime.timedelta) -> sa.Select[tuple[datetime.datetime, datetime.datetime]]
```

#### `make_timestamp_intervals` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
make_timestamp_intervals(self, start_time: datetime.datetime, end_time: datetime.datetime, interval: datetime.timedelta) -> sa.Select[tuple[datetime.datetime, datetime.datetime]]
```

#### `read_configuration_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_configuration_value(self, db: PrefectDBInterface, session: AsyncSession, key: str) -> Optional[dict[str, Any]]
```

Read a configuration value by key.

Configuration values should not be changed at run time, so retrieved
values are cached in memory.

The main use of configurations is encrypting blocks, this speeds up nested
block document queries.

#### `set_state_id_on_inserted_flow_runs_statement` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state_id_on_inserted_flow_runs_statement(self, db: PrefectDBInterface, inserted_flow_run_ids: Sequence[UUID], insert_flow_run_states: Iterable[dict[str, Any]]) -> sa.Update
```

Given a list of flow run ids and associated states, set the state\_id
to the appropriate state for all flow runs

#### `set_state_id_on_inserted_flow_runs_statement` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state_id_on_inserted_flow_runs_statement(self, inserted_flow_run_ids: Sequence[UUID], insert_flow_run_states: Iterable[dict[str, Any]]) -> sa.Update
```

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

#### `uses_json_strings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L551" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
uses_json_strings(self) -> bool
```

#### `uses_json_strings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
uses_json_strings(self) -> bool
```

specifies whether the configured dialect returns JSON as strings

### `UUIDList` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L778" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Map a JSON list of strings back to a list of UUIDs at the result loading stage

**Methods:**

#### `process_result_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L784" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_result_value(self, value: Optional[list[Union[str, UUID]]], dialect: sa.Dialect) -> Optional[list[UUID]]
```

### `AioSqliteQueryComponents` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L792" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_json_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L807" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_json_object(self, *args: Union[str, sa.ColumnElement[Any]]) -> sa.ColumnElement[Any]
```

#### `build_json_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_json_object(self, *args: Union[str, sa.ColumnElement[Any]]) -> sa.ColumnElement[Any]
```

builds a JSON object from sequential key-value pairs

#### `cast_to_json` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L804" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cast_to_json(self, json_obj: sa.ColumnElement[T]) -> sa.ColumnElement[T]
```

#### `cast_to_json` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cast_to_json(self, json_obj: sa.ColumnElement[T]) -> sa.ColumnElement[T]
```

casts to JSON object if necessary

#### `clear_configuration_value_cache_for_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L377" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_configuration_value_cache_for_key(self, key: str) -> None
```

Removes a configuration key from the cache.

#### `flow_run_graph_v2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L405" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_graph_v2(self, db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID, since: DateTime, max_nodes: int, max_artifacts: int) -> Graph
```

Returns the query that selects all of the nodes and edges for a flow run graph (version 2).

#### `get_scheduled_flow_runs_from_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs_from_work_pool(self, db: PrefectDBInterface, session: AsyncSession, limit: Optional[int] = None, worker_limit: Optional[int] = None, queue_limit: Optional[int] = None, work_pool_ids: Optional[list[UUID]] = None, work_queue_ids: Optional[list[UUID]] = None, scheduled_before: Optional[DateTime] = None, scheduled_after: Optional[DateTime] = None, respect_queue_priorities: bool = False) -> list[schemas.responses.WorkerFlowRunResponse]
```

#### `get_scheduled_flow_runs_from_work_queues` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs_from_work_queues(self, db: PrefectDBInterface, limit_per_queue: Optional[int] = None, work_queue_ids: Optional[list[UUID]] = None, scheduled_before: Optional[DateTime] = None) -> sa.Select[tuple[orm_models.FlowRun, UUID]]
```

Returns all scheduled runs in work queues, subject to provided parameters.

This query returns a `(orm_models.FlowRun, orm_models.WorkQueue.id)` pair; calling
`result.all()` will return both; calling `result.scalars().unique().all()`
will return only the flow run because it grabs the first result.

#### `insert` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L795" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
insert(self, obj: type[orm_models.Base]) -> sqlite.Insert
```

#### `insert` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
insert(self, obj: type[orm_models.Base]) -> Union[postgresql.Insert, sqlite.Insert]
```

dialect-specific insert statement

#### `json_arr_agg` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L812" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_arr_agg(self, json_array: sa.ColumnElement[Any]) -> sa.ColumnElement[Any]
```

#### `json_arr_agg` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_arr_agg(self, json_array: sa.ColumnElement[Any]) -> sa.ColumnElement[Any]
```

aggregates a JSON array

#### `make_timestamp_intervals` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L817" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
make_timestamp_intervals(self, start_time: datetime.datetime, end_time: datetime.datetime, interval: datetime.timedelta) -> sa.Select[tuple[datetime.datetime, datetime.datetime]]
```

#### `make_timestamp_intervals` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
make_timestamp_intervals(self, start_time: datetime.datetime, end_time: datetime.datetime, interval: datetime.timedelta) -> sa.Select[tuple[datetime.datetime, datetime.datetime]]
```

#### `read_configuration_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_configuration_value(self, db: PrefectDBInterface, session: AsyncSession, key: str) -> Optional[dict[str, Any]]
```

Read a configuration value by key.

Configuration values should not be changed at run time, so retrieved
values are cached in memory.

The main use of configurations is encrypting blocks, this speeds up nested
block document queries.

#### `set_state_id_on_inserted_flow_runs_statement` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L851" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state_id_on_inserted_flow_runs_statement(self, db: PrefectDBInterface, inserted_flow_run_ids: Sequence[UUID], insert_flow_run_states: Iterable[dict[str, Any]]) -> sa.Update
```

Given a list of flow run ids and associated states, set the state\_id
to the appropriate state for all flow runs

#### `set_state_id_on_inserted_flow_runs_statement` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state_id_on_inserted_flow_runs_statement(self, inserted_flow_run_ids: Sequence[UUID], insert_flow_run_states: Iterable[dict[str, Any]]) -> sa.Update
```

#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

#### `uses_json_strings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L801" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
uses_json_strings(self) -> bool
```

#### `uses_json_strings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/query_components.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
uses_json_strings(self) -> bool
```

specifies whether the configured dialect returns JSON as strings


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-__init__



# `prefect.server.events`

*This module is empty or contains only private/internal implementations.*


# actions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-actions



# `prefect.server.events.actions`

The actions consumer watches for actions that have been triggered by Automations
and carries them out.  Also includes the various concrete subtypes of Actions

## Functions

### `record_action_happening` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1713" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_action_happening(id: UUID) -> None
```

Record that an action has happened, with an expiration of an hour.

### `action_has_already_happened` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1718" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
action_has_already_happened(id: UUID) -> bool
```

Check if the action has already happened

### `consumer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1724" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
consumer() -> AsyncGenerator[MessageHandler, None]
```

## Classes

### `ActionFailed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Action` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An Action that may be performed when an Automation is triggered

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

Perform the requested Action

#### `fail` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fail(self, triggered_action: 'TriggeredAction', reason: str) -> None
```

#### `logging_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logging_context(self, triggered_action: 'TriggeredAction') -> Dict[str, Any]
```

Common logging context for all actions

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `succeed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
succeed(self, triggered_action: 'TriggeredAction') -> None
```

### `DoNothing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Do nothing when an Automation is triggered

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `EmitEventAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L279" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L280" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `create_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_event(self, triggered_action: 'TriggeredAction') -> 'Event'
```

Create an event from the TriggeredAction

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

### `ExternalDataAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that require data from an external source such as
the Orchestration API

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `events_api_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_client(self, triggered_action: 'TriggeredAction') -> PrefectServerEventsAPIClient
```

#### `orchestration_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orchestration_client(self, triggered_action: 'TriggeredAction') -> 'OrchestrationClient'
```

#### `reason_from_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reason_from_response(self, response: Response) -> str
```

### `JinjaTemplateAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L387" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that use Jinja templates supplied by the user and
are rendered with a context containing data from the triggered action,
and the orchestration API.

**Methods:**

#### `events_api_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_client(self, triggered_action: 'TriggeredAction') -> PrefectServerEventsAPIClient
```

#### `instantiate_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
instantiate_object(self, model: Type[PrefectBaseModel], data: Dict[str, Any], triggered_action: 'TriggeredAction', resource: Optional['Resource'] = None) -> PrefectBaseModel
```

#### `orchestration_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orchestration_client(self, triggered_action: 'TriggeredAction') -> 'OrchestrationClient'
```

#### `reason_from_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reason_from_response(self, response: Response) -> str
```

#### `templates_in_dictionary` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L417" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
templates_in_dictionary(cls, dict_: dict[Any, Any | dict[Any, Any]]) -> list[tuple[dict[Any, Any], dict[Any, str]]]
```

#### `validate_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_template(cls, template: str, field_name: str) -> str
```

### `DeploymentAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L632" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Deployments and need to infer them from
events

**Methods:**

#### `deployment_id_to_use` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L661" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deployment_id_to_use(self, triggered_action: 'TriggeredAction') -> UUID
```

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `selected_deployment_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L651" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_deployment_requires_id(self) -> Self
```

### `DeploymentCommandAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L677" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Executes a command against a matching deployment

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', deployment_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Execute the deployment command

#### `events_api_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_client(self, triggered_action: 'TriggeredAction') -> PrefectServerEventsAPIClient
```

#### `orchestration_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orchestration_client(self, triggered_action: 'TriggeredAction') -> 'OrchestrationClient'
```

#### `reason_from_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reason_from_response(self, response: Response) -> str
```

#### `selected_deployment_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_deployment_requires_id(self)
```

### `RunDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Runs the given deployment with the given parameters

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L750" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', deployment_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', deployment_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Execute the deployment command

#### `instantiate_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
instantiate_object(self, model: Type[PrefectBaseModel], data: Dict[str, Any], triggered_action: 'TriggeredAction', resource: Optional['Resource'] = None) -> PrefectBaseModel
```

#### `render_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L864" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
render_parameters(self, triggered_action: 'TriggeredAction') -> Dict[str, Any]
```

#### `templates_in_dictionary` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L417" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
templates_in_dictionary(cls, dict_: dict[Any, Any | dict[Any, Any]]) -> list[tuple[dict[Any, Any], dict[Any, str]]]
```

#### `validate_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L807" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_parameters(cls, value: dict[str, Any] | None) -> dict[str, Any] | None
```

#### `validate_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_template(cls, template: str, field_name: str) -> str
```

### `PauseDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L962" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses the given Deployment

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L969" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', deployment_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', deployment_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Execute the deployment command

### `ResumeDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L978" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes the given Deployment

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L682" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L985" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', deployment_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', deployment_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Execute the deployment command

### `FlowRunAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L994" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An action that operates on a flow run

**Methods:**

#### `events_api_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_client(self, triggered_action: 'TriggeredAction') -> PrefectServerEventsAPIClient
```

#### `flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L997" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run(self, triggered_action: 'TriggeredAction') -> UUID
```

#### `orchestration_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orchestration_client(self, triggered_action: 'TriggeredAction') -> 'OrchestrationClient'
```

#### `reason_from_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reason_from_response(self, response: Response) -> str
```

### `FlowRunStateChangeAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1013" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Changes the state of a flow run associated with the trigger

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1020" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L997" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run(self, triggered_action: 'TriggeredAction') -> UUID
```

#### `new_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1017" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
new_state(self, triggered_action: 'TriggeredAction') -> StateCreate
```

Return the new state for the flow run

### `ChangeFlowRunState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1054" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Changes the state of a flow run associated with the trigger

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1020" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `new_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1072" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
new_state(self, triggered_action: 'TriggeredAction') -> StateCreate
```

#### `new_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1017" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
new_state(self, triggered_action: 'TriggeredAction') -> StateCreate
```

Return the new state for the flow run

### `CancelFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1085" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Cancels a flow run associated with the trigger

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1020" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `new_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1090" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
new_state(self, triggered_action: 'TriggeredAction') -> StateCreate
```

#### `new_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1017" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
new_state(self, triggered_action: 'TriggeredAction') -> StateCreate
```

Return the new state for the flow run

### `SuspendFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1097" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Suspends a flow run associated with the trigger

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1020" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `new_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
new_state(self, triggered_action: 'TriggeredAction') -> StateCreate
```

#### `new_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1017" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
new_state(self, triggered_action: 'TriggeredAction') -> StateCreate
```

Return the new state for the flow run

### `ResumeFlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a paused or suspended flow run associated with the trigger

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L997" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run(self, triggered_action: 'TriggeredAction') -> UUID
```

### `CallWebhook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Call a webhook when an Automation is triggered.

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `ensure_payload_is_a_string` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ensure_payload_is_a_string(cls, value: Union[str, Dict[str, Any], None]) -> Optional[str]
```

Temporary measure while we migrate payloads from being a dictionary to
a string template.  This covers both reading from the database where values
may currently be a dictionary, as well as the API, where older versions of the
frontend may be sending a JSON object with the single `"message"` key.

#### `instantiate_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
instantiate_object(self, model: Type[PrefectBaseModel], data: Dict[str, Any], triggered_action: 'TriggeredAction', resource: Optional['Resource'] = None) -> PrefectBaseModel
```

#### `templates_in_dictionary` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L417" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
templates_in_dictionary(cls, dict_: dict[Any, Any | dict[Any, Any]]) -> list[tuple[dict[Any, Any], dict[Any, str]]]
```

#### `validate_payload_templates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_payload_templates(cls, value: Optional[str]) -> Optional[str]
```

Validate user-provided payload template.

#### `validate_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_template(cls, template: str, field_name: str) -> str
```

### `SendNotification` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Send a notification when an Automation is triggered

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `instantiate_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L438" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
instantiate_object(self, model: Type[PrefectBaseModel], data: Dict[str, Any], triggered_action: 'TriggeredAction', resource: Optional['Resource'] = None) -> PrefectBaseModel
```

#### `is_valid_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_valid_template(cls, value: str, info: ValidationInfo) -> str
```

#### `render` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1313" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
render(self, triggered_action: 'TriggeredAction') -> List[str]
```

#### `templates_in_dictionary` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L417" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
templates_in_dictionary(cls, dict_: dict[Any, Any | dict[Any, Any]]) -> list[tuple[dict[Any, Any], dict[Any, str]]]
```

#### `validate_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_template(cls, template: str, field_name: str) -> str
```

### `WorkPoolAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1317" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Work Pools and need to infer them from
events

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `selected_work_pool_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_work_pool_requires_id(self) -> Self
```

#### `work_pool_id_to_use` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
work_pool_id_to_use(self, triggered_action: 'TriggeredAction') -> UUID
```

### `WorkPoolCommandAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_pool: WorkPool, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Pool

#### `events_api_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_client(self, triggered_action: 'TriggeredAction') -> PrefectServerEventsAPIClient
```

#### `orchestration_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orchestration_client(self, triggered_action: 'TriggeredAction') -> 'OrchestrationClient'
```

#### `reason_from_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reason_from_response(self, response: Response) -> str
```

#### `target_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
target_work_pool(self, triggered_action: 'TriggeredAction') -> WorkPool
```

### `PauseWorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses a Work Pool

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1426" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_pool: WorkPool, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_pool: WorkPool, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Pool

#### `target_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
target_work_pool(self, triggered_action: 'TriggeredAction') -> WorkPool
```

### `ResumeWorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a Work Pool

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1442" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_pool: WorkPool, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_pool: WorkPool, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Pool

#### `target_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
target_work_pool(self, triggered_action: 'TriggeredAction') -> WorkPool
```

### `WorkQueueAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1451" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Work Queues and need to infer them from
events

**Methods:**

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `selected_work_queue_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1470" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_work_queue_requires_id(self) -> Self
```

#### `work_queue_id_to_use` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1480" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
work_queue_id_to_use(self, triggered_action: 'TriggeredAction') -> UUID
```

### `WorkQueueCommandAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1496" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_queue_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Queue

#### `events_api_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_client(self, triggered_action: 'TriggeredAction') -> PrefectServerEventsAPIClient
```

#### `orchestration_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orchestration_client(self, triggered_action: 'TriggeredAction') -> 'OrchestrationClient'
```

#### `reason_from_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reason_from_response(self, response: Response) -> str
```

#### `selected_work_queue_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_work_queue_requires_id(self) -> Self
```

### `PauseWorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1538" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses a Work Queue

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1545" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_queue_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_queue_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Queue

### `ResumeWorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1554" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a Work Queue

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1561" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_queue_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, orchestration: 'OrchestrationClient', work_queue_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Queue

### `AutomationAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1570" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Actions that operate on Automations and need to infer them from
events

**Methods:**

#### `automation_id_to_use` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1599" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
automation_id_to_use(self, triggered_action: 'TriggeredAction') -> UUID
```

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self) -> str
```

A human-readable description of the action

#### `selected_automation_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_automation_requires_id(self) -> Self
```

### `AutomationCommandAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1615" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1618" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1646" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, events: PrefectServerEventsAPIClient, automation_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Queue

#### `events_api_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_client(self, triggered_action: 'TriggeredAction') -> PrefectServerEventsAPIClient
```

#### `orchestration_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orchestration_client(self, triggered_action: 'TriggeredAction') -> 'OrchestrationClient'
```

#### `reason_from_response` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reason_from_response(self, response: Response) -> str
```

#### `selected_automation_requires_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/actions.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
selected_automation_requires_id(self) -> Self
```

### `PauseAutomation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1655" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Pauses a Work Queue

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1618" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1662" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, events: PrefectServerEventsAPIClient, automation_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1646" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, events: PrefectServerEventsAPIClient, automation_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Queue

### `ResumeAutomation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1671" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Resumes a Work Queue

**Methods:**

#### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1618" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(self, triggered_action: 'TriggeredAction') -> None
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1678" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, events: PrefectServerEventsAPIClient, automation_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

#### `command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/actions.py#L1646" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
command(self, events: PrefectServerEventsAPIClient, automation_id: UUID, triggered_action: 'TriggeredAction') -> Response
```

Issue the command to the Work Queue


# clients
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-clients



# `prefect.server.events.clients`

## Classes

### `EventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The abstract interface for a Prefect Events client

**Methods:**

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> Optional[Event]
```

### `NullEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A no-op implementation of the Prefect Events client for testing

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

Emit a single event

### `AssertingEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An implementation of the Prefect Events client that records all events sent
to it for inspection during tests.

**Methods:**

#### `assert_emitted_event_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_emitted_event_count(cls, count: int) -> None
```

Assert that the given number of events were emitted.

#### `assert_emitted_event_with` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_emitted_event_with(cls, event: Optional[str] = None, resource: Optional[Dict[str, LabelValue]] = None, related: Optional[List[Dict[str, LabelValue]]] = None, payload: Optional[Dict[str, Any]] = None) -> None
```

Assert that an event was emitted containing the given properties.

#### `assert_no_emitted_event_with` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_no_emitted_event_with(cls, event: Optional[str] = None, resource: Optional[Dict[str, LabelValue]] = None, related: Optional[List[Dict[str, LabelValue]]] = None, payload: Optional[Dict[str, Any]] = None) -> None
```

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> Event
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

Emit a single event

#### `emitted_events_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emitted_events_count(cls) -> int
```

#### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(cls) -> None
```

Reset all captured instances and their events.  For use this between tests

### `PrefectServerEventsClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L214" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `client_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_name(self) -> str
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> ReceivedEvent
```

#### `emit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/clients.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit(self, event: Event) -> None
```

Emit a single event

### `PrefectServerEventsAPIClient` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `pause_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L269" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pause_automation(self, automation_id: UUID) -> httpx.Response
```

#### `resume_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/clients.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resume_automation(self, automation_id: UUID) -> httpx.Response
```


# counting
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-counting



# `prefect.server.events.counting`

## Classes

### `InvalidEventCountParameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the given parameters are invalid for counting events.

### `TimeUnit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `as_timedelta` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_timedelta(self, interval: float) -> Duration
```

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

#### `database_label_expression` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
database_label_expression(self, db: PrefectDBInterface, time_interval: float) -> sa.Function[str]
```

Returns the SQL expression to label a time bucket

#### `database_value_expression` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
database_value_expression(self, time_interval: float) -> sa.Cast[str]
```

Returns the SQL expression to place an event in a time bucket

#### `get_interval_spans` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_interval_spans(self, start_datetime: datetime.datetime, end_datetime: datetime.datetime, interval: float) -> Generator[int | tuple[datetime.datetime, datetime.datetime], None, None]
```

Divide the given range of dates into evenly-sized spans of interval units

#### `validate_buckets` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_buckets(self, start_datetime: datetime.datetime, end_datetime: datetime.datetime, interval: float) -> None
```

### `Countable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

#### `get_database_query` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/counting.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_database_query(self, filter: 'EventFilter', time_unit: TimeUnit, time_interval: float) -> Select[tuple[str, str, DateTime, DateTime, int]]
```


# filters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-filters



# `prefect.server.events.filters`

## Classes

### `AutomationFilterCreated` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Automation.created`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `AutomationFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Automation.created`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `AutomationFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Automation.tags`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `AutomationFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `EventDataFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base class for filtering event data.

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self) -> Sequence['ColumnExpressionArgument[bool]']
```

Convert the criteria to a WHERE clause.

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `EventOccurredFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

#### `clamp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clamp(self, max_duration: timedelta) -> None
```

Limit how far the query can look back based on the given duration

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventNameFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `LabelSet` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `LabelOperations` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `EventResourceFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L319" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L301" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventRelatedFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L413" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventAnyResourceFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L536" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L514" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventIDFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L609" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L622" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L614" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventTextFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L633" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by text search across event content.

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L700" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

Build SQLAlchemy WHERE clauses for text search

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L647" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Check if this text filter includes the given event.

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

### `EventOrder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L763" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `EventFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L768" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build_where_clauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L805" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_where_clauses(self, db: PrefectDBInterface) -> Sequence['ColumnExpressionArgument[bool]']
```

#### `excludes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
excludes(self, event: Event) -> bool
```

Would the given filter exclude this event?

#### `get_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_filters(self) -> list['EventDataFilter']
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/filters.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, event: Event) -> bool
```

Does the given event match the criteria of this filter?

#### `logical_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/filters.py#L822" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logical_limit(self) -> int
```

The logical limit for this query, which is a maximum number of rows that it
*could* return (regardless of what the caller has requested).  May be used as
an optimization for DB queries


# jinja_filters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-jinja_filters



# `prefect.server.events.jinja_filters`

## Functions

### `ui_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/jinja_filters.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ui_url(ctx: Mapping[str, Any], obj: Any) -> Optional[str]
```

Return the UI URL for the given object.

### `ui_resource_events_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/jinja_filters.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ui_resource_events_url(ctx: Mapping[str, Any], obj: Any) -> Optional[str]
```

Given a Resource or Model, return a UI link to the events page
filtered for that resource. If an unsupported object is provided,
return `None`.

Currently supports Automation, Resource, Deployment, Flow, FlowRun, TaskRun, and
WorkQueue objects. Within a Resource, deployment, flow, flow-run, task-run,
and work-queue are supported.


# messaging
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-messaging



# `prefect.server.events.messaging`

## Functions

### `publish` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/messaging.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish(events: Iterable[ReceivedEvent]) -> None
```

Send the given events as a batch via the default publisher

### `create_event_publisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/messaging.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_event_publisher() -> EventPublisher
```

### `create_actions_publisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/messaging.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_actions_publisher() -> Publisher
```

## Classes

### `EventPublisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/messaging.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `publish_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/messaging.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_data(self, data: bytes, attributes: Mapping[str, str]) -> None
```

#### `publish_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_data(self, data: bytes, attributes: Mapping[str, str]) -> None
```

#### `publish_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/messaging.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_event(self, event: ReceivedEvent) -> None
```

Publishes the given events

**Args:**

* `event`: the event to publish


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-models-__init__



# `prefect.server.events.models`

*This module is empty or contains only private/internal implementations.*


# automations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-models-automations



# `prefect.server.events.models.automations`

## Functions

### `automations_session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
automations_session(db: PrefectDBInterface, begin_transaction: bool = False) -> AsyncGenerator[AsyncSession, None]
```

### `read_automations_for_workspace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_automations_for_workspace(db: PrefectDBInterface, session: AsyncSession, sort: AutomationSort = AutomationSort.NAME_ASC, limit: Optional[int] = None, offset: Optional[int] = None, automation_filter: Optional[filters.AutomationFilter] = None) -> Sequence[Automation]
```

### `count_automations_for_workspace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_automations_for_workspace(db: PrefectDBInterface, session: AsyncSession) -> int
```

### `read_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_automation(db: PrefectDBInterface, session: AsyncSession, automation_id: UUID) -> Optional[Automation]
```

### `read_automation_by_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_automation_by_id(db: PrefectDBInterface, session: AsyncSession, automation_id: UUID) -> Optional[Automation]
```

### `create_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_automation(db: PrefectDBInterface, session: AsyncSession, automation: Automation) -> Automation
```

### `update_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_automation(db: PrefectDBInterface, session: AsyncSession, automation_update: Union[AutomationUpdate, AutomationPartialUpdate], automation_id: UUID) -> bool
```

### `delete_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_automation(db: PrefectDBInterface, session: AsyncSession, automation_id: UUID) -> bool
```

### `delete_automations_for_workspace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_automations_for_workspace(db: PrefectDBInterface, session: AsyncSession) -> bool
```

### `disable_automations_for_workspace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable_automations_for_workspace(db: PrefectDBInterface, session: AsyncSession) -> bool
```

### `disable_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable_automation(db: PrefectDBInterface, session: AsyncSession, automation_id: UUID) -> bool
```

### `relate_automation_to_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
relate_automation_to_resource(db: PrefectDBInterface, session: AsyncSession, automation_id: UUID, resource_id: str, owned_by_resource: bool) -> None
```

### `read_automations_related_to_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_automations_related_to_resource(db: PrefectDBInterface, session: AsyncSession, resource_id: str, owned_by_resource: Optional[bool] = None, automation_filter: Optional[filters.AutomationFilter] = None) -> Sequence[Automation]
```

### `delete_automations_owned_by_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/automations.py#L389" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_automations_owned_by_resource(db: PrefectDBInterface, session: AsyncSession, resource_id: str, automation_filter: Optional[filters.AutomationFilter] = None) -> Sequence[UUID]
```


# composite_trigger_child_firing
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-models-composite_trigger_child_firing



# `prefect.server.events.models.composite_trigger_child_firing`

## Functions

### `upsert_child_firing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/composite_trigger_child_firing.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
upsert_child_firing(db: PrefectDBInterface, session: AsyncSession, firing: Firing)
```

### `get_child_firings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/composite_trigger_child_firing.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_child_firings(db: PrefectDBInterface, session: AsyncSession, trigger: CompositeTrigger) -> Sequence['ORMCompositeTriggerChildFiring']
```

### `clear_old_child_firings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/composite_trigger_child_firing.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_old_child_firings(db: PrefectDBInterface, session: AsyncSession, trigger: CompositeTrigger, fired_before: DateTime) -> None
```

### `clear_child_firings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/models/composite_trigger_child_firing.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_child_firings(db: PrefectDBInterface, session: AsyncSession, trigger: CompositeTrigger, firing_ids: Sequence[UUID]) -> None
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-ordering-__init__



# `prefect.server.events.ordering`

Manages the partial causal ordering of events for a particular consumer.  This module
maintains a buffer of events to be processed, aiming to process them in the order they
occurred causally.

## Functions

### `get_triggers_causal_ordering` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_triggers_causal_ordering() -> CausalOrdering
```

### `get_task_run_recorder_causal_ordering` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_run_recorder_causal_ordering() -> CausalOrdering
```

## Classes

### `CausalOrderingModule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `EventArrivedEarly` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `MaxDepthExceeded` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `event_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `CausalOrdering` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `event_has_been_seen` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
event_has_been_seen(self, event: Union[UUID, Event]) -> bool
```

#### `forget_follower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_follower(self, follower: ReceivedEvent) -> None
```

#### `get_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_followers(self, leader: ReceivedEvent) -> List[ReceivedEvent]
```

#### `get_lost_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_lost_followers(self) -> List[ReceivedEvent]
```

#### `preceding_event_confirmed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
preceding_event_confirmed(self, handler: event_handler, event: ReceivedEvent, depth: int = 0) -> AsyncContextManager[None]
```

#### `record_event_as_seen` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_event_as_seen(self, event: ReceivedEvent) -> None
```

#### `record_follower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/__init__.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_follower(self, event: ReceivedEvent) -> None
```


# db
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-ordering-db



# `prefect.server.events.ordering.db`

## Classes

### `CausalOrdering` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `event_has_been_seen` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
event_has_been_seen(self, event: Union[UUID, Event]) -> bool
```

#### `forget_follower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_follower(self, db: PrefectDBInterface, follower: ReceivedEvent) -> None
```

Forget that this event is waiting on another event to arrive

#### `get_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_followers(self, db: PrefectDBInterface, leader: ReceivedEvent) -> List[ReceivedEvent]
```

Returns events that were waiting on this leader event to arrive

#### `get_lost_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_lost_followers(self, db: PrefectDBInterface) -> List[ReceivedEvent]
```

Returns events that were waiting on a leader event that never arrived

#### `preceding_event_confirmed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
preceding_event_confirmed(self, handler: event_handler, event: ReceivedEvent, depth: int = 0)
```

Events may optionally declare that they logically follow another event, so that
we can preserve important event orderings in the face of unreliable delivery and
ordering of messages from the queues.

This function keeps track of the ID of each event that this shard has successfully
processed going back to the PRECEDING\_EVENT\_LOOKBACK period.  If an event arrives
that must follow another one, confirm that we have recently seen and processed that
event before proceeding.

event (ReceivedEvent): The event to be processed. This object should include metadata indicating
if and what event it follows.
depth (int, optional): The current recursion depth, used to prevent infinite recursion due to
cyclic dependencies between events. Defaults to 0.

Raises EventArrivedEarly if the current event shouldn't be processed yet.

#### `record_event_as_seen` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_event_as_seen(self, event: ReceivedEvent) -> None
```

#### `record_follower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/db.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_follower(self, db: PrefectDBInterface, event: ReceivedEvent) -> None
```

Remember that this event is waiting on another event to arrive


# memory
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-ordering-memory



# `prefect.server.events.ordering.memory`

## Classes

### `EventBeingProcessed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Indicates that an event is currently being processed and should not be processed
until it is finished. This may happen due to concurrent processing.

### `CausalOrdering` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `clear` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear(self) -> None
```

Clear all data for this scope.

#### `clear_all_scopes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_all_scopes(cls) -> None
```

Clear all data for all scopes - useful for testing.

#### `event_has_been_seen` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
event_has_been_seen(self, event: UUID | Event) -> bool
```

#### `event_has_started_processing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
event_has_started_processing(self, event: UUID | Event) -> bool
```

#### `event_is_processing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
event_is_processing(self, event: ReceivedEvent) -> AsyncGenerator[None, None]
```

Mark an event as being processed for the duration of its lifespan through
the ordering system.

#### `followers_by_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
followers_by_id(self, follower_ids: list[UUID]) -> list[ReceivedEvent]
```

Returns the events with the given IDs, in the order they occurred.

#### `forget_event_is_processing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_event_is_processing(self, event: ReceivedEvent) -> None
```

#### `forget_follower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_follower(self, follower: ReceivedEvent) -> None
```

Forget that this event is waiting on another event to arrive.

#### `get_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_followers(self, leader: ReceivedEvent) -> list[ReceivedEvent]
```

Returns events that were waiting on this leader event to arrive.

#### `get_lost_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_lost_followers(self) -> list[ReceivedEvent]
```

Returns events that were waiting on a leader event that never arrived.

#### `preceding_event_confirmed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
preceding_event_confirmed(self, handler: event_handler, event: ReceivedEvent, depth: int = 0) -> AsyncGenerator[None, None]
```

Events may optionally declare that they logically follow another event, so that
we can preserve important event orderings in the face of unreliable delivery and
ordering of messages from the queues.

This function keeps track of the ID of each event that this shard has
successfully processed going back to the PRECEDING\_EVENT\_LOOKBACK period. If an
event arrives that must follow another one, confirm that we have recently seen
and processed that event before proceeding.

**Args:**

* `handler`: The function to call when an out-of-order event is
  ready to be processed
* `event`: The event to be processed. This object should include
  metadata indicating if and what event it follows.
* `depth`: The current recursion depth, used to prevent infinite
  recursion due to cyclic dependencies between events. Defaults to 0.

Raises EventArrivedEarly if the current event shouldn't be processed yet.

#### `record_event_as_processing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_event_as_processing(self, event: ReceivedEvent) -> bool
```

Record that an event is being processed, returning False if already processing.

#### `record_event_as_seen` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_event_as_seen(self, event: ReceivedEvent) -> None
```

#### `record_follower` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_follower(self, event: ReceivedEvent) -> None
```

Remember that this event is waiting on another event to arrive.

#### `wait_for_leader` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/ordering/memory.py#L217" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_leader(self, event: ReceivedEvent) -> None
```

Given an event, wait for its leader to be processed before proceeding, or
raise EventArrivedEarly if we would wait too long in this attempt.


# pipeline
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-pipeline



# `prefect.server.events.pipeline`

## Classes

### `EventsPipeline` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/pipeline.py#L7" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `events_to_messages` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/pipeline.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_to_messages(events: list[Event]) -> list[MemoryMessage]
```

#### `process_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/pipeline.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_events(self, events: list[Event]) -> None
```

#### `process_message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/pipeline.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_message(self, message: MemoryMessage) -> None
```

Process a single event message

#### `process_messages` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/pipeline.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_messages(self, messages: list[MemoryMessage]) -> None
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-schemas-__init__



# `prefect.server.events.schemas`

*This module is empty or contains only private/internal implementations.*


# automations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-schemas-automations



# `prefect.server.events.schemas.automations`

## Classes

### `Posture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `TriggerState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `Trigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class describing a set of criteria that must be satisfied in order to trigger
an automation.

**Methods:**

#### `all_triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_triggers(self) -> Sequence[Trigger]
```

Returns all triggers within this trigger

#### `automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
automation(self) -> 'Automation'
```

#### `create_automation_state_change_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_automation_state_change_event(self, firing: 'Firing', trigger_state: TriggerState) -> ReceivedEvent
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `parent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parent(self) -> 'Union[Trigger, Automation]'
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `reset_ids` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_ids(self) -> None
```

Resets the ID of this trigger and all of its children

### `CompositeTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Requires some number of triggers to have fired within the given time period.

**Methods:**

#### `actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
actions(self) -> List[ActionTypes]
```

#### `all_triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_triggers(self) -> Sequence[Trigger]
```

#### `as_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_automation(self) -> 'AutomationCore'
```

#### `child_trigger_ids` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
child_trigger_ids(self) -> List[UUID]
```

#### `create_automation_state_change_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_automation_state_change_event(self, firing: Firing, trigger_state: TriggerState) -> ReceivedEvent
```

Returns a ReceivedEvent for an automation state change
into a triggered or resolved state.

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `num_expected_firings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
num_expected_firings(self) -> int
```

#### `owner_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
owner_resource(self) -> Optional[str]
```

#### `ready_to_fire` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ready_to_fire(self, firings: Sequence['Firing']) -> bool
```

#### `set_deployment_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_deployment_id(self, deployment_id: UUID) -> None
```

### `CompoundTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A composite trigger that requires some number of triggers to have
fired within the given time period

**Methods:**

#### `num_expected_firings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
num_expected_firings(self) -> int
```

#### `ready_to_fire` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ready_to_fire(self, firings: Sequence['Firing']) -> bool
```

#### `validate_require` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_require(self) -> Self
```

### `SequenceTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A composite trigger that requires some number of triggers to have fired
within the given time period in a specific order

**Methods:**

#### `expected_firing_order` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L219" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
expected_firing_order(self) -> List[UUID]
```

#### `ready_to_fire` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ready_to_fire(self, firings: Sequence['Firing']) -> bool
```

### `ResourceTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for triggers that may filter by the labels of resources.

**Methods:**

#### `actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
actions(self) -> List[ActionTypes]
```

#### `as_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_automation(self) -> 'AutomationCore'
```

#### `covers_resources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
covers_resources(self, resource: Resource, related: Sequence[RelatedResource]) -> bool
```

#### `describe_for_cli` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
describe_for_cli(self, indent: int = 0) -> str
```

Return a human-readable description of this trigger for the CLI

#### `owner_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
owner_resource(self) -> Optional[str]
```

#### `set_deployment_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/automations.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_deployment_id(self, deployment_id: UUID) -> None
```

### `EventTrigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A trigger that fires based on the presence or absence of events within a given
period of time.

**Methods:**

#### `bucketing_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bucketing_key(self, event: ReceivedEvent) -> Tuple[str, ...]
```

#### `covers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L352" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
covers(self, event: ReceivedEvent) -> bool
```

#### `create_automation_state_change_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_automation_state_change_event(self, firing: Firing, trigger_state: TriggerState) -> ReceivedEvent
```

Returns a ReceivedEvent for an automation state change
into a triggered or resolved state.

#### `enforce_minimum_within_for_proactive_triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L326" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_minimum_within_for_proactive_triggers(cls, data: Dict[str, Any] | Any) -> Dict[str, Any]
```

#### `event_pattern` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
event_pattern(self) -> re.Pattern[str]
```

A regular expression which may be evaluated against any event string to
determine if this trigger would be interested in the event

#### `expects` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L401" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
expects(self, event: str) -> bool
```

#### `immediate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
immediate(self) -> bool
```

Does this reactive trigger fire immediately for all events?

#### `meets_threshold` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L415" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
meets_threshold(self, event_count: int) -> bool
```

#### `starts_after` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L389" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
starts_after(self, event: str) -> bool
```

### `AutomationCore` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L476" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines an action a user wants to take when a certain number of events
do or don't happen to the matching resources

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `prevent_run_deployment_loops` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L532" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prevent_run_deployment_loops(self) -> Self
```

Detects potential infinite loops in automations with RunDeployment actions

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `trigger_by_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L524" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
trigger_by_id(self, trigger_id: UUID) -> Optional[Trigger]
```

Returns the trigger with the given ID, or None if no such trigger exists

#### `triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
triggers(self) -> Sequence[Trigger]
```

Returns all triggers within this automation

#### `triggers_of_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L520" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
triggers_of_type(self, trigger_type: Type[T]) -> Sequence[T]
```

Returns all triggers of the specified type within this automation

### `Automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L611" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: Any) -> Self
```

### `AutomationCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L626" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `AutomationUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L632" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `AutomationPartialUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L636" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `AutomationSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L640" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines automations sorting options.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `Firing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L649" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents one instance of a trigger firing

**Methods:**

#### `all_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L714" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_events(self) -> Sequence[ReceivedEvent]
```

#### `all_firings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L709" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_firings(self) -> Sequence[Firing]
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `validate_trigger_states` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L704" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_trigger_states(cls, value: set[TriggerState]) -> set[TriggerState]
```

### `TriggeredAction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An action caused as the result of an automation

**Methods:**

#### `all_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L777" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_events(self) -> Sequence[ReceivedEvent]
```

#### `all_firings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L774" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_firings(self) -> Sequence[Firing]
```

#### `idempotency_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/automations.py#L764" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
idempotency_key(self) -> str
```

Produce a human-friendly idempotency key for this action

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# events
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-schemas-events



# `prefect.server.events.schemas.events`

## Functions

### `matches` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L239" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches(expected: str, value: Optional[str]) -> bool
```

Returns true if the given value matches the expected string, which may
include a a negation prefix ("!this-value") or a wildcard suffix
("any-value-starting-with\*")

## Classes

### `Resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An observable business object of interest to the user

**Methods:**

#### `as_label_value_array` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_label_value_array(self) -> List[Dict[str, str]]
```

#### `enforce_maximum_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_maximum_labels(self) -> Self
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, label: str, default: Optional[str] = None) -> Optional[str]
```

#### `has_all_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
has_all_labels(self, labels: Dict[str, str]) -> bool
```

#### `id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
id(self) -> str
```

#### `items` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
items(self) -> Iterable[Tuple[str, str]]
```

#### `keys` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keys(self) -> Iterable[str]
```

#### `labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/labelling.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
labels(self) -> LabelDiver
```

#### `name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
name(self) -> Optional[str]
```

#### `prefect_object_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_object_id(self, kind: str) -> UUID
```

Extracts the UUID from an event's resource ID if it's the expected kind
of prefect resource

#### `requires_resource_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_resource_id(self) -> Self
```

### `RelatedResource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Resource with a specific role in an Event

**Methods:**

#### `enforce_maximum_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_maximum_labels(self) -> Self
```

#### `id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
id(self) -> str
```

#### `name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
name(self) -> Optional[str]
```

#### `prefect_object_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_object_id(self, kind: str) -> UUID
```

Extracts the UUID from an event's resource ID if it's the expected kind
of prefect resource

#### `requires_resource_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/events/schemas/events.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_resource_id(self) -> Self
```

#### `requires_resource_role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
requires_resource_role(self) -> Self
```

#### `role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
role(self) -> str
```

### `Event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The client-side view of an event that has happened to a Resource

**Methods:**

#### `enforce_maximum_related_resources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enforce_maximum_related_resources(cls, value: List[RelatedResource]) -> List[RelatedResource]
```

#### `find_resource_label` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L185" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
find_resource_label(self, label: str) -> Optional[str]
```

Finds the value of the given label in this event's resource or one of its
related resources.  If the label starts with `related:<role>:`, search for the
first matching label in a related resource with that role.

#### `involved_resources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
involved_resources(self) -> Sequence[Resource]
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `receive` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
receive(self, received: Optional[prefect.types._datetime.DateTime] = None) -> 'ReceivedEvent'
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `resource_in_role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resource_in_role(self) -> Mapping[str, RelatedResource]
```

Returns a mapping of roles to the first related resource in that role

#### `resources_in_role` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resources_in_role(self) -> Mapping[str, Sequence[RelatedResource]]
```

Returns a mapping of roles to related resources in that role

### `ReceivedEvent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The server-side view of an event that has happened to a Resource after it has
been received by the server

**Methods:**

#### `as_database_resource_rows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_database_resource_rows(self) -> List[Dict[str, Any]]
```

#### `as_database_row` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_database_row(self) -> dict[str, Any]
```

#### `is_set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/concurrency/primitives.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_set(self)
```

#### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/concurrency/primitives.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self) -> None
```

Set the flag, notifying all waiters.

Unlike `asyncio.Event`, waiters may not be notified immediately when this is
called; instead, notification will be placed on the owning loop of each waiter
for thread safety.

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/concurrency/primitives.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self) -> Literal[True]
```

Block until the internal flag is true.

If the internal flag is true on entry, return True immediately.
Otherwise, block until another `set()` is called, then return True.

### `ResourceSpecification` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `deepcopy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deepcopy(self) -> 'ResourceSpecification'
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, key: str, default: Optional[Union[str, List[str]]] = None) -> Optional[List[str]]
```

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, candidates: Iterable[Resource]) -> bool
```

#### `items` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
items(self) -> Iterable[Tuple[str, List[str]]]
```

#### `matches` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches(self, resource: Resource) -> bool
```

#### `matches_every_resource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches_every_resource(self) -> bool
```

#### `matches_every_resource_of_kind` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matches_every_resource_of_kind(self, prefix: str) -> bool
```

#### `pop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pop(self, key: str, default: Optional[Union[str, List[str]]] = None) -> Optional[List[str]]
```

### `EventPage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A single page of events returned from the API, with an optional link to the
next page of results

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `EventCount` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/events.py#L345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The count of events with the given filter value

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# labelling
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-schemas-labelling



# `prefect.server.events.schemas.labelling`

## Classes

### `LabelDiver` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L6" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

The LabelDiver supports templating use cases for any Labelled object, by
presenting the labels as a graph of objects that may be accessed by attribute.  For
example:

```python
diver = LabelDiver({
    'hello.world': 'foo',
    'hello.world.again': 'bar'
})

assert str(diver.hello.world) == 'foo'
assert str(diver.hello.world.again) == 'bar'
```

### `Labelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `as_label_value_array` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_label_value_array(self) -> List[Dict[str, str]]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, label: str, default: Optional[str] = None) -> Optional[str]
```

#### `has_all_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
has_all_labels(self, labels: Dict[str, str]) -> bool
```

#### `items` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
items(self) -> Iterable[Tuple[str, str]]
```

#### `keys` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
keys(self) -> Iterable[str]
```

#### `labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/schemas/labelling.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
labels(self) -> LabelDiver
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-services-__init__



# `prefect.server.events.services`

*This module is empty or contains only private/internal implementations.*


# actions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-services-actions



# `prefect.server.events.services.actions`

## Classes

### `Actions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/actions.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Runs the actions triggered by automations

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/actions.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/actions.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/actions.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service


# event_logger
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-services-event_logger



# `prefect.server.events.services.event_logger`

## Classes

### `EventLogger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_logger.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A debugging service that logs events to the console as they arrive.

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_logger.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_logger.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_logger.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service


# event_persister
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-services-event_persister



# `prefect.server.events.services.event_persister`

The event persister moves event messages from the event bus to storage
storage as fast as it can.  Never gets tired.

## Functions

### `batch_delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
batch_delete(session: AsyncSession, model: type[T], condition: Any, batch_size: int = 10000) -> int
```

Perform a batch deletion of database records using a subquery with LIMIT. Works with both PostgreSQL and
SQLite. Compared to a basic delete(...).where(...), a batch deletion is more robust against timeouts
when handling large tables, which is especially the case if we first delete old entries from long
existing tables.

**Returns:**

* Total number of deleted records

### `create_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_handler(batch_size: int = 20, flush_every: timedelta = timedelta(seconds=5), trim_every: timedelta = timedelta(minutes=15)) -> AsyncGenerator[MessageHandler, None]
```

Set up a message handler that will accumulate and send events to
the database every `batch_size` messages, or every `flush_every` interval to flush
any remaining messages

## Classes

### `EventPersister` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A service that persists events to the database as they arrive.

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `started_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
started_event(self) -> asyncio.Event
```

#### `started_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
started_event(self, value: asyncio.Event) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/event_persister.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service


# triggers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-services-triggers



# `prefect.server.events.services.triggers`

## Classes

### `ReactiveTriggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/triggers.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Evaluates reactive automation triggers

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/triggers.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/triggers.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/triggers.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service

### `ProactiveTriggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/triggers.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Evaluates proactive automation triggers

**Methods:**

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/triggers.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/services/triggers.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-storage-__init__



# `prefect.server.events.storage`

## Functions

### `to_page_token` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/__init__.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_page_token(filter: 'EventFilter', count: int, page_size: int, current_offset: int) -> Optional[str]
```

### `from_page_token` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/__init__.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_page_token(page_token: str) -> Tuple['EventFilter', int, int, int]
```

### `process_time_based_counts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/__init__.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_time_based_counts(filter: 'EventFilter', time_unit: TimeUnit, time_interval: float, counts: List[EventCount]) -> List[EventCount]
```

Common logic for processing time-based counts across different event backends.

When doing time-based counting we want to do two things:

1. Backfill any missing intervals with 0 counts.
2. Update the start/end times that are emitted to match the beginning and
   end of the intervals rather than having them reflect the true max/min
   occurred time of the events themselves.

## Classes

### `InvalidTokenError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/__init__.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `QueryRangeTooLarge` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/__init__.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# database
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-storage-database



# `prefect.server.events.storage.database`

## Functions

### `build_distinct_queries` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_distinct_queries(db: PrefectDBInterface, events_filter: EventFilter) -> list[sa.Column['ORMEvent']]
```

### `query_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
query_events(session: AsyncSession, filter: EventFilter, page_size: int = INTERACTIVE_PAGE_SIZE) -> tuple[list[ReceivedEvent], int, Optional[str]]
```

### `query_next_page` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
query_next_page(session: AsyncSession, page_token: str) -> tuple[list[ReceivedEvent], int, Optional[str]]
```

### `count_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_events(session: AsyncSession, filter: EventFilter, countable: Countable, time_unit: TimeUnit, time_interval: float) -> list[EventCount]
```

### `raw_count_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raw_count_events(db: PrefectDBInterface, session: AsyncSession, events_filter: EventFilter) -> int
```

Count events from the database with the given filter.

Only returns the count and does not return any addition metadata. For additional
metadata, use `count_events`.

**Args:**

* `session`: a database session
* `events_filter`: filter criteria for events

**Returns:**

* The count of events in the database that match the filter criteria.

### `read_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_events(db: PrefectDBInterface, session: AsyncSession, events_filter: EventFilter, limit: Optional[int] = None, offset: Optional[int] = None) -> Sequence['ORMEvent']
```

Read events from the Postgres database.

**Args:**

* `session`: a Postgres events session.
* `filter`: filter criteria for events.
* `limit`: limit for the query.
* `offset`: offset for the query.

**Returns:**

* A list of events ORM objects.

### `write_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_events(session: AsyncSession, events: list[ReceivedEvent]) -> None
```

Write events to the database.

**Args:**

* `session`: a database session
* `events`: the events to insert

### `get_max_query_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_max_query_parameters() -> int
```

### `get_number_of_event_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_number_of_event_fields() -> int
```

### `get_number_of_resource_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/storage/database.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_number_of_resource_fields() -> int
```


# stream
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-stream



# `prefect.server.events.stream`

## Functions

### `subscribed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
subscribed(filter: EventFilter) -> AsyncGenerator['Queue[ReceivedEvent]', None]
```

### `events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events(filter: EventFilter) -> AsyncGenerator[AsyncIterable[Optional[ReceivedEvent]], None]
```

### `distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
distributor() -> AsyncGenerator[messaging.MessageHandler, None]
```

### `start_distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_distributor() -> None
```

Starts the distributor consumer as a global background task

### `stop_distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop_distributor() -> None
```

Stops the distributor consumer global background task

### `run_distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_distributor(started: asyncio.Event) -> NoReturn
```

Runs the distributor consumer forever until it is cancelled

## Classes

### `Distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> dict[str, str]
```

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> None
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/stream.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service


# triggers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-events-triggers



# `prefect.server.events.triggers`

The triggers consumer watches events streaming in from the event bus and decides whether
to act on them based on the automations that users have set up.

## Functions

### `evaluate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
evaluate(session: AsyncSession, trigger: EventTrigger, bucket: 'ORMAutomationBucket', now: prefect.types._datetime.DateTime, triggering_event: Optional[ReceivedEvent]) -> 'ORMAutomationBucket | None'
```

Evaluates an Automation, either triggered by a specific event or proactively
on a time interval.  Evaluating a Automation updates the associated counters for
each automation, and will fire the associated action if it has met the threshold.

### `fire` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L304" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fire(session: AsyncSession, firing: Firing) -> None
```

### `evaluate_composite_trigger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
evaluate_composite_trigger(session: AsyncSession, firing: Firing) -> None
```

### `act` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
act(firing: Firing) -> None
```

Given a Automation that has been triggered, the triggering labels and event
(if there was one), publish an action for the `actions` service to process.

### `update_events_clock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L462" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_events_clock(event: ReceivedEvent) -> None
```

### `get_events_clock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L482" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_events_clock() -> Optional[float]
```

### `get_events_clock_offset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L487" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_events_clock_offset() -> float
```

Calculate the current clock offset.  This takes into account both the `occurred`
of the last event, as well as the time we *saw* the last event.  This helps to
ensure that in low volume environments, we don't end up getting huge offsets.

### `reset_events_clock` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L503" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_events_clock() -> None
```

### `reactive_evaluation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L510" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reactive_evaluation(event: ReceivedEvent, depth: int = 0) -> None
```

Evaluate all automations that may apply to this event.

event (ReceivedEvent): The event to evaluate. This object contains all the necessary information
about the event, including its type, associated resources, and metadata.
depth (int, optional): The current recursion depth. This is used to prevent infinite recursion
due to cyclic event dependencies. Defaults to 0 and is incremented with
each recursive call.

### `get_lost_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L624" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_lost_followers() -> List[ReceivedEvent]
```

Get followers that have been sitting around longer than our lookback

### `periodic_evaluation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L629" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
periodic_evaluation(now: prefect.types._datetime.DateTime) -> None
```

Periodic tasks that should be run regularly, but not as often as every event

### `evaluate_periodically` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L650" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
evaluate_periodically(periodic_granularity: timedelta) -> None
```

Runs periodic evaluation on the given interval

### `find_interested_triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L684" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
find_interested_triggers(event: ReceivedEvent) -> Collection[EventTrigger]
```

### `load_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L689" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_automation(automation: Optional[Automation]) -> None
```

Loads the given automation into memory so that it is available for evaluations

### `forget_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L707" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_automation(automation_id: UUID) -> None
```

Unloads the given automation from memory

### `automation_changed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L715" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
automation_changed(automation_id: UUID, event: Literal['automation__created', 'automation__updated', 'automation__deleted']) -> None
```

### `load_automations` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L730" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_automations(db: PrefectDBInterface, session: AsyncSession)
```

Loads all automations for the given set of accounts

### `remove_buckets_exceeding_threshold` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L746" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_buckets_exceeding_threshold(db: PrefectDBInterface, session: AsyncSession, trigger: EventTrigger)
```

Deletes bucket where the count has already exceeded the threshold

### `read_buckets_for_automation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L761" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_buckets_for_automation(db: PrefectDBInterface, session: AsyncSession, trigger: Trigger, batch_size: int = AUTOMATION_BUCKET_BATCH_SIZE) -> AsyncGenerator['ORMAutomationBucket', None]
```

Yields buckets for the given automation and trigger in batches.

### `read_bucket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L795" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_bucket(db: PrefectDBInterface, session: AsyncSession, trigger: Trigger, bucketing_key: Tuple[str, ...]) -> Optional['ORMAutomationBucket']
```

Gets the bucket this event would fall into for the given Automation, if there is
one currently

### `read_bucket_by_trigger_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L812" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_bucket_by_trigger_id(db: PrefectDBInterface, session: AsyncSession, automation_id: UUID, trigger_id: UUID, bucketing_key: Tuple[str, ...]) -> 'ORMAutomationBucket | None'
```

Gets the bucket this event would fall into for the given Automation, if there is
one currently

### `increment_bucket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L835" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
increment_bucket(db: PrefectDBInterface, session: AsyncSession, bucket: 'ORMAutomationBucket', count: int, last_event: Optional[ReceivedEvent]) -> 'ORMAutomationBucket'
```

Adds the given count to the bucket, returning the new bucket

### `start_new_bucket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L886" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_new_bucket(db: PrefectDBInterface, session: AsyncSession, trigger: EventTrigger, bucketing_key: Tuple[str, ...], start: prefect.types._datetime.DateTime, end: prefect.types._datetime.DateTime, count: int, triggered_at: Optional[prefect.types._datetime.DateTime] = None, last_event: Optional[ReceivedEvent] = None) -> 'ORMAutomationBucket'
```

Ensures that a bucket with the given start and end exists with the given count,
returning the new bucket

### `ensure_bucket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L946" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ensure_bucket(db: PrefectDBInterface, session: AsyncSession, trigger: EventTrigger, bucketing_key: Tuple[str, ...], start: prefect.types._datetime.DateTime, end: prefect.types._datetime.DateTime, last_event: Optional[ReceivedEvent], initial_count: int = 0) -> 'ORMAutomationBucket'
```

Ensures that a bucket has been started for the given automation and key,
returning the current bucket.  Will not modify the existing bucket.

### `remove_bucket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L999" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_bucket(db: PrefectDBInterface, session: AsyncSession, bucket: 'ORMAutomationBucket')
```

Removes the given bucket from the database

### `sweep_closed_buckets` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L1013" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
sweep_closed_buckets(db: PrefectDBInterface, session: AsyncSession, older_than: prefect.types._datetime.DateTime) -> None
```

### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L1023" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset() -> None
```

Resets the in-memory state of the service

### `listen_for_automation_changes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L1031" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
listen_for_automation_changes() -> None
```

Listens for any changes to automations via PostgreSQL NOTIFY/LISTEN,
and applies those changes to the set of loaded automations.

### `consumer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L1100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
consumer(periodic_granularity: timedelta = timedelta(seconds=5)) -> AsyncGenerator[MessageHandler, None]
```

The `triggers.consumer` processes all Events arriving on the event bus to
determine if they meet the automation criteria, queuing up a corresponding
`TriggeredAction` for the `actions` service if the automation criteria is met.

### `proactive_evaluation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L1159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
proactive_evaluation(trigger: EventTrigger, as_of: prefect.types._datetime.DateTime) -> prefect.types._datetime.DateTime
```

The core proactive evaluation operation for a single Automation

### `evaluate_proactive_triggers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/events/triggers.py#L1211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
evaluate_proactive_triggers() -> None
```


# exceptions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-exceptions



# `prefect.server.exceptions`

## Classes

### `ObjectNotFoundError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/exceptions.py#L4" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Error raised by the Prefect REST API when a requested object is not found.

If thrown during a request, this exception will be caught and
a 404 response will be returned.

### `OrchestrationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/exceptions.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An error raised while orchestrating a state transition

### `MissingVariableError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/exceptions.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An error raised by the Prefect REST API when attempting to create or update a
deployment with missing required variables.

### `FlowRunGraphTooLarge` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/exceptions.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised to indicate that a flow run's graph has more nodes that the configured
maximum


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-logs-__init__



# `prefect.server.logs`

*This module is empty or contains only private/internal implementations.*


# messaging
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-logs-messaging



# `prefect.server.logs.messaging`

Log messaging for streaming logs through the messaging system.

## Functions

### `create_log_publisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/messaging.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_log_publisher() -> AsyncGenerator[messaging.Publisher, None]
```

Creates a publisher for sending logs to the messaging system.

**Returns:**

* A messaging publisher configured for the "logs" topic

### `publish_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/messaging.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_logs(logs: list[Log]) -> None
```

Publishes logs to the messaging system.

**Args:**

* `logs`: The logs to publish


# stream
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-logs-stream



# `prefect.server.logs.stream`

Log streaming for live log distribution via websockets.

## Functions

### `subscribed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
subscribed(filter: LogFilter) -> AsyncGenerator['Queue[Log]', None]
```

Subscribe to a stream of logs matching the given filter.

**Args:**

* `filter`: The log filter to apply

### `logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
logs(filter: LogFilter) -> AsyncGenerator[AsyncIterable[Log | None], None]
```

Create a stream of logs matching the given filter.

**Args:**

* `filter`: The log filter to apply

### `log_matches_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
log_matches_filter(log: Log, filter: LogFilter) -> bool
```

Check if a log matches the given filter criteria.

**Args:**

* `log`: The log to check
* `filter`: The filter to apply

**Returns:**

* True if the log matches the filter, False otherwise

### `distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
distributor() -> AsyncGenerator[messaging.MessageHandler, None]
```

Create a message handler that distributes logs to subscribed clients.

### `start_distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_distributor() -> None
```

Starts the distributor consumer as a global background task

### `stop_distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop_distributor() -> None
```

Stops the distributor consumer global background task

### `run_distributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_distributor(started: asyncio.Event) -> NoReturn
```

Runs the distributor consumer forever until it is cancelled

## Classes

### `LogDistributor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L220" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Service for distributing logs to websocket subscribers

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/logs/stream.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-__init__



# `prefect.server.models`

*This module is empty or contains only private/internal implementations.*


# artifacts
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-artifacts



# `prefect.server.models.artifacts`

## Functions

### `create_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_artifact(session: AsyncSession, artifact: Artifact) -> orm_models.Artifact
```

### `read_latest_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_latest_artifact(db: PrefectDBInterface, session: AsyncSession, key: str) -> Union[orm_models.ArtifactCollection, None]
```

Reads the latest artifact by key.
Args:
session: A database session
key: The artifact key
Returns:
Artifact: The latest artifact

### `read_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_artifact(db: PrefectDBInterface, session: AsyncSession, artifact_id: UUID) -> Union[orm_models.Artifact, None]
```

Reads an artifact by id.

### `read_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_artifacts(db: PrefectDBInterface, session: AsyncSession, offset: Optional[int] = None, limit: Optional[int] = None, artifact_filter: Optional[filters.ArtifactFilter] = None, flow_run_filter: Optional[filters.FlowRunFilter] = None, task_run_filter: Optional[filters.TaskRunFilter] = None, deployment_filter: Optional[filters.DeploymentFilter] = None, flow_filter: Optional[filters.FlowFilter] = None, sort: sorting.ArtifactSort = sorting.ArtifactSort.ID_DESC) -> Sequence[orm_models.Artifact]
```

Reads artifacts.

**Args:**

* `session`: A database session
* `offset`: Query offset
* `limit`: Query limit
* `artifact_filter`: Only select artifacts matching this filter
* `flow_run_filter`: Only select artifacts whose flow runs matching this filter
* `task_run_filter`: Only select artifacts whose task runs matching this filter
* `deployment_filter`: Only select artifacts whose flow runs belong to deployments matching this filter
* `flow_filter`: Only select artifacts whose flow runs belong to flows matching this filter
* `work_pool_filter`: Only select artifacts whose flow runs belong to work pools matching this filter

### `read_latest_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L299" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_latest_artifacts(db: PrefectDBInterface, session: AsyncSession, offset: Optional[int] = None, limit: Optional[int] = None, artifact_filter: Optional[filters.ArtifactCollectionFilter] = None, flow_run_filter: Optional[filters.FlowRunFilter] = None, task_run_filter: Optional[filters.TaskRunFilter] = None, deployment_filter: Optional[filters.DeploymentFilter] = None, flow_filter: Optional[filters.FlowFilter] = None, sort: sorting.ArtifactCollectionSort = sorting.ArtifactCollectionSort.ID_DESC) -> Sequence[orm_models.ArtifactCollection]
```

Reads artifacts.

**Args:**

* `session`: A database session
* `offset`: Query offset
* `limit`: Query limit
* `artifact_filter`: Only select artifacts matching this filter
* `flow_run_filter`: Only select artifacts whose flow runs matching this filter
* `task_run_filter`: Only select artifacts whose task runs matching this filter
* `deployment_filter`: Only select artifacts whose flow runs belong to deployments matching this filter
* `flow_filter`: Only select artifacts whose flow runs belong to flows matching this filter
* `work_pool_filter`: Only select artifacts whose flow runs belong to work pools matching this filter

### `count_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_artifacts(db: PrefectDBInterface, session: AsyncSession, artifact_filter: Optional[filters.ArtifactFilter] = None, flow_run_filter: Optional[filters.FlowRunFilter] = None, task_run_filter: Optional[filters.TaskRunFilter] = None, deployment_filter: Optional[filters.DeploymentFilter] = None, flow_filter: Optional[filters.FlowFilter] = None) -> int
```

Counts artifacts.
Args:
session: A database session
artifact\_filter: Only select artifacts matching this filter
flow\_run\_filter: Only select artifacts whose flow runs matching this filter
task\_run\_filter: Only select artifacts whose task runs matching this filter

### `count_latest_artifacts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_latest_artifacts(db: PrefectDBInterface, session: AsyncSession, artifact_filter: Optional[filters.ArtifactCollectionFilter] = None, flow_run_filter: Optional[filters.FlowRunFilter] = None, task_run_filter: Optional[filters.TaskRunFilter] = None, deployment_filter: Optional[filters.DeploymentFilter] = None, flow_filter: Optional[filters.FlowFilter] = None) -> int
```

Counts artifacts.
Args:
session: A database session
artifact\_filter: Only select artifacts matching this filter
flow\_run\_filter: Only select artifacts whose flow runs matching this filter
task\_run\_filter: Only select artifacts whose task runs matching this filter

### `update_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L414" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_artifact(db: PrefectDBInterface, session: AsyncSession, artifact_id: UUID, artifact: actions.ArtifactUpdate) -> bool
```

Updates an artifact by id.

**Args:**

* `session`: A database session
* `artifact_id`: The artifact id to update
* `artifact`: An artifact model

**Returns:**

* True if the update was successful, False otherwise

### `delete_artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/artifacts.py#L453" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_artifact(db: PrefectDBInterface, session: AsyncSession, artifact_id: UUID) -> bool
```

Deletes an artifact by id.

The ArtifactCollection table is used to track the latest version of an artifact
by key. If we are deleting the latest version of an artifact from the Artifact
table, we need to first update the latest version referenced in ArtifactCollection
so that it points to the next latest version of the artifact.

Example:
If we have the following artifacts in Artifact:

* key: "foo", id: 1, created: 2020-01-01
* key: "foo", id: 2, created: 2020-01-02
* key: "foo", id: 3, created: 2020-01-03

the ArtifactCollection table has the following entry:

* key: "foo", latest\_id: 3

If we delete the artifact with id 3, we need to update the latest version of the
artifact with key "foo" to be the artifact with id 2.

**Args:**

* `session`: A database session
* `artifact_id`: The artifact id to delete

**Returns:**

* True if the delete was successful, False otherwise


# block_documents
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-block_documents



# `prefect.server.models.block_documents`

Functions for interacting with block document ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_block_document` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_document(db: PrefectDBInterface, session: AsyncSession, block_document: schemas.actions.BlockDocumentCreate) -> BlockDocument
```

### `block_document_with_unique_values_exists` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_document_with_unique_values_exists(db: PrefectDBInterface, session: AsyncSession, block_type_id: UUID, name: str) -> bool
```

### `read_block_document_by_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_document_by_id(session: AsyncSession, block_document_id: UUID, include_secrets: bool = False) -> Union[BlockDocument, None]
```

### `read_block_document_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_document_by_name(session: AsyncSession, name: str, block_type_slug: str, include_secrets: bool = False) -> Union[BlockDocument, None]
```

Read a block document with the given name and block type slug.

### `read_block_documents` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L303" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_documents(db: PrefectDBInterface, session: AsyncSession, block_document_filter: Optional[schemas.filters.BlockDocumentFilter] = None, block_type_filter: Optional[schemas.filters.BlockTypeFilter] = None, block_schema_filter: Optional[schemas.filters.BlockSchemaFilter] = None, include_secrets: bool = False, sort: schemas.sorting.BlockDocumentSort = schemas.sorting.BlockDocumentSort.NAME_ASC, offset: Optional[int] = None, limit: Optional[int] = None) -> List[BlockDocument]
```

Read block documents with an optional limit and offset

### `count_block_documents` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L441" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_block_documents(db: PrefectDBInterface, session: AsyncSession, block_document_filter: Optional[schemas.filters.BlockDocumentFilter] = None, block_type_filter: Optional[schemas.filters.BlockTypeFilter] = None, block_schema_filter: Optional[schemas.filters.BlockSchemaFilter] = None) -> int
```

Count block documents that match the filters.

### `delete_block_document` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L466" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_block_document(db: PrefectDBInterface, session: AsyncSession, block_document_id: UUID) -> bool
```

### `update_block_document` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L477" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_block_document(db: PrefectDBInterface, session: AsyncSession, block_document_id: UUID, block_document: schemas.actions.BlockDocumentUpdate) -> bool
```

### `create_block_document_reference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L633" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_document_reference(db: PrefectDBInterface, session: AsyncSession, block_document_reference: schemas.actions.BlockDocumentReferenceCreate) -> Union[orm_models.BlockDocumentReference, None]
```

### `delete_block_document_reference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_documents.py#L655" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_block_document_reference(db: PrefectDBInterface, session: AsyncSession, block_document_reference_id: UUID) -> bool
```


# block_registration
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-block_registration



# `prefect.server.models.block_registration`

## Functions

### `register_block_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_registration.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_block_schema(session: AsyncSession, block_schema: Union[schemas.core.BlockSchema, 'ClientBlockSchema']) -> UUID
```

Stores the provided block schema in the Prefect REST API database.

If a block schema with a matching checksum and version is already saved,
then the ID of the existing block schema will be returned.

**Args:**

* `session`: A database session.
* `block_schema`: A block schema object.

**Returns:**

* The ID of the registered block schema.

### `register_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_registration.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_block_type(session: AsyncSession, block_type: Union[schemas.core.BlockType, 'ClientBlockType']) -> UUID
```

Stores the provided block type in the Prefect REST API database.

If a block type with a matching slug is already saved, then the block type
will be updated to match the passed in block type.

**Args:**

* `session`: A database session.
* `block_type`: A block type object.

**Returns:**

* The ID of the registered block type.

### `run_block_auto_registration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_registration.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_block_auto_registration(session: AsyncSession) -> None
```

Registers all blocks in the client block registry and any blocks from Prefect
Collections that are configured for auto-registration.

**Args:**

* `session`: A database session.


# block_schemas
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-block_schemas



# `prefect.server.models.block_schemas`

Functions for interacting with block schema ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_block_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_schema(db: PrefectDBInterface, session: AsyncSession, block_schema: Union[schemas.actions.BlockSchemaCreate, schemas.core.BlockSchema, 'ClientBlockSchemaCreate', 'ClientBlockSchema'], override: bool = False, definitions: Optional[dict[str, Any]] = None) -> Union[BlockSchema, orm_models.BlockSchema]
```

Create a new block schema.

**Args:**

* `session`: A database session
* `block_schema`: a block schema object
* `definitions`: Definitions of fields from block schema fields
  attribute. Used when recursively creating nested block schemas

**Returns:**

* an ORM block schema model

### `delete_block_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_block_schema(db: PrefectDBInterface, session: AsyncSession, block_schema_id: UUID) -> bool
```

Delete a block schema by id.

**Args:**

* `session`: A database session
* `block_schema_id`: a block schema id

**Returns:**

* whether or not the block schema was deleted

### `read_block_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L307" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_schema(db: PrefectDBInterface, session: AsyncSession, block_schema_id: UUID) -> Union[BlockSchema, None]
```

Reads a block schema by id. Will reconstruct the block schema's fields attribute
to include block schema references.

**Args:**

* `session`: A database session
* `block_schema_id`: a block\_schema id

**Returns:**

* orm\_models..BlockSchema: the block\_schema

### `read_block_schemas` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L592" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_schemas(db: PrefectDBInterface, session: AsyncSession, block_schema_filter: Optional[schemas.filters.BlockSchemaFilter] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> List[BlockSchema]
```

Reads block schemas, optionally filtered by type or name.

**Args:**

* `session`: A database session
* `block_schema_filter`: a block schema filter object
* `limit`: query limit
* `offset`: query offset

**Returns:**

* List\[orm\_models.BlockSchema]: the block\_schemas

### `read_block_schema_by_checksum` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L705" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_schema_by_checksum(db: PrefectDBInterface, session: AsyncSession, checksum: str, version: Optional[str] = None) -> Optional[BlockSchema]
```

Reads a block\_schema by checksum. Will reconstruct the block schema's fields
attribute to include block schema references.

**Args:**

* `session`: A database session
* `checksum`: a block\_schema checksum
* `version`: A block\_schema version

**Returns:**

* orm\_models.BlockSchema: the block\_schema

### `read_available_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L786" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_available_block_capabilities(db: PrefectDBInterface, session: AsyncSession) -> List[str]
```

Retrieves a list of all available block capabilities.

**Args:**

* `session`: A database session.

**Returns:**

* List\[str]: List of all available block capabilities.

### `create_block_schema_reference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L811" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_schema_reference(db: PrefectDBInterface, session: AsyncSession, block_schema_reference: schemas.core.BlockSchemaReference) -> Union[orm_models.BlockSchemaReference, None]
```

Retrieves a list of all available block capabilities.

**Args:**

* `session`: A database session.
* `block_schema_reference`: A block schema reference object.

**Returns:**

* orm\_models.BlockSchemaReference: The created BlockSchemaReference

## Classes

### `MissingBlockTypeException` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_schemas.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the block type corresponding to a block schema cannot be found


# block_types
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-block_types



# `prefect.server.models.block_types`

Functions for interacting with block type ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_types.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_block_type(db: PrefectDBInterface, session: AsyncSession, block_type: Union[schemas.core.BlockType, 'ClientBlockType'], override: bool = False) -> Union[BlockType, None]
```

Create a new block type.

**Args:**

* `session`: A database session
* `block_type`: a block type object

**Returns:**

* an ORM block type model

### `read_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_types.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_type(db: PrefectDBInterface, session: AsyncSession, block_type_id: UUID) -> Union[BlockType, None]
```

Reads a block type by id.

**Args:**

* `session`: A database session
* `block_type_id`: a block\_type id

**Returns:**

* an ORM block type model

### `read_block_type_by_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_types.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_type_by_slug(db: PrefectDBInterface, session: AsyncSession, block_type_slug: str) -> Union[BlockType, None]
```

Reads a block type by slug.

**Args:**

* `session`: A database session
* `block_type_slug`: a block type slug

**Returns:**

* an ORM block type model

### `read_block_types` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_types.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_block_types(db: PrefectDBInterface, session: AsyncSession, block_type_filter: Optional[schemas.filters.BlockTypeFilter] = None, block_schema_filter: Optional[schemas.filters.BlockSchemaFilter] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> Sequence[BlockType]
```

Reads block types with an optional limit and offset

Args:

**Returns:**

* List\[BlockType]: List of

### `update_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_types.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_block_type(db: PrefectDBInterface, session: AsyncSession, block_type_id: Union[str, UUID], block_type: Union[schemas.actions.BlockTypeUpdate, schemas.core.BlockType, 'ClientBlockTypeUpdate', 'ClientBlockType']) -> bool
```

Update a block type by id.

**Args:**

* `session`: A database session
* `block_type_id`: Data to update block type with
* `block_type`: A block type id

**Returns:**

* True if the block type was updated

### `delete_block_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/block_types.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_block_type(db: PrefectDBInterface, session: AsyncSession, block_type_id: str) -> bool
```

Delete a block type by id.

**Args:**

* `session`: A database session
* `block_type_id`: A block type id

**Returns:**

* True if the block type was updated


# concurrency_limits
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-concurrency_limits



# `prefect.server.models.concurrency_limits`

Functions for interacting with concurrency limit ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_concurrency_limit(db: PrefectDBInterface, session: AsyncSession, concurrency_limit: schemas.core.ConcurrencyLimit) -> orm_models.ConcurrencyLimit
```

### `read_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limit(db: PrefectDBInterface, session: AsyncSession, concurrency_limit_id: UUID) -> Union[orm_models.ConcurrencyLimit, None]
```

Reads a concurrency limit by id. If used for orchestration, simultaneous read race
conditions might allow the concurrency limit to be temporarily exceeded.

### `read_concurrency_limit_by_tag` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limit_by_tag(db: PrefectDBInterface, session: AsyncSession, tag: str) -> Union[orm_models.ConcurrencyLimit, None]
```

Reads a concurrency limit by tag. If used for orchestration, simultaneous read race
conditions might allow the concurrency limit to be temporarily exceeded.

### `reset_concurrency_limit_by_tag` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_concurrency_limit_by_tag(db: PrefectDBInterface, session: AsyncSession, tag: str, slot_override: Optional[List[UUID]] = None) -> Union[orm_models.ConcurrencyLimit, None]
```

Resets a concurrency limit by tag.

### `filter_concurrency_limits_for_orchestration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter_concurrency_limits_for_orchestration(db: PrefectDBInterface, session: AsyncSession, tags: List[str]) -> Sequence[orm_models.ConcurrencyLimit]
```

Filters concurrency limits by tag. This will apply a "select for update" lock on
these rows to prevent simultaneous read race conditions from enabling the
the concurrency limit on these tags from being temporarily exceeded.

### `delete_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_concurrency_limit(db: PrefectDBInterface, session: AsyncSession, concurrency_limit_id: UUID) -> bool
```

### `delete_concurrency_limit_by_tag` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_concurrency_limit_by_tag(db: PrefectDBInterface, session: AsyncSession, tag: str) -> bool
```

### `read_concurrency_limits` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limits(db: PrefectDBInterface, session: AsyncSession, limit: Optional[int] = None, offset: Optional[int] = None) -> Sequence[orm_models.ConcurrencyLimit]
```

Reads a concurrency limits. If used for orchestration, simultaneous read race
conditions might allow the concurrency limit to be temporarily exceeded.

**Args:**

* `session`: A database session
* `offset`: Query offset
* `limit`: Query limit

**Returns:**

* List\[orm\_models.ConcurrencyLimit]: concurrency limits


# concurrency_limits_v2
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-concurrency_limits_v2



# `prefect.server.models.concurrency_limits_v2`

## Functions

### `active_slots_after_decay` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
active_slots_after_decay(db: PrefectDBInterface) -> ColumnElement[float]
```

### `denied_slots_after_decay` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
denied_slots_after_decay(db: PrefectDBInterface) -> ColumnElement[float]
```

### `create_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_concurrency_limit(db: PrefectDBInterface, session: AsyncSession, concurrency_limit: Union[schemas.actions.ConcurrencyLimitV2Create, schemas.core.ConcurrencyLimitV2]) -> orm_models.ConcurrencyLimitV2
```

### `read_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_concurrency_limit(db: PrefectDBInterface, session: AsyncSession, concurrency_limit_id: Optional[UUID] = None, name: Optional[str] = None) -> Union[orm_models.ConcurrencyLimitV2, None]
```

### `read_all_concurrency_limits` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_all_concurrency_limits(db: PrefectDBInterface, session: AsyncSession, limit: int, offset: int) -> Sequence[orm_models.ConcurrencyLimitV2]
```

### `update_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_concurrency_limit(db: PrefectDBInterface, session: AsyncSession, concurrency_limit: schemas.actions.ConcurrencyLimitV2Update, concurrency_limit_id: Optional[UUID] = None, name: Optional[str] = None) -> bool
```

### `delete_concurrency_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_concurrency_limit(db: PrefectDBInterface, session: AsyncSession, concurrency_limit_id: Optional[UUID] = None, name: Optional[str] = None) -> bool
```

### `bulk_read_concurrency_limits` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_read_concurrency_limits(db: PrefectDBInterface, session: AsyncSession, names: List[str]) -> List[orm_models.ConcurrencyLimitV2]
```

### `bulk_increment_active_slots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_increment_active_slots(db: PrefectDBInterface, session: AsyncSession, concurrency_limit_ids: List[UUID], slots: int) -> bool
```

### `bulk_decrement_active_slots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_decrement_active_slots(db: PrefectDBInterface, session: AsyncSession, concurrency_limit_ids: List[UUID], slots: int, occupancy_seconds: Optional[float] = None) -> bool
```

### `bulk_update_denied_slots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/concurrency_limits_v2.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_update_denied_slots(db: PrefectDBInterface, session: AsyncSession, concurrency_limit_ids: List[UUID], slots: int) -> bool
```


# configuration
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-configuration



# `prefect.server.models.configuration`

## Functions

### `write_configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/configuration.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_configuration(db: PrefectDBInterface, session: AsyncSession, configuration: schemas.core.Configuration) -> orm_models.Configuration
```

### `read_configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/configuration.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_configuration(db: PrefectDBInterface, session: AsyncSession, key: str) -> Optional[schemas.core.Configuration]
```


# csrf_token
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-csrf_token



# `prefect.server.models.csrf_token`

## Functions

### `create_or_update_csrf_token` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/csrf_token.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_or_update_csrf_token(db: PrefectDBInterface, session: AsyncSession, client: str) -> core.CsrfToken
```

Create or update a CSRF token for a client. If the client already has a
token, it will be updated.

**Args:**

* `session`: The database session
* `client`: The client identifier

**Returns:**

* core.CsrfToken: The CSRF token

### `read_token_for_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/csrf_token.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_token_for_client(db: PrefectDBInterface, session: AsyncSession, client: str) -> Optional[core.CsrfToken]
```

Read a CSRF token for a client.

**Args:**

* `session`: The database session
* `client`: The client identifier

**Returns:**

* Optional\[core.CsrfToken]: The CSRF token, if it exists and is not
  expired.

### `delete_expired_tokens` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/csrf_token.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_expired_tokens(db: PrefectDBInterface, session: AsyncSession) -> int
```

Delete expired CSRF tokens.

**Args:**

* `session`: The database session

**Returns:**

* The number of tokens deleted


# deployments
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-deployments



# `prefect.server.models.deployments`

Functions for interacting with deployment ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_deployment(db: PrefectDBInterface, session: AsyncSession, deployment: schemas.core.Deployment | schemas.actions.DeploymentCreate) -> Optional[orm_models.Deployment]
```

Upserts a deployment.

**Args:**

* `session`: a database session
* `deployment`: a deployment model

**Returns:**

* orm\_models.Deployment: the newly-created or updated deployment

### `update_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_deployment(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID, deployment: schemas.actions.DeploymentUpdate) -> bool
```

Updates a deployment.

**Args:**

* `session`: a database session
* `deployment_id`: the ID of the deployment to modify
* `deployment`: changes to a deployment model

**Returns:**

* whether the deployment was updated

### `read_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID) -> Optional[orm_models.Deployment]
```

Reads a deployment by id.

**Args:**

* `session`: A database session
* `deployment_id`: a deployment id

**Returns:**

* orm\_models.Deployment: the deployment

### `read_deployment_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment_by_name(db: PrefectDBInterface, session: AsyncSession, name: str, flow_name: str) -> Optional[orm_models.Deployment]
```

Reads a deployment by name.

**Args:**

* `session`: A database session
* `name`: a deployment name
* `flow_name`: the name of the flow the deployment belongs to

**Returns:**

* orm\_models.Deployment: the deployment

### `read_deployments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L462" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployments(db: PrefectDBInterface, session: AsyncSession, offset: Optional[int] = None, limit: Optional[int] = None, flow_filter: Optional[schemas.filters.FlowFilter] = None, flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None, task_run_filter: Optional[schemas.filters.TaskRunFilter] = None, deployment_filter: Optional[schemas.filters.DeploymentFilter] = None, work_pool_filter: Optional[schemas.filters.WorkPoolFilter] = None, work_queue_filter: Optional[schemas.filters.WorkQueueFilter] = None, sort: schemas.sorting.DeploymentSort = schemas.sorting.DeploymentSort.NAME_ASC) -> Sequence[orm_models.Deployment]
```

Read deployments.

**Args:**

* `session`: A database session
* `offset`: Query offset
* `limit`: Query limit
* `flow_filter`: only select deployments whose flows match these criteria
* `flow_run_filter`: only select deployments whose flow runs match these criteria
* `task_run_filter`: only select deployments whose task runs match these criteria
* `deployment_filter`: only select deployment that match these filters
* `work_pool_filter`: only select deployments whose work pools match these criteria
* `work_queue_filter`: only select deployments whose work pool queues match these criteria
* `sort`: the sort criteria for selected deployments. Defaults to `name` ASC.

**Returns:**

* list\[orm\_models.Deployment]: deployments

### `count_deployments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L517" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_deployments(db: PrefectDBInterface, session: AsyncSession, flow_filter: Optional[schemas.filters.FlowFilter] = None, flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None, task_run_filter: Optional[schemas.filters.TaskRunFilter] = None, deployment_filter: Optional[schemas.filters.DeploymentFilter] = None, work_pool_filter: Optional[schemas.filters.WorkPoolFilter] = None, work_queue_filter: Optional[schemas.filters.WorkQueueFilter] = None) -> int
```

Count deployments.

**Args:**

* `session`: A database session
* `flow_filter`: only count deployments whose flows match these criteria
* `flow_run_filter`: only count deployments whose flow runs match these criteria
* `task_run_filter`: only count deployments whose task runs match these criteria
* `deployment_filter`: only count deployment that match these filters
* `work_pool_filter`: only count deployments that match these work pool filters
* `work_queue_filter`: only count deployments that match these work pool queue filters

**Returns:**

* the number of deployments matching filters

### `delete_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L561" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_deployment(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID) -> bool
```

Delete a deployment by id.

**Args:**

* `session`: A database session
* `deployment_id`: a deployment id

**Returns:**

* whether or not the deployment was deleted

### `schedule_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L604" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schedule_runs(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID, start_time: Optional[datetime.datetime] = None, end_time: Optional[datetime.datetime] = None, min_time: Optional[datetime.timedelta] = None, min_runs: Optional[int] = None, max_runs: Optional[int] = None, auto_scheduled: bool = True) -> Sequence[UUID]
```

Schedule flow runs for a deployment

**Args:**

* `session`: a database session
* `deployment_id`: the id of the deployment to schedule
* `start_time`: the time from which to start scheduling runs
* `end_time`: runs will be scheduled until at most this time
* `min_time`: runs will be scheduled until at least this far in the future
* `min_runs`: a minimum amount of runs to schedule
* `max_runs`: a maximum amount of runs to schedule

This function will generate the minimum number of runs that satisfy the min
and max times, and the min and max counts. Specifically, the following order
will be respected.

* Runs will be generated starting on or after the `start_time`
* No more than `max_runs` runs will be generated
* No runs will be generated after `end_time` is reached
* At least `min_runs` runs will be generated
* Runs will be generated until at least `start_time` + `min_time` is reached

**Returns:**

* a list of flow run ids scheduled for the deployment

### `check_work_queues_for_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L861" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_work_queues_for_deployment(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID) -> Sequence[orm_models.WorkQueue]
```

Get work queues that can pick up the specified deployment.

Work queues will pick up a deployment when all of the following are met.

* The deployment has ALL tags that the work queue has (i.e. the work
  queue's tags must be a subset of the deployment's tags).
* The work queue's specified deployment IDs match the deployment's ID,
  or the work queue does NOT have specified deployment IDs.
* The work queue's specified flow runners match the deployment's flow
  runner or the work queue does NOT have a specified flow runner.

Notes on the query:

* Our database currently allows either "null" and empty lists as
  null values in filters, so we need to catch both cases with "or".
* `A.contains(B)` should be interpreted as "True if A
  contains B".

**Returns:**

* List\[orm\_models.WorkQueue]: WorkQueues

### `create_deployment_schedules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L921" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_deployment_schedules(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID, schedules: list[schemas.actions.DeploymentScheduleCreate]) -> list[schemas.core.DeploymentSchedule]
```

Creates a deployment's schedules.

**Args:**

* `session`: A database session
* `deployment_id`: a deployment id
* `schedules`: a list of deployment schedule create actions

### `read_deployment_schedules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L955" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_deployment_schedules(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID, deployment_schedule_filter: Optional[schemas.filters.DeploymentScheduleFilter] = None) -> list[schemas.core.DeploymentSchedule]
```

Reads a deployment's schedules.

**Args:**

* `session`: A database session
* `deployment_id`: a deployment id

**Returns:**

* list\[schemas.core.DeploymentSchedule]: the deployment's schedules

### `update_deployment_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L992" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_deployment_schedule(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID, schedule: schemas.actions.DeploymentScheduleUpdate, deployment_schedule_id: UUID | None = None, deployment_schedule_slug: str | None = None) -> bool
```

Updates a deployment's schedules.

**Args:**

* `session`: A database session
* `deployment_schedule_id`: a deployment schedule id
* `schedule`: a deployment schedule update action

### `delete_schedules_for_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L1039" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_schedules_for_deployment(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID) -> bool
```

Deletes a deployment schedule.

**Args:**

* `session`: A database session
* `deployment_id`: a deployment id

### `delete_deployment_schedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L1064" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_deployment_schedule(db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID, deployment_schedule_id: UUID) -> bool
```

Deletes a deployment schedule.

**Args:**

* `session`: A database session
* `deployment_schedule_id`: a deployment schedule id

### `mark_deployments_ready` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L1090" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
mark_deployments_ready(db: PrefectDBInterface, deployment_ids: Optional[Iterable[UUID]] = None, work_queue_ids: Optional[Iterable[UUID]] = None) -> None
```

### `mark_deployments_not_ready` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L1147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
mark_deployments_not_ready(db: PrefectDBInterface, deployment_ids: Optional[Iterable[UUID]] = None, work_queue_ids: Optional[Iterable[UUID]] = None) -> None
```

### `with_system_labels_for_deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L1201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_system_labels_for_deployment(session: AsyncSession, deployment: schemas.core.Deployment) -> schemas.core.KeyValueLabels
```

Augment user supplied labels with system default labels for a deployment.

### `with_system_labels_for_deployment_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/deployments.py#L1222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_system_labels_for_deployment_flow_run(session: AsyncSession, deployment: orm_models.Deployment, user_supplied_labels: Optional[schemas.core.KeyValueLabels] = None) -> schemas.core.KeyValueLabels
```

Generate system labels for a flow run created from a deployment.

**Args:**

* `session`: Database session
* `deployment`: The deployment the flow run is created from
* `user_supplied_labels`: Optional user-supplied labels to include

**Returns:**

* Complete set of labels for the flow run


# events
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-events



# `prefect.server.models.events`

## Functions

### `flow_run_state_change_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/events.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_state_change_event(session: AsyncSession, occurred: datetime, flow_run: ORMFlowRun, initial_state_id: Optional[UUID], initial_state: Optional[schemas.states.State], validated_state_id: Optional[UUID], validated_state: schemas.states.State) -> Event
```

### `state_payload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/events.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state_payload(state: Optional[schemas.states.State]) -> Optional[Dict[str, str]]
```

Given a State, return the essential string parts of it for use in an
event payload

### `deployment_status_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/events.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deployment_status_event(session: AsyncSession, deployment_id: UUID, status: DeploymentStatus, occurred: DateTime) -> Event
```

### `work_queue_status_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/events.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
work_queue_status_event(session: AsyncSession, work_queue: 'ORMWorkQueue', occurred: DateTime) -> Event
```

### `work_pool_status_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/events.py#L401" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
work_pool_status_event(event_id: UUID, occurred: DateTime, pre_update_work_pool: Optional['ORMWorkPool'], work_pool: 'ORMWorkPool') -> Event
```


# flow_run_input
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-flow_run_input



# `prefect.server.models.flow_run_input`

## Functions

### `create_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_run_input.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run_input(db: PrefectDBInterface, session: AsyncSession, flow_run_input: schemas.core.FlowRunInput) -> schemas.core.FlowRunInput
```

### `filter_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_run_input.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter_flow_run_input(db: PrefectDBInterface, session: AsyncSession, flow_run_id: uuid.UUID, prefix: str, limit: int, exclude_keys: List[str]) -> List[schemas.core.FlowRunInput]
```

### `read_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_run_input.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_input(db: PrefectDBInterface, session: AsyncSession, flow_run_id: uuid.UUID, key: str) -> Optional[schemas.core.FlowRunInput]
```

### `delete_flow_run_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_run_input.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow_run_input(db: PrefectDBInterface, session: AsyncSession, flow_run_id: uuid.UUID, key: str) -> bool
```


# flow_run_states
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-flow_run_states



# `prefect.server.models.flow_run_states`

Functions for interacting with flow run state ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `read_flow_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_run_states.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_state(db: PrefectDBInterface, session: AsyncSession, flow_run_state_id: UUID) -> Union[orm_models.FlowRunState, None]
```

Reads a flow run state by id.

**Args:**

* `session`: A database session
* `flow_run_state_id`: a flow run state id

**Returns:**

* orm\_models.FlowRunState: the flow state

### `read_flow_run_states` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_run_states.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_states(db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID) -> Sequence[orm_models.FlowRunState]
```

Reads flow runs states for a flow run.

**Args:**

* `session`: A database session
* `flow_run_id`: the flow run id

**Returns:**

* List\[orm\_models.FlowRunState]: the flow run states

### `delete_flow_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_run_states.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow_run_state(db: PrefectDBInterface, session: AsyncSession, flow_run_state_id: UUID) -> bool
```

Delete a flow run state by id.

**Args:**

* `session`: A database session
* `flow_run_state_id`: a flow run state id

**Returns:**

* whether or not the flow run state was deleted


# flow_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-flow_runs



# `prefect.server.models.flow_runs`

Functions for interacting with flow run ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow_run(db: PrefectDBInterface, session: AsyncSession, flow_run: schemas.core.FlowRun, orchestration_parameters: Optional[dict[str, Any]] = None) -> orm_models.FlowRun
```

Creates a new flow run.

If the provided flow run has a state attached, it will also be created.

**Args:**

* `session`: a database session
* `flow_run`: a flow run model

**Returns:**

* orm\_models.FlowRun: the newly-created flow run

### `update_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_flow_run(db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID, flow_run: schemas.actions.FlowRunUpdate) -> bool
```

Updates a flow run.

**Args:**

* `session`: a database session
* `flow_run_id`: the flow run id to update
* `flow_run`: a flow run model

**Returns:**

* whether or not matching rows were found to update

### `read_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run(db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID, for_update: bool = False) -> Optional[orm_models.FlowRun]
```

Reads a flow run by id.

**Args:**

* `session`: A database session
* `flow_run_id`: a flow run id

**Returns:**

* orm\_models.FlowRun: the flow run

### `read_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L282" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_runs(db: PrefectDBInterface, session: AsyncSession, columns: Optional[list[str]] = None, flow_filter: Optional[schemas.filters.FlowFilter] = None, flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None, task_run_filter: Optional[schemas.filters.TaskRunFilter] = None, deployment_filter: Optional[schemas.filters.DeploymentFilter] = None, work_pool_filter: Optional[schemas.filters.WorkPoolFilter] = None, work_queue_filter: Optional[schemas.filters.WorkQueueFilter] = None, offset: Optional[int] = None, limit: Optional[int] = None, sort: schemas.sorting.FlowRunSort = schemas.sorting.FlowRunSort.ID_DESC) -> Sequence[orm_models.FlowRun]
```

Read flow runs.

**Args:**

* `session`: a database session
* `columns`: a list of the flow run ORM columns to load, for performance
* `flow_filter`: only select flow runs whose flows match these filters
* `flow_run_filter`: only select flow runs match these filters
* `task_run_filter`: only select flow runs whose task runs match these filters
* `deployment_filter`: only select flow runs whose deployments match these filters
* `offset`: Query offset
* `limit`: Query limit
* `sort`: Query sort

**Returns:**

* List\[orm\_models.FlowRun]: flow runs

### `cleanup_flow_run_concurrency_slots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cleanup_flow_run_concurrency_slots(session: AsyncSession, flow_run: orm_models.FlowRun) -> None
```

Cleanup flow run related resources, such as releasing concurrency slots.
All operations should be idempotent and safe to call multiple times.
IMPORTANT: This run may no longer exist in the database when this operation occurs.

### `read_task_run_dependencies` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L387" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_dependencies(session: AsyncSession, flow_run_id: UUID) -> List[DependencyResult]
```

Get a task run dependency map for a given flow run.

### `count_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_flow_runs(db: PrefectDBInterface, session: AsyncSession, flow_filter: Optional[schemas.filters.FlowFilter] = None, flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None, task_run_filter: Optional[schemas.filters.TaskRunFilter] = None, deployment_filter: Optional[schemas.filters.DeploymentFilter] = None, work_pool_filter: Optional[schemas.filters.WorkPoolFilter] = None, work_queue_filter: Optional[schemas.filters.WorkQueueFilter] = None) -> int
```

Count flow runs.

**Args:**

* `session`: a database session
* `flow_filter`: only count flow runs whose flows match these filters
* `flow_run_filter`: only count flow runs that match these filters
* `task_run_filter`: only count flow runs whose task runs match these filters
* `deployment_filter`: only count flow runs whose deployments match these filters

**Returns:**

* count of flow runs

### `delete_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L477" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow_run(db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID) -> bool
```

Delete a flow run by flow\_run\_id, handling concurrency limits if applicable.

**Args:**

* `session`: A database session
* `flow_run_id`: a flow run id

**Returns:**

* whether or not the flow run was deleted

### `set_flow_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_flow_run_state(session: AsyncSession, flow_run_id: UUID, state: schemas.states.State, force: bool = False, flow_policy: Optional[Type[FlowRunOrchestrationPolicy]] = None, orchestration_parameters: Optional[Dict[str, Any]] = None, client_version: Optional[str] = None) -> OrchestrationResult
```

Creates a new orchestrated flow run state.

Setting a new state on a run is the one of the principal actions that is governed by
Prefect's orchestration logic. Setting a new run state will not guarantee creation,
but instead trigger orchestration rules to govern the proposed `state` input. If
the state is considered valid, it will be written to the database. Otherwise, a
it's possible a different state, or no state, will be created. A `force` flag is
supplied to bypass a subset of orchestration logic.

**Args:**

* `session`: a database session
* `flow_run_id`: the flow run id
* `state`: a flow run state model
* `force`: if False, orchestration rules will be applied that may alter or prevent
  the state transition. If True, orchestration rules are not applied.

**Returns:**

* OrchestrationResult object

### `read_flow_run_graph` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L597" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_run_graph(db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID, since: datetime.datetime = earliest_possible_datetime()) -> Graph
```

Given a flow run, return the graph of it's task and subflow runs. If a `since`
datetime is provided, only return items that may have changed since that time.

### `with_system_labels_for_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L617" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_system_labels_for_flow_run(session: AsyncSession, flow_run: Union[schemas.core.FlowRun, schemas.actions.FlowRunCreate]) -> schemas.core.KeyValueLabels
```

Augment user supplied labels with system default labels for a flow
run.

### `update_flow_run_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L654" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_flow_run_labels(db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID, labels: KeyValueLabels) -> bool
```

Update flow run labels by patching existing labels with new values.
Args:
session: A database session
flow\_run\_id: the flow run id to update
labels: the new labels to patch into existing labels
Returns:
bool: whether the update was successful

## Classes

### `DependencyResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flow_runs.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# flows
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-flows



# `prefect.server.models.flows`

Functions for interacting with flow ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_flow(db: PrefectDBInterface, session: AsyncSession, flow: schemas.core.Flow) -> orm_models.Flow
```

Creates a new flow.

If a flow with the same name already exists, the existing flow is returned.

**Args:**

* `session`: a database session
* `flow`: a flow model

**Returns:**

* orm\_models.Flow: the newly-created or existing flow

### `update_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_flow(db: PrefectDBInterface, session: AsyncSession, flow_id: UUID, flow: schemas.actions.FlowUpdate) -> bool
```

Updates a flow.

**Args:**

* `session`: a database session
* `flow_id`: the flow id to update
* `flow`: a flow update model

**Returns:**

* whether or not matching rows were found to update

### `read_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow(db: PrefectDBInterface, session: AsyncSession, flow_id: UUID) -> Optional[orm_models.Flow]
```

Reads a flow by id.

**Args:**

* `session`: A database session
* `flow_id`: a flow id

**Returns:**

* orm\_models.Flow: the flow

### `read_flow_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_by_name(db: PrefectDBInterface, session: AsyncSession, name: str) -> Optional[orm_models.Flow]
```

Reads a flow by name.

**Args:**

* `session`: A database session
* `name`: a flow name

**Returns:**

* orm\_models.Flow: the flow

### `read_flows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flows(db: PrefectDBInterface, session: AsyncSession, flow_filter: Union[schemas.filters.FlowFilter, None] = None, flow_run_filter: Union[schemas.filters.FlowRunFilter, None] = None, task_run_filter: Union[schemas.filters.TaskRunFilter, None] = None, deployment_filter: Union[schemas.filters.DeploymentFilter, None] = None, work_pool_filter: Union[schemas.filters.WorkPoolFilter, None] = None, sort: schemas.sorting.FlowSort = schemas.sorting.FlowSort.NAME_ASC, offset: Union[int, None] = None, limit: Union[int, None] = None) -> Sequence[orm_models.Flow]
```

Read multiple flows.

**Args:**

* `session`: A database session
* `flow_filter`: only select flows that match these filters
* `flow_run_filter`: only select flows whose flow runs match these filters
* `task_run_filter`: only select flows whose task runs match these filters
* `deployment_filter`: only select flows whose deployments match these filters
* `work_pool_filter`: only select flows whose work pools match these filters
* `offset`: Query offset
* `limit`: Query limit

**Returns:**

* List\[orm\_models.Flow]: flows

### `count_flows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_flows(db: PrefectDBInterface, session: AsyncSession, flow_filter: Union[schemas.filters.FlowFilter, None] = None, flow_run_filter: Union[schemas.filters.FlowRunFilter, None] = None, task_run_filter: Union[schemas.filters.TaskRunFilter, None] = None, deployment_filter: Union[schemas.filters.DeploymentFilter, None] = None, work_pool_filter: Union[schemas.filters.WorkPoolFilter, None] = None) -> int
```

Count flows.

**Args:**

* `session`: A database session
* `flow_filter`: only count flows that match these filters
* `flow_run_filter`: only count flows whose flow runs match these filters
* `task_run_filter`: only count flows whose task runs match these filters
* `deployment_filter`: only count flows whose deployments match these filters
* `work_pool_filter`: only count flows whose work pools match these filters

**Returns:**

* count of flows

### `delete_flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_flow(db: PrefectDBInterface, session: AsyncSession, flow_id: UUID) -> bool
```

Delete a flow by id.

**Args:**

* `session`: A database session
* `flow_id`: a flow id

**Returns:**

* whether or not the flow was deleted

### `read_flow_labels` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/flows.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_flow_labels(db: PrefectDBInterface, session: AsyncSession, flow_id: UUID) -> Union[schemas.core.KeyValueLabels, None]
```


# logs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-logs



# `prefect.server.models.logs`

Functions for interacting with log ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `split_logs_into_batches` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/logs.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
split_logs_into_batches(logs: Sequence[schemas.actions.LogCreate]) -> Generator[Tuple[LogCreate, ...], None, None]
```

### `create_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/logs.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_logs(db: PrefectDBInterface, session: AsyncSession, logs: Sequence[LogCreate]) -> None
```

Creates new logs

**Args:**

* `session`: a database session
* `logs`: a list of log schemas

**Returns:**

* None

### `read_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/logs.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_logs(db: PrefectDBInterface, session: AsyncSession, log_filter: Optional[schemas.filters.LogFilter], offset: Optional[int] = None, limit: Optional[int] = None, sort: schemas.sorting.LogSort = schemas.sorting.LogSort.TIMESTAMP_ASC) -> Sequence[orm_models.Log]
```

Read logs.

**Args:**

* `session`: a database session
* `db`: the database interface
* `log_filter`: only select logs that match these filters
* `offset`: Query offset
* `limit`: Query limit
* `sort`: Query sort

**Returns:**

* List\[orm\_models.Log]: the matching logs

### `delete_logs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/logs.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_logs(db: PrefectDBInterface, session: AsyncSession, log_filter: schemas.filters.LogFilter) -> int
```


# saved_searches
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-saved_searches



# `prefect.server.models.saved_searches`

Functions for interacting with saved search ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_saved_search` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/saved_searches.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_saved_search(db: PrefectDBInterface, session: AsyncSession, saved_search: schemas.core.SavedSearch) -> orm_models.SavedSearch
```

Upserts a SavedSearch.

If a SavedSearch with the same name exists, all properties will be updated.

**Args:**

* `session`: a database session
* `saved_search`: a SavedSearch model

**Returns:**

* orm\_models.SavedSearch: the newly-created or updated SavedSearch

### `read_saved_search` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/saved_searches.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_saved_search(db: PrefectDBInterface, session: AsyncSession, saved_search_id: UUID) -> Union[orm_models.SavedSearch, None]
```

Reads a SavedSearch by id.

**Args:**

* `session`: A database session
* `saved_search_id`: a SavedSearch id

**Returns:**

* orm\_models.SavedSearch: the SavedSearch

### `read_saved_search_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/saved_searches.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_saved_search_by_name(db: PrefectDBInterface, session: AsyncSession, name: str) -> Union[orm_models.SavedSearch, None]
```

Reads a SavedSearch by name.

**Args:**

* `session`: A database session
* `name`: a SavedSearch name

**Returns:**

* orm\_models.SavedSearch: the SavedSearch

### `read_saved_searches` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/saved_searches.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_saved_searches(db: PrefectDBInterface, session: AsyncSession, offset: Optional[int] = None, limit: Optional[int] = None) -> Sequence[orm_models.SavedSearch]
```

Read SavedSearches.

**Args:**

* `session`: A database session
* `offset`: Query offset
* `limit`: Query limit

**Returns:**

* List\[orm\_models.SavedSearch]: SavedSearches

### `delete_saved_search` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/saved_searches.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_saved_search(db: PrefectDBInterface, session: AsyncSession, saved_search_id: UUID) -> bool
```

Delete a SavedSearch by id.

**Args:**

* `session`: A database session
* `saved_search_id`: a SavedSearch id

**Returns:**

* whether or not the SavedSearch was deleted


# task_run_states
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-task_run_states



# `prefect.server.models.task_run_states`

Functions for interacting with task run state ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `read_task_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_run_states.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_state(db: PrefectDBInterface, session: AsyncSession, task_run_state_id: UUID) -> Union[orm_models.TaskRunState, None]
```

Reads a task run state by id.

**Args:**

* `session`: A database session
* `task_run_state_id`: a task run state id

**Returns:**

* orm\_models.TaskRunState: the task state

### `read_task_run_states` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_run_states.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_states(db: PrefectDBInterface, session: AsyncSession, task_run_id: UUID) -> Sequence[orm_models.TaskRunState]
```

Reads task runs states for a task run.

**Args:**

* `session`: A database session
* `task_run_id`: the task run id

**Returns:**

* List\[orm\_models.TaskRunState]: the task run states

### `delete_task_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_run_states.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_task_run_state(db: PrefectDBInterface, session: AsyncSession, task_run_state_id: UUID) -> bool
```

Delete a task run state by id.

**Args:**

* `session`: A database session
* `task_run_state_id`: a task run state id

**Returns:**

* whether or not the task run state was deleted


# task_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-task_runs



# `prefect.server.models.task_runs`

Functions for interacting with task run ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_task_run(db: PrefectDBInterface, session: AsyncSession, task_run: schemas.core.TaskRun, orchestration_parameters: Optional[Dict[str, Any]] = None) -> orm_models.TaskRun
```

Creates a new task run.

If a task run with the same flow\_run\_id, task\_key, and dynamic\_key already exists,
the existing task run will be returned. If the provided task run has a state
attached, it will also be created.

**Args:**

* `session`: a database session
* `task_run`: a task run model

**Returns:**

* orm\_models.TaskRun: the newly-created or existing task run

### `update_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_task_run(db: PrefectDBInterface, session: AsyncSession, task_run_id: UUID, task_run: schemas.actions.TaskRunUpdate) -> bool
```

Updates a task run.

**Args:**

* `session`: a database session
* `task_run_id`: the task run id to update
* `task_run`: a task run model

**Returns:**

* whether or not matching rows were found to update

### `read_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run(db: PrefectDBInterface, session: AsyncSession, task_run_id: UUID) -> Union[orm_models.TaskRun, None]
```

Read a task run by id.

**Args:**

* `session`: a database session
* `task_run_id`: the task run id

**Returns:**

* orm\_models.TaskRun: the task run

### `read_task_run_with_flow_run_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_run_with_flow_run_name(db: PrefectDBInterface, session: AsyncSession, task_run_id: UUID) -> Union[orm_models.TaskRun, None]
```

Read a task run by id.

**Args:**

* `session`: a database session
* `task_run_id`: the task run id

**Returns:**

* orm\_models.TaskRun: the task run with the flow run name

### `read_task_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_task_runs(db: PrefectDBInterface, session: AsyncSession, flow_filter: Optional[schemas.filters.FlowFilter] = None, flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None, task_run_filter: Optional[schemas.filters.TaskRunFilter] = None, deployment_filter: Optional[schemas.filters.DeploymentFilter] = None, offset: Optional[int] = None, limit: Optional[int] = None, sort: schemas.sorting.TaskRunSort = schemas.sorting.TaskRunSort.ID_DESC) -> Sequence[orm_models.TaskRun]
```

Read task runs.

**Args:**

* `session`: a database session
* `flow_filter`: only select task runs whose flows match these filters
* `flow_run_filter`: only select task runs whose flow runs match these filters
* `task_run_filter`: only select task runs that match these filters
* `deployment_filter`: only select task runs whose deployments match these filters
* `offset`: Query offset
* `limit`: Query limit
* `sort`: Query sort

**Returns:**

* List\[orm\_models.TaskRun]: the task runs

### `count_task_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_task_runs(db: PrefectDBInterface, session: AsyncSession, flow_filter: Optional[schemas.filters.FlowFilter] = None, flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None, task_run_filter: Optional[schemas.filters.TaskRunFilter] = None, deployment_filter: Optional[schemas.filters.DeploymentFilter] = None) -> int
```

Count task runs.

**Args:**

* `session`: a database session
* `flow_filter`: only count task runs whose flows match these filters
* `flow_run_filter`: only count task runs whose flow runs match these filters
* `task_run_filter`: only count task runs that match these filters
* `deployment_filter`: only count task runs whose deployments match these filters

Returns:
int: count of task runs

### `count_task_runs_by_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L398" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_task_runs_by_state(db: PrefectDBInterface, session: AsyncSession, flow_filter: Optional[schemas.filters.FlowFilter] = None, flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None, task_run_filter: Optional[schemas.filters.TaskRunFilter] = None, deployment_filter: Optional[schemas.filters.DeploymentFilter] = None) -> schemas.states.CountByState
```

Count task runs by state.

**Args:**

* `session`: a database session
* `flow_filter`: only count task runs whose flows match these filters
* `flow_run_filter`: only count task runs whose flow runs match these filters
* `task_run_filter`: only count task runs that match these filters
* `deployment_filter`: only count task runs whose deployments match these filters

Returns:
schemas.states.CountByState: count of task runs by state

### `delete_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L445" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_task_run(db: PrefectDBInterface, session: AsyncSession, task_run_id: UUID) -> bool
```

Delete a task run by id.

**Args:**

* `session`: a database session
* `task_run_id`: the task run id to delete

**Returns:**

* whether or not the task run was deleted

### `set_task_run_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L465" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_task_run_state(session: AsyncSession, task_run_id: UUID, state: schemas.states.State, force: bool = False, task_policy: Optional[Type[TaskRunOrchestrationPolicy]] = None, orchestration_parameters: Optional[Dict[str, Any]] = None) -> OrchestrationResult
```

Creates a new orchestrated task run state.

Setting a new state on a run is the one of the principal actions that is governed by
Prefect's orchestration logic. Setting a new run state will not guarantee creation,
but instead trigger orchestration rules to govern the proposed `state` input. If
the state is considered valid, it will be written to the database. Otherwise, a
it's possible a different state, or no state, will be created. A `force` flag is
supplied to bypass a subset of orchestration logic.

**Args:**

* `session`: a database session
* `task_run_id`: the task run id
* `state`: a task run state model
* `force`: if False, orchestration rules will be applied that may alter or prevent
  the state transition. If True, orchestration rules are not applied.

**Returns:**

* OrchestrationResult object

### `with_system_labels_for_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_runs.py#L549" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_system_labels_for_task_run(session: AsyncSession, task_run: schemas.core.TaskRun) -> schemas.core.KeyValueLabels
```

Augment user supplied labels with system default labels for a task
run.


# task_workers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-task_workers



# `prefect.server.models.task_workers`

## Functions

### `observe_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
observe_worker(task_keys: List[TaskKey], worker_id: WorkerId) -> None
```

### `forget_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_worker(worker_id: WorkerId) -> None
```

### `get_workers_for_task_keys` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_workers_for_task_keys(task_keys: List[TaskKey]) -> List[TaskWorkerResponse]
```

### `get_all_workers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_all_workers() -> List[TaskWorkerResponse]
```

## Classes

### `TaskWorkerResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `InMemoryTaskWorkerTracker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `forget_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_worker(self, worker_id: WorkerId) -> None
```

#### `get_all_workers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_all_workers(self) -> List[TaskWorkerResponse]
```

#### `get_workers_for_task_keys` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_workers_for_task_keys(self, task_keys: List[TaskKey]) -> List[TaskWorkerResponse]
```

#### `observe_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
observe_worker(self, task_keys: List[TaskKey], worker_id: WorkerId) -> None
```

#### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/task_workers.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(self) -> None
```

Testing utility to reset the state of the task worker tracker


# variables
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-variables



# `prefect.server.models.variables`

## Functions

### `create_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_variable(db: PrefectDBInterface, session: AsyncSession, variable: VariableCreate) -> orm_models.Variable
```

Create a variable

**Args:**

* `session`: async database session
* `variable`: variable to create

**Returns:**

* orm\_models.Variable

### `read_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_variable(db: PrefectDBInterface, session: AsyncSession, variable_id: UUID) -> Optional[orm_models.Variable]
```

Reads a variable by id.

### `read_variable_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_variable_by_name(db: PrefectDBInterface, session: AsyncSession, name: str) -> Optional[orm_models.Variable]
```

Reads a variable by name.

### `read_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_variables(db: PrefectDBInterface, session: AsyncSession, variable_filter: Optional[filters.VariableFilter] = None, sort: sorting.VariableSort = sorting.VariableSort.NAME_ASC, offset: Optional[int] = None, limit: Optional[int] = None) -> Sequence[orm_models.Variable]
```

Read variables, applying filers.

### `count_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_variables(db: PrefectDBInterface, session: AsyncSession, variable_filter: Optional[filters.VariableFilter] = None) -> int
```

Count variables, applying filters.

### `update_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_variable(db: PrefectDBInterface, session: AsyncSession, variable_id: UUID, variable: VariableUpdate) -> bool
```

Updates a variable by id.

### `update_variable_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_variable_by_name(db: PrefectDBInterface, session: AsyncSession, name: str, variable: VariableUpdate) -> bool
```

Updates a variable by name.

### `delete_variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_variable(db: PrefectDBInterface, session: AsyncSession, variable_id: UUID) -> bool
```

Delete a variable by id.

### `delete_variable_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/variables.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_variable_by_name(db: PrefectDBInterface, session: AsyncSession, name: str) -> bool
```

Delete a variable by name.


# work_queues
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-work_queues



# `prefect.server.models.work_queues`

Functions for interacting with work queue ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue: Union[schemas.core.WorkQueue, schemas.actions.WorkQueueCreate]) -> orm_models.WorkQueue
```

Inserts a WorkQueue.

If a WorkQueue with the same name exists, an error will be thrown.

**Args:**

* `session`: a database session
* `work_queue`: a WorkQueue model

**Returns:**

* orm\_models.WorkQueue: the newly-created or updated WorkQueue

### `read_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue_id: Union[UUID, PrefectUUID]) -> Optional[orm_models.WorkQueue]
```

Reads a WorkQueue by id.

**Args:**

* `session`: A database session
* `work_queue_id`: a WorkQueue id

**Returns:**

* orm\_models.WorkQueue: the WorkQueue

### `read_work_queue_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_by_name(db: PrefectDBInterface, session: AsyncSession, name: str) -> Optional[orm_models.WorkQueue]
```

Reads a WorkQueue by id.

**Args:**

* `session`: A database session
* `work_queue_id`: a WorkQueue id

**Returns:**

* orm\_models.WorkQueue: the WorkQueue

### `read_work_queues` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queues(db: PrefectDBInterface, session: AsyncSession, offset: Optional[int] = None, limit: Optional[int] = None, work_queue_filter: Optional[schemas.filters.WorkQueueFilter] = None) -> Sequence[orm_models.WorkQueue]
```

Read WorkQueues.

**Args:**

* `session`: A database session
* `offset`: Query offset
* `limit`: Query limit
* `work_queue_filter`: only select work queues matching these filters

Returns:
Sequence\[orm\_models.WorkQueue]: WorkQueues

### `is_last_polled_recent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_last_polled_recent(last_polled: Optional[DateTime]) -> bool
```

### `update_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue_id: UUID, work_queue: schemas.actions.WorkQueueUpdate, emit_status_change: Optional[Callable[[orm_models.WorkQueue], Awaitable[None]]] = None) -> bool
```

Update a WorkQueue by id.

**Args:**

* `session`: A database session
* `work_queue`: the work queue data
* `work_queue_id`: a WorkQueue id

**Returns:**

* whether or not the WorkQueue was updated

### `delete_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue_id: UUID) -> bool
```

Delete a WorkQueue by id.

**Args:**

* `session`: A database session
* `work_queue_id`: a WorkQueue id

**Returns:**

* whether or not the WorkQueue was deleted

### `get_runs_in_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_runs_in_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue_id: UUID, limit: Optional[int] = None, scheduled_before: Optional[datetime.datetime] = None) -> Tuple[orm_models.WorkQueue, Sequence[orm_models.FlowRun]]
```

Get runs from a work queue.

**Args:**

* `session`: A database session. work\_queue\_id: The work queue id.
* `scheduled_before`: Only return runs scheduled to start before this time.
* `limit`: An optional limit for the number of runs to return from the
  queue. This limit applies to the request only. It does not affect
  the work queue's concurrency limit. If `limit` exceeds the work
  queue's concurrency limit, it will be ignored.

### `ensure_work_queue_exists` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ensure_work_queue_exists(session: AsyncSession, name: str) -> orm_models.WorkQueue
```

Checks if a work queue exists and creates it if it does not.

Useful when working with deployments, agents, and flow runs that automatically create work queues.

Will also create a work pool queue in the default agent pool to facilitate migration to work pools.

### `read_work_queue_status` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L464" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_status(session: AsyncSession, work_queue_id: UUID) -> schemas.core.WorkQueueStatusDetail
```

Get work queue status by id.

**Args:**

* `session`: A database session
* `work_queue_id`: a WorkQueue id

**Returns:**

* Information about the status of the work queue.

### `record_work_queue_polls` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L511" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_work_queue_polls(db: PrefectDBInterface, session: AsyncSession, polled_work_queue_ids: Sequence[UUID], ready_work_queue_ids: Sequence[UUID]) -> None
```

Record that the given work queues were polled, and also update the given
ready\_work\_queue\_ids to READY.

### `mark_work_queues_ready` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L536" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
mark_work_queues_ready(db: PrefectDBInterface, polled_work_queue_ids: Sequence[UUID], ready_work_queue_ids: Sequence[UUID]) -> None
```

### `mark_work_queues_not_ready` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L574" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
mark_work_queues_not_ready(db: PrefectDBInterface, work_queue_ids: Iterable[UUID]) -> None
```

### `emit_work_queue_status_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/work_queues.py#L612" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_work_queue_status_event(db: PrefectDBInterface, work_queue: orm_models.WorkQueue) -> None
```


# workers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-models-workers



# `prefect.server.models.workers`

Functions for interacting with worker ORM objects.
Intended for internal use by the Prefect REST API.

## Functions

### `create_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_work_pool(db: PrefectDBInterface, session: AsyncSession, work_pool: Union[schemas.core.WorkPool, schemas.actions.WorkPoolCreate]) -> orm_models.WorkPool
```

Creates a work pool.

If a WorkPool with the same name exists, an error will be thrown.

**Args:**

* `session`: a database session
* `work_pool`: a WorkPool model

**Returns:**

* orm\_models.WorkPool: the newly-created WorkPool

### `read_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_pool(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID) -> Optional[orm_models.WorkPool]
```

Reads a WorkPool by id.

**Args:**

* `session`: A database session
* `work_pool_id`: a WorkPool id

**Returns:**

* orm\_models.WorkPool: the WorkPool

### `read_work_pool_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_pool_by_name(db: PrefectDBInterface, session: AsyncSession, work_pool_name: str) -> Optional[orm_models.WorkPool]
```

Reads a WorkPool by name.

**Args:**

* `session`: A database session
* `work_pool_name`: a WorkPool name

**Returns:**

* orm\_models.WorkPool: the WorkPool

### `read_work_pools` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_pools(db: PrefectDBInterface, session: AsyncSession, work_pool_filter: Optional[schemas.filters.WorkPoolFilter] = None, offset: Optional[int] = None, limit: Optional[int] = None) -> Sequence[orm_models.WorkPool]
```

Read worker configs.

**Args:**

* `session`: A database session
* `offset`: Query offset
* `limit`: Query limit

Returns:
List\[orm\_models.WorkPool]: worker configs

### `count_work_pools` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
count_work_pools(db: PrefectDBInterface, session: AsyncSession, work_pool_filter: Optional[schemas.filters.WorkPoolFilter] = None) -> int
```

Read worker configs.

**Args:**

* `session`: A database session
* `work_pool_filter`: filter criteria to apply to the count

Returns:
int: the count of work pools matching the criteria

### `update_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_work_pool(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID, work_pool: schemas.actions.WorkPoolUpdate, emit_status_change: Optional[Callable[[UUID, DateTime, orm_models.WorkPool, orm_models.WorkPool], Awaitable[None]]] = None) -> bool
```

Update a WorkPool by id.

**Args:**

* `session`: A database session
* `work_pool_id`: a WorkPool id
* `worker`: the work queue data
* `emit_status_change`: function to call when work pool
  status is changed

**Returns:**

* whether or not the worker was updated

### `delete_work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_work_pool(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID) -> bool
```

Delete a WorkPool by id.

**Args:**

* `session`: A database session
* `work_pool_id`: a work pool id

**Returns:**

* whether or not the WorkPool was deleted

### `get_scheduled_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_scheduled_flow_runs(db: PrefectDBInterface, session: AsyncSession, work_pool_ids: Optional[List[UUID]] = None, work_queue_ids: Optional[List[UUID]] = None, scheduled_before: Optional[datetime.datetime] = None, scheduled_after: Optional[datetime.datetime] = None, limit: Optional[int] = None, respect_queue_priorities: Optional[bool] = None) -> Sequence[schemas.responses.WorkerFlowRunResponse]
```

Get runs from queues in a specific work pool.

**Args:**

* `session`: a database session
* `work_pool_ids`: a list of work pool ids
* `work_queue_ids`: a list of work pool queue ids
* `scheduled_before`: a datetime to filter runs scheduled before
* `scheduled_after`: a datetime to filter runs scheduled after
* `respect_queue_priorities`: whether or not to respect queue priorities
* `limit`: the maximum number of runs to return
* `db`: a database interface

**Returns:**

* List\[WorkerFlowRunResponse]: the runs, as well as related work pool details

### `create_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_work_queue(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID, work_queue: schemas.actions.WorkQueueCreate) -> orm_models.WorkQueue
```

Creates a work pool queue.

**Args:**

* `session`: a database session
* `work_pool_id`: a work pool id
* `work_queue`: a WorkQueue action model

**Returns:**

* orm\_models.WorkQueue: the newly-created WorkQueue

### `bulk_update_work_queue_priorities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bulk_update_work_queue_priorities(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID, new_priorities: Dict[UUID, int]) -> None
```

This is a brute force update of all work pool queue priorities for a given work
pool.

It loads all queues fully into memory, sorts them, and flushes the update to
the orm\_models. The algorithm ensures that priorities are unique integers > 0, and
makes the minimum number of changes required to satisfy the provided
`new_priorities`. For example, if no queues currently have the provided
`new_priorities`, then they are assigned without affecting other queues. If
they are held by other queues, then those queues' priorities are
incremented as necessary.

Updating queue priorities is not a common operation (happens on the same scale as
queue modification, which is significantly less than reading from queues),
so while this implementation is slow, it may suffice and make up for that
with extreme simplicity.

### `read_work_queues` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L468" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queues(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID, work_queue_filter: Optional[schemas.filters.WorkQueueFilter] = None, offset: Optional[int] = None, limit: Optional[int] = None) -> Sequence[orm_models.WorkQueue]
```

Read all work pool queues for a work pool. Results are ordered by ascending priority.

**Args:**

* `session`: a database session
* `work_pool_id`: a work pool id
* `work_queue_filter`: Filter criteria for work pool queues
* `offset`: Query offset
* `limit`: Query limit

**Returns:**

* List\[orm\_models.WorkQueue]: the WorkQueues

### `read_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L509" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue_id: Union[UUID, PrefectUUID]) -> Optional[orm_models.WorkQueue]
```

Read a specific work pool queue.

**Args:**

* `session`: a database session
* `work_queue_id`: a work pool queue id

**Returns:**

* orm\_models.WorkQueue: the WorkQueue

### `read_work_queue_by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_work_queue_by_name(db: PrefectDBInterface, session: AsyncSession, work_pool_name: str, work_queue_name: str) -> Optional[orm_models.WorkQueue]
```

Reads a WorkQueue by name.

**Args:**

* `session`: A database session
* `work_pool_name`: a WorkPool name
* `work_queue_name`: a WorkQueue name

**Returns:**

* orm\_models.WorkQueue: the WorkQueue

### `update_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L563" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue_id: UUID, work_queue: schemas.actions.WorkQueueUpdate, emit_status_change: Optional[Callable[[orm_models.WorkQueue], Awaitable[None]]] = None, default_status: WorkQueueStatus = WorkQueueStatus.NOT_READY) -> bool
```

Update a work pool queue.

**Args:**

* `session`: a database session
* `work_queue_id`: a work pool queue ID
* `work_queue`: a WorkQueue model
* `emit_status_change`: function to call when work queue
  status is changed

**Returns:**

* whether or not the WorkQueue was updated

### `delete_work_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L647" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_work_queue(db: PrefectDBInterface, session: AsyncSession, work_queue_id: UUID) -> bool
```

Delete a work pool queue.

**Args:**

* `session`: a database session
* `work_queue_id`: a work pool queue ID

**Returns:**

* whether or not the WorkQueue was deleted

### `read_workers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L695" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_workers(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID, worker_filter: Optional[schemas.filters.WorkerFilter] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> Sequence[orm_models.Worker]
```

### `worker_heartbeat` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L724" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
worker_heartbeat(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID, worker_name: str, heartbeat_interval_seconds: Optional[int] = None) -> bool
```

Record a worker process heartbeat.

**Args:**

* `session`: a database session
* `work_pool_id`: a work pool ID
* `worker_name`: a worker name

**Returns:**

* whether or not the worker was updated

### `delete_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L774" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_worker(db: PrefectDBInterface, session: AsyncSession, work_pool_id: UUID, worker_name: str) -> bool
```

Delete a work pool's worker.

**Args:**

* `session`: a database session
* `work_pool_id`: a work pool ID
* `worker_name`: a worker name

**Returns:**

* whether or not the Worker was deleted

### `emit_work_pool_status_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/models/workers.py#L802" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_work_pool_status_event(event_id: UUID, occurred: DateTime, pre_update_work_pool: Optional[orm_models.WorkPool], work_pool: orm_models.WorkPool) -> None
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-orchestration-__init__



# `prefect.server.orchestration`

*This module is empty or contains only private/internal implementations.*


# core_policy
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-orchestration-core_policy



# `prefect.server.orchestration.core_policy`

Orchestration logic that fires on state transitions.

`CoreFlowPolicy` and `CoreTaskPolicy` contain all default orchestration rules that
Prefect enforces on a state transition.

## Classes

### `CoreFlowPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Orchestration rules that run against flow-run-state transitions in priority order.

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.FlowRun, core.FlowRunPolicy]], type[BaseOrchestrationRule[orm_models.FlowRun, core.FlowRunPolicy]]]]
```

### `CoreTaskPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Orchestration rules that run against task-run-state transitions in priority order.

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.TaskRun, core.TaskRunPolicy]], type[BaseOrchestrationRule[orm_models.TaskRun, core.TaskRunPolicy]]]]
```

### `ClientSideTaskOrchestrationPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Orchestration rules that run against task-run-state transitions in priority order,
specifically for clients doing client-side orchestration.

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.TaskRun, core.TaskRunPolicy]], type[BaseOrchestrationRule[orm_models.TaskRun, core.TaskRunPolicy]]]]
```

### `BackgroundTaskPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Orchestration rules that run against task-run-state transitions in priority order.

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[type[BaseUniversalTransform[orm_models.TaskRun, core.TaskRunPolicy]] | type[BaseOrchestrationRule[orm_models.TaskRun, core.TaskRunPolicy]]]
```

### `MinimalFlowPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L219" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.FlowRun, core.FlowRunPolicy]], type[BaseOrchestrationRule[orm_models.FlowRun, core.FlowRunPolicy]]]]
```

### `MarkLateRunsPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.FlowRun, core.FlowRunPolicy]], type[BaseOrchestrationRule[orm_models.FlowRun, core.FlowRunPolicy]]]]
```

### `MinimalTaskPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.TaskRun, core.TaskRunPolicy]], type[BaseOrchestrationRule[orm_models.TaskRun, core.TaskRunPolicy]]]]
```

### `SecureTaskConcurrencySlots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Checks relevant concurrency slots are available before entering a Running state.

This rule checks if concurrency limits have been set on the tags associated with a
TaskRun. If so, a concurrency slot will be secured against each concurrency limit
before being allowed to transition into a running state. If a concurrency limit has
been reached, the client will be instructed to delay the transition for the duration
specified by the "PREFECT\_TASK\_RUN\_TAG\_CONCURRENCY\_SLOT\_WAIT\_SECONDS" setting
before trying again. If the concurrency limit set on a tag is 0, the transition will
be aborted to prevent deadlocks.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

#### `cleanup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L417" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cleanup(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `ReleaseTaskConcurrencySlots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L454" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Releases any concurrency slots held by a run upon exiting a Running or
Cancelling state.

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L460" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `SecureFlowConcurrencySlots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L525" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enforce deployment concurrency limits.

This rule enforces concurrency limits on deployments. If a deployment has a concurrency limit,
this rule will prevent more than that number of flow runs from being submitted concurrently
based on the concurrency limit behavior configured for the deployment.

We use the PENDING state as the target transition because this allows workers to secure a slot
before provisioning dynamic infrastructure to run a flow. If a slot isn't available, the worker
won't provision infrastructure.

A lease is created for the concurrency limit. The client will be responsible for maintaining the lease.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: FlowOrchestrationContext) -> None
```

#### `cleanup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L632" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cleanup(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: FlowOrchestrationContext) -> None
```

### `CopyDeploymentConcurrencyLeaseID` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L670" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Copies the deployment concurrency lease ID to the proposed state.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L678" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `RemoveDeploymentConcurrencyLeaseForOldClientVersions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L693" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Removes a deployment concurrency lease if the client version is less than the minimum version for leasing.

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L701" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `ReleaseFlowConcurrencySlots` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Releases deployment concurrency slots held by a flow run.

This rule releases a concurrency slot for a deployment when a flow run
transitions out of the Running or Cancelling state.

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L729" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `CacheInsertion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L799" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Caches completed states with cache keys after they are validated.

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L826" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, db: PrefectDBInterface, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L807" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `CacheRetrieval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L846" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Rejects running states if a completed state has been cached.

This rule rejects transitions into a running state with a cache key if the key
has already been associated with a completed state in the cache table. The client
will be instructed to transition into the cached completed state instead.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L859" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, db: PrefectDBInterface, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `RetryFailedFlows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L896" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Rejects failed states and schedules a retry if the retry limit has not been reached.

This rule rejects transitions into a failed state if `retries` has been
set and the run count has not reached the specified limit. The client will be
instructed to transition into a scheduled state to retry flow execution.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L908" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `RetryFailedTasks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L977" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Rejects failed states and schedules a retry if the retry limit has not been reached.

This rule rejects transitions into a failed state if `retries` has been
set, the run count has not reached the specified limit, and the client
asserts it is a retriable task run. The client will be instructed to
transition into a scheduled state to retry task execution.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L990" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `EnqueueScheduledTasks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1029" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enqueues background task runs when they are scheduled

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1037" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `RenameReruns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1060" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Name the states if they have run more than once.

In the special case where the initial state is an "AwaitingRetry" scheduled state,
the proposed state will be renamed to "Retrying" instead.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1071" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.Run, core.TaskRunPolicy | core.FlowRunPolicy]) -> None
```

### `CopyScheduledTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1090" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Ensures scheduled time is copied from scheduled states to pending states.

If a new scheduled time has been proposed on the pending state, the scheduled time
on the scheduled state will be ignored.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.Run, core.TaskRunPolicy | core.FlowRunPolicy]) -> None
```

### `WaitForScheduledTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Prevents transitions to running states from happening too early.

This rule enforces that all scheduled states will only start with the machine clock
used by the Prefect REST API instance. This rule will identify transitions from scheduled
states that are too early and nullify them. Instead, no state will be written to the
database and the client will be sent an instruction to wait for `delay_seconds`
before attempting the transition again.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.Run, core.TaskRunPolicy | core.FlowRunPolicy]) -> None
```

### `CopyTaskParametersID` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Ensures a task's parameters ID is copied from Scheduled to Pending and from
Pending to Running states.

If a parameters ID has been included on the proposed state, the parameters ID
on the initial state will be ignored.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `HandlePausingFlows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Governs runs attempting to enter a Paused/Suspended state

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `HandleResumingPausedFlows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1255" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Governs runs attempting to leave a Paused state

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `UpdateFlowRunTrackerOnTasks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Tracks the flow run attempt a task run state is associated with.

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `HandleTaskTerminalStateTransitions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

We do not allow tasks to leave terminal states if:

* The task is completed and has a persisted result
* The task is going to CANCELLING / PAUSED / CRASHED

We reset the run count when a task leaves a terminal state for a non-terminal state
which resets task run retries; this is particularly relevant for flow run retries.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

#### `cleanup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cleanup(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `HandleFlowTerminalStateTransitions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1420" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

We do not allow flows to leave terminal states if:

* The flow is completed and has a persisted result
* The flow is going to CANCELLING / PAUSED / CRASHED
* The flow is going to scheduled and has no deployment

We reset the pause metadata when a flow leaves a terminal state for a non-terminal
state. This resets pause behavior during manual flow run retries.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

#### `cleanup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1489" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cleanup(self, initial_state: states.State[Any] | None, validated_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `PreventPendingTransitions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1498" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Prevents transitions to PENDING.

This rule is only used for flow runs.

This is intended to prevent race conditions during duplicate submissions of runs.
Before a run is submitted to its execution environment, it should be placed in a
PENDING state. If two workers attempt to submit the same run, one of them should
encounter a PENDING -> PENDING transition and abort orchestration of the run.

Similarly, if the execution environment starts quickly the run may be in a RUNNING
state when the second worker attempts the PENDING transition. We deny these state
changes as well to prevent duplicate submission. If a run has transitioned to a
RUNNING state a worker should not attempt to submit it again unless it has moved
into a terminal state.

CANCELLING and CANCELLED runs should not be allowed to transition to PENDING.
For re-runs of deployed runs, they should transition to SCHEDULED first.
For re-runs of ad-hoc runs, they should transition directly to RUNNING.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1528" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.Run, Union[core.FlowRunPolicy, core.TaskRunPolicy]]) -> None
```

### `EnsureOnlyScheduledFlowsMarkedLate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1551" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `PreventRunningTasksFromStoppedFlows` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Prevents running tasks from stopped flows.

A running state implies execution, but also the converse. This rule ensures that a
flow's tasks cannot be run unless the flow is also running.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1580" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `EnforceCancellingToCancelledTransition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1616" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Rejects transitions from Cancelling to any terminal state except for Cancelled.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1624" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `BypassCancellingFlowRunsWithNoInfra` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1640" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Rejects transitions from Scheduled to Cancelling, and instead sets the state to Cancelled,
if the flow run has no associated infrastructure process ID. Also Rejects transitions from
Paused to Cancelling if the Paused state's details indicates the flow run has been suspended,
exiting the flow and tearing down infra.

The `Cancelling` state is used to clean up infrastructure. If there is not infrastructure
to clean up, we can transition directly to `Cancelled`. Runs that are `Resuming` are in a
`Scheduled` state that were previously `Suspended` and do not yet have infrastructure.

Runs that are `AwaitingRetry` are a `Scheduled` state that may have associated infrastructure.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1656" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `PreventDuplicateTransitions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1684" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Prevent duplicate transitions from being made right after one another.

This rule allows for clients to set an optional transition\_id on a state. If the
run's next transition has the same transition\_id, the transition will be
rejected and the existing state will be returned.

This allows for clients to make state transition requests without worrying about
the following case:

* A client making a state transition request
* The server accepts transition and commits the transition
* The client is unable to receive the response and retries the request

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/core_policy.py#L1702" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: states.State[Any] | None, proposed_state: states.State[Any] | None, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```


# dependencies
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-orchestration-dependencies



# `prefect.server.orchestration.dependencies`

Injected orchestration dependencies

## Functions

### `provide_task_policy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provide_task_policy() -> type[TaskRunOrchestrationPolicy]
```

### `provide_flow_policy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provide_flow_policy() -> type[FlowRunOrchestrationPolicy]
```

### `provide_task_orchestration_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provide_task_orchestration_parameters() -> dict[str, Any]
```

### `provide_flow_orchestration_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
provide_flow_orchestration_parameters() -> dict[str, Any]
```

### `temporary_task_policy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_task_policy(tmp_task_policy: type[TaskRunOrchestrationPolicy])
```

### `temporary_flow_policy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_flow_policy(tmp_flow_policy: type[FlowRunOrchestrationPolicy])
```

### `temporary_task_orchestration_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_task_orchestration_parameters(tmp_orchestration_parameters: dict[str, Any])
```

### `temporary_flow_orchestration_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_flow_orchestration_parameters(tmp_orchestration_parameters: dict[str, Any])
```

## Classes

### `OrchestrationDependencies` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/dependencies.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# global_policy
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-orchestration-global_policy



# `prefect.server.orchestration.global_policy`

Bookkeeping logic that fires on every state transition.

For clarity, `GlobalFlowpolicy` and `GlobalTaskPolicy` contain all transition logic
implemented using `BaseUniversalTransform`. None of these operations modify state, and regardless of what orchestration Prefect REST API might
enforce on a transition, the global policies contain Prefect's necessary bookkeeping.
Because these transforms record information about the validated state committed to the
state database, they should be the most deeply nested contexts in orchestration loop.

## Functions

### `COMMON_GLOBAL_TRANSFORMS` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
COMMON_GLOBAL_TRANSFORMS() -> list[type[BaseUniversalTransform[orm_models.Run, Union[core.FlowRunPolicy, core.TaskRunPolicy]]]]
```

## Classes

### `GlobalFlowPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Global transforms that run against flow-run-state transitions in priority order.

These transforms are intended to run immediately before and after a state transition
is validated.

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.FlowRun, core.FlowRunPolicy]], type[BaseOrchestrationRule[orm_models.FlowRun, core.FlowRunPolicy]]]]
```

### `GlobalTaskPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Global transforms that run against task-run-state transitions in priority order.

These transforms are intended to run immediately before and after a state transition
is validated.

**Methods:**

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[Union[type[BaseUniversalTransform[orm_models.TaskRun, core.TaskRunPolicy]], type[BaseOrchestrationRule[orm_models.TaskRun, core.TaskRunPolicy]]]]
```

### `SetRunStateType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Updates the state type of a run on a state transition.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `SetRunStateName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Updates the state name of a run on a state transition.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `SetStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Records the time a run enters a running state for the first time.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `SetRunStateTimestamp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Records the time a run changes states.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `SetEndTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Records the time a run enters a terminal state.

With normal client usage, a run will not transition out of a terminal state.
However, it's possible to force these transitions manually via the API. While
leaving a terminal state, the end time will be unset.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `IncrementRunTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Records the amount of time a run spends in the running state.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L242" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `IncrementFlowRunCount` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Records the number of times a run enters a running state. For use with retries.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `RemoveResumingIndicator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Removes the indicator on a flow run that marks it as resuming.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `IncrementTaskRunCount` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Records the number of times a run enters a running state. For use with retries.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None
```

### `SetExpectedStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Estimates the time a state is expected to start running if not set.

For scheduled states, this estimate is simply the scheduled time. For other states,
this is set to the time the proposed state was created by Prefect.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `SetNextScheduledStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Records the scheduled time on a run.

When a run enters a scheduled state, `run.next_scheduled_start_time` is set to
the state's scheduled time. When leaving a scheduled state,
`run.next_scheduled_start_time` is unset.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None
```

### `UpdateSubflowParentTask` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Whenever a subflow changes state, it must update its parent task run's state.

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `UpdateSubflowStateDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Update a child subflow state's references to a corresponding tracking task run id
in the parent flow run

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L426" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```

### `UpdateStateDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L442" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Update a state's references to a corresponding flow- or task- run.

**Methods:**

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L451" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: GenericOrchestrationContext) -> None
```


# instrumentation_policies
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-orchestration-instrumentation_policies



# `prefect.server.orchestration.instrumentation_policies`

Orchestration rules related to instrumenting the orchestration engine for Prefect
Observability

## Classes

### `InstrumentFlowRunStateTransitions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/instrumentation_policies.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

When a Flow Run changes states, fire a Prefect Event for the state change

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/instrumentation_policies.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None
```


# policies
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-orchestration-policies



# `prefect.server.orchestration.policies`

Policies are collections of orchestration rules and transforms.

Prefect implements (most) orchestration with logic that governs a Prefect flow or task
changing state. Policies organize of orchestration logic both to provide an ordering
mechanism as well as provide observability into the orchestration process.

While Prefect's orchestration rules can gracefully run independently of one another, ordering can still have an impact on
the observed behavior of the system. For example, it makes no sense to secure a
concurrency slot for a run if a cached state exists. Furthermore, policies, provide a
mechanism to configure and observe exactly what logic will fire against a transition.

## Classes

### `BaseOrchestrationPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/policies.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An abstract base class used to organize orchestration rules in priority order.

Different collections of orchestration rules might be used to govern various kinds
of transitions. For example, flow-run states and task-run states might require
different orchestration logic.

**Methods:**

#### `compile_transition_rules` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/policies.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compile_transition_rules(cls, from_state: states.StateType | None = None, to_state: states.StateType | None = None) -> list[type[BaseUniversalTransform[T, RP] | BaseOrchestrationRule[T, RP]]]
```

Returns rules in policy that are valid for the specified state transition.

#### `priority` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/policies.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
priority() -> list[type[BaseUniversalTransform[T, RP] | BaseOrchestrationRule[T, RP]]]
```

A list of orchestration rules in priority order.

### `TaskRunOrchestrationPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/policies.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `FlowRunOrchestrationPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/policies.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `GenericOrchestrationPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/policies.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# rules
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-orchestration-rules



# `prefect.server.orchestration.rules`

Prefect's flow and task-run orchestration machinery.

This module contains all the core concepts necessary to implement Prefect's state
orchestration engine. These states correspond to intuitive descriptions of all the
points that a Prefect flow or task can observe executing user code and intervene, if
necessary. A detailed description of states can be found in our concept
[documentation](https://docs.prefect.io/v3/concepts/states).

Prefect's orchestration engine operates under the assumption that no governed user code
will execute without first requesting Prefect REST API validate a change in state and record
metadata about the run. With all attempts to run user code being checked against a
Prefect instance, the Prefect REST API database becomes the unambiguous source of truth for managing
the execution of complex interacting workflows. Orchestration rules can be implemented
as discrete units of logic that operate against each state transition and can be fully
observable, extensible, and customizable -- all without needing to store or parse a
single line of user code.

## Classes

### `OrchestrationContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A container for a state transition, governed by orchestration rules.

When a flow- or task- run attempts to change state, Prefect REST API has an opportunity
to decide whether this transition can proceed. All the relevant information
associated with the state transition is stored in an `OrchestrationContext`,
which is subsequently governed by nested orchestration rules implemented using
the `BaseOrchestrationRule` ABC.

`OrchestrationContext` introduces the concept of a state being `None` in the
context of an intended state transition. An initial state can be `None` if a run
is is attempting to set a state for the first time. The proposed state might be
`None` if a rule governing the transition determines that no state change
should occur at all and nothing is written to the database.

**Args:**

* `session`: a SQLAlchemy database session
* `initial_state`: the initial state of a run
* `proposed_state`: the proposed state a run is transitioning into

**Methods:**

#### `entry_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
entry_context(self) -> tuple[Optional[states.State], Optional[states.State], Self]
```

A convenience method that generates input parameters for orchestration rules.

An `OrchestrationContext` defines a state transition that is managed by
orchestration rules which can fire hooks before a transition has been committed
to the database. These hooks have a consistent interface which can be generated
with this method.

#### `exit_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exit_context(self) -> tuple[Optional[states.State], Optional[states.State], Self]
```

A convenience method that generates input parameters for orchestration rules.

An `OrchestrationContext` defines a state transition that is managed by
orchestration rules which can fire hooks after a transition has been committed
to the database. These hooks have a consistent interface which can be generated
with this method.

#### `flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run(self) -> orm_models.FlowRun | None
```

#### `initial_state_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
initial_state_type(self) -> Optional[states.StateType]
```

The state type of `self.initial_state` if it exists.

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `proposed_state_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
proposed_state_type(self) -> Optional[states.StateType]
```

The state type of `self.proposed_state` if it exists.

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `run_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_settings(self) -> RP
```

Run-level settings used to orchestrate the state transition.

#### `safe_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
safe_copy(self) -> Self
```

Creates a mostly-mutation-safe copy for use in orchestration rules.

Orchestration rules govern state transitions using information stored in
an `OrchestrationContext`. However, mutating objects stored on the context
directly can have unintended side-effects. To guard against this,
`self.safe_copy` can be used to pass information to orchestration rules
without risking mutation.

**Returns:**

* A mutation-safe copy of the `OrchestrationContext`

#### `validated_state_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validated_state_type(self) -> Optional[states.StateType]
```

The state type of `self.validated_state` if it exists.

### `FlowOrchestrationContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A container for a flow run state transition, governed by orchestration rules.

When a flow- run attempts to change state, Prefect REST API has an opportunity
to decide whether this transition can proceed. All the relevant information
associated with the state transition is stored in an `OrchestrationContext`,
which is subsequently governed by nested orchestration rules implemented using
the `BaseOrchestrationRule` ABC.

`FlowOrchestrationContext` introduces the concept of a state being `None` in the
context of an intended state transition. An initial state can be `None` if a run
is is attempting to set a state for the first time. The proposed state might be
`None` if a rule governing the transition determines that no state change
should occur at all and nothing is written to the database.

**Args:**

* `session`: a SQLAlchemy database session
* `run`: the flow run attempting to change state
* `initial_state`: the initial state of a run
* `proposed_state`: the proposed state a run is transitioning into

**Methods:**

#### `flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run(self) -> orm_models.FlowRun
```

#### `run_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_settings(self) -> core.FlowRunPolicy
```

Run-level settings used to orchestrate the state transition.

#### `safe_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
safe_copy(self) -> Self
```

Creates a mostly-mutation-safe copy for use in orchestration rules.

Orchestration rules govern state transitions using information stored in
an `OrchestrationContext`. However, mutating objects stored on the context
directly can have unintended side-effects. To guard against this,
`self.safe_copy` can be used to pass information to orchestration rules
without risking mutation.

**Returns:**

* A mutation-safe copy of `FlowOrchestrationContext`

#### `task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run(self) -> None
```

#### `validate_proposed_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L252" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_proposed_state(self, db: PrefectDBInterface)
```

Validates a proposed state by committing it to the database.

After the `FlowOrchestrationContext` is governed by orchestration rules, the
proposed state can be validated: the proposed state is added to the current
SQLAlchemy session and is flushed. `self.validated_state` set to the flushed
state. The state on the run is set to the validated state as well.

If the proposed state is `None` when this method is called, no state will be
written and `self.validated_state` will be set to the run's current state.

**Returns:**

* None

### `TaskOrchestrationContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L368" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A container for a task run state transition, governed by orchestration rules.

When a task- run attempts to change state, Prefect REST API has an opportunity
to decide whether this transition can proceed. All the relevant information
associated with the state transition is stored in an `OrchestrationContext`,
which is subsequently governed by nested orchestration rules implemented using
the `BaseOrchestrationRule` ABC.

`TaskOrchestrationContext` introduces the concept of a state being `None` in the
context of an intended state transition. An initial state can be `None` if a run
is is attempting to set a state for the first time. The proposed state might be
`None` if a rule governing the transition determines that no state change
should occur at all and nothing is written to the database.

**Args:**

* `session`: a SQLAlchemy database session
* `run`: the task run attempting to change state
* `initial_state`: the initial state of a run
* `proposed_state`: the proposed state a run is transitioning into

**Methods:**

#### `flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L525" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run(self) -> orm_models.FlowRun | None
```

#### `run_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L517" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_settings(self) -> core.TaskRunPolicy
```

Run-level settings used to orchestrate the state transition.

#### `safe_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
safe_copy(self) -> Self
```

Creates a mostly-mutation-safe copy for use in orchestration rules.

Orchestration rules govern state transitions using information stored in
an `OrchestrationContext`. However, mutating objects stored on the context
directly can have unintended side-effects. To guard against this,
`self.safe_copy` can be used to pass information to orchestration rules
without risking mutation.

**Returns:**

* A mutation-safe copy of `TaskOrchestrationContext`

#### `task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L522" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run(self) -> orm_models.TaskRun
```

#### `validate_proposed_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_proposed_state(self, db: PrefectDBInterface)
```

Validates a proposed state by committing it to the database.

After the `TaskOrchestrationContext` is governed by orchestration rules, the
proposed state can be validated: the proposed state is added to the current
SQLAlchemy session and is flushed. `self.validated_state` set to the flushed
state. The state on the run is set to the validated state as well.

If the proposed state is `None` when this method is called, no state will be
written and `self.validated_state` will be set to the run's current state.

**Returns:**

* None

### `BaseOrchestrationRule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L534" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An abstract base class used to implement a discrete piece of orchestration logic.

An `OrchestrationRule` is a stateful context manager that directly governs a state
transition. Complex orchestration is achieved by nesting multiple rules.
Each rule runs against an `OrchestrationContext` that contains the transition
details; this context is then passed to subsequent rules. The context can be
modified by hooks that fire before and after a new state is validated and committed
to the database. These hooks will fire as long as the state transition is
considered "valid" and govern a transition by either modifying the proposed state
before it is validated or by producing a side-effect.

A state transition occurs whenever a flow- or task- run changes state, prompting
Prefect REST API to decide whether or not this transition can proceed. The current state of
the run is referred to as the "initial state", and the state a run is
attempting to transition into is the "proposed state". Together, the initial state
transitioning into the proposed state is the intended transition that is governed
by these orchestration rules. After using rules to enter a runtime context, the
`OrchestrationContext` will contain a proposed state that has been governed by
each rule, and at that point can validate the proposed state and commit it to
the database. The validated state will be set on the context as
`context.validated_state`, and rules will call the `self.after_transition` hook
upon exiting the managed context.

Examples:

Create a rule:

```python
class BasicRule(BaseOrchestrationRule):
    # allowed initial state types
    FROM_STATES = [StateType.RUNNING]
    # allowed proposed state types
    TO_STATES = [StateType.COMPLETED, StateType.FAILED]

    async def before_transition(initial_state, proposed_state, ctx):
        # side effects and proposed state mutation can happen here
        ...

    async def after_transition(initial_state, validated_state, ctx):
        # operations on states that have been validated can happen here
        ...

    async def cleanup(intitial_state, validated_state, ctx):
        # reverts side effects generated by `before_transition` if necessary
        ...
```

Use a rule:

```python
intended_transition = (StateType.RUNNING, StateType.COMPLETED)
async with BasicRule(context, *intended_transition):
    # context.proposed_state has been governed by BasicRule
    ...
```

Use multiple rules:

```python
rules = [BasicRule, BasicRule]
intended_transition = (StateType.RUNNING, StateType.COMPLETED)
async with contextlib.AsyncExitStack() as stack:
    for rule in rules:
        stack.enter_async_context(rule(context, *intended_transition))

    # context.proposed_state has been governed by all rules
    ...
```

**Args:**

* `context`: A `FlowOrchestrationContext` or `TaskOrchestrationContext` that is
  passed between rules
* `from_state_type`: The state type of the initial state of a run, if this
  state type is not contained in `FROM_STATES`, no hooks will fire
* `to_state_type`: The state type of the proposed state before orchestration, if
  this state type is not contained in `TO_STATES`, no hooks will fire

**Methods:**

#### `abort_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L900" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
abort_transition(self, reason: str) -> None
```

Aborts a proposed transition before the transition is validated.

This method will abort a proposed transition, expecting no further action to
occur for this run. The proposed state is set to `None`, signaling to the
`OrchestrationContext` that no state should be written to the database. A
reason for aborting the transition is also provided. Rules that abort the
transition will not fizzle, despite the proposed state type changing.

**Args:**

* `reason`: The reason for aborting the transition

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L727" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, initial_state: Optional[states.State], validated_state: Optional[states.State], context: OrchestrationContext[T, RP]) -> None
```

Implements a hook that can fire after a state is committed to the database.

**Args:**

* `initial_state`: The initial state of a transition
* `validated_state`: The governed state that has been committed to the database
* `context`: A safe copy of the `OrchestrationContext`, with the exception of
  `context.run`, mutating this context will have no effect on the broader
  orchestration environment.

**Returns:**

* None

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L696" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, initial_state: Optional[states.State], proposed_state: Optional[states.State], context: OrchestrationContext[T, RP]) -> None
```

Implements a hook that can fire before a state is committed to the database.

This hook may produce side-effects or mutate the proposed state of a
transition using one of four methods: `self.reject_transition`,
`self.delay_transition`, `self.abort_transition`, and `self.rename_state`.

**Args:**

* `initial_state`: The initial state of a transition
* `proposed_state`: The proposed state of a transition
* `context`: A safe copy of the `OrchestrationContext`, with the exception of
  `context.run`, mutating this context will have no effect on the broader
  orchestration environment.

**Returns:**

* None

#### `cleanup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L747" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cleanup(self, initial_state: Optional[states.State], validated_state: Optional[states.State], context: OrchestrationContext[T, RP]) -> None
```

Implements a hook that can fire after a state is committed to the database.

The intended use of this method is to revert side-effects produced by
`self.before_transition` when the transition is found to be invalid on exit.
This allows multiple rules to be gracefully run in sequence, without logic that
keeps track of all other rules that might govern a transition.

**Args:**

* `initial_state`: The initial state of a transition
* `validated_state`: The governed state that has been committed to the database
* `context`: A safe copy of the `OrchestrationContext`, with the exception of
  `context.run`, mutating this context will have no effect on the broader
  orchestration environment.

**Returns:**

* None

#### `delay_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L868" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delay_transition(self, delay_seconds: int, reason: str) -> None
```

Delays a proposed transition before the transition is validated.

This method will delay a proposed transition, setting the proposed state to
`None`, signaling to the `OrchestrationContext` that no state should be
written to the database. The number of seconds a transition should be delayed is
passed to the `OrchestrationContext`. A reason for delaying the transition is
also provided. Rules that delay the transition will not fizzle, despite the
proposed state type changing.

**Args:**

* `delay_seconds`: The number of seconds the transition should be delayed
* `reason`: The reason for delaying the transition

#### `fizzled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L795" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fizzled(self) -> bool
```

Determines if a rule is fizzled and side-effects need to be reverted.

Rules are fizzled if the transitions were valid on entry (thus firing
`self.before_transition`) but are invalid upon exiting the governed context,
most likely caused by another rule mutating the transition.

**Returns:**

* True if the rule is fizzled, False otherwise.

#### `invalid` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L772" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
invalid(self) -> bool
```

Determines if a rule is invalid.

Invalid rules do nothing and no hooks fire upon entering or exiting a governed
context. Rules are invalid if the transition states types are not contained in
`self.FROM_STATES` and `self.TO_STATES`, or if the context is proposing
a transition that differs from the transition the rule was instantiated with.

**Returns:**

* True if the rules in invalid, False otherwise.

#### `invalid_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L811" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
invalid_transition(self) -> bool
```

Determines if the transition proposed by the `OrchestrationContext` is invalid.

If the `OrchestrationContext` is attempting to manage a transition with this
rule that differs from the transition the rule was instantiated with, the
transition is considered to be invalid. Depending on the context, a rule with an
invalid transition is either "invalid" or "fizzled".

**Returns:**

* True if the transition is invalid, False otherwise.

#### `reject_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L830" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reject_transition(self, state: Optional[states.State], reason: str) -> None
```

Rejects a proposed transition before the transition is validated.

This method will reject a proposed transition, mutating the proposed state to
the provided `state`. A reason for rejecting the transition is also passed on
to the `OrchestrationContext`. Rules that reject the transition will not fizzle,
despite the proposed state type changing.

**Args:**

* `state`: The new proposed state. If `None`, the current run state will be
  returned in the result instead.
* `reason`: The reason for rejecting the transition

#### `rename_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L924" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rename_state(self, state_name: str) -> None
```

Sets the "name" attribute on a proposed state.

The name of a state is an annotation intended to provide rich, human-readable
context for how a run is progressing. This method only updates the name and not
the canonical state TYPE, and will not fizzle or invalidate any other rules
that might govern this state transition.

#### `update_context_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L936" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_context_parameters(self, key: str, value: Any) -> None
```

Updates the "parameters" dictionary attribute with the specified key-value pair.

This mechanism streamlines the process of passing messages and information
between orchestration rules if necessary and is simpler and more ephemeral than
message-passing via the database or some other side-effect. This mechanism can
be used to break up large rules for ease of testing or comprehension, but note
that any rules coupled this way (or any other way) are no longer independent and
the order in which they appear in the orchestration policy priority will matter.

### `FlowRunOrchestrationRule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L951" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `TaskRunOrchestrationRule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L957" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `GenericOrchestrationRule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L963" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BaseUniversalTransform` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L969" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An abstract base class used to implement privileged bookkeeping logic.

Beyond the orchestration rules implemented with the `BaseOrchestrationRule` ABC,
Universal transforms are not stateful, and fire their before- and after- transition
hooks on every state transition unless the proposed state is `None`, indicating that
no state should be written to the database. Because there are no guardrails in place
to prevent directly mutating state or other parts of the orchestration context,
universal transforms should only be used with care.

**Args:**

* `context`: A `FlowOrchestrationContext` or `TaskOrchestrationContext` that is
  passed between transforms

**Methods:**

#### `after_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L1055" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
after_transition(self, context: OrchestrationContext[T, RP]) -> None
```

Implements a hook that can fire after a state is committed to the database.

**Args:**

* `context`: the `OrchestrationContext` that contains transition details

**Returns:**

* None

#### `before_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L1044" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
before_transition(self, context: OrchestrationContext[T, RP]) -> None
```

Implements a hook that fires before a state is committed to the database.

**Args:**

* `context`: the `OrchestrationContext` that contains transition details

**Returns:**

* None

#### `exception_in_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L1079" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exception_in_transition(self) -> bool
```

Determines if the transition has encountered an exception.

**Returns:**

* True if the transition is encountered an exception, False otherwise.

#### `nullified_transition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L1066" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
nullified_transition(self) -> bool
```

Determines if the transition has been nullified.

Transitions are nullified if the proposed state is `None`, indicating that
nothing should be written to the database.

**Returns:**

* True if the transition is nullified, False otherwise.

### `TaskRunUniversalTransform` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L1090" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `FlowRunUniversalTransform` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L1096" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `GenericUniversalTransform` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/rules.py#L1102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-__init__



# `prefect.server.schemas`

*This module is empty or contains only private/internal implementations.*


# actions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-actions



# `prefect.server.schemas.actions`

Reduced schemas for accepting API actions.

## Functions

### `validate_base_job_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L852" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_base_job_template(v: dict[str, Any]) -> dict[str, Any]
```

## Classes

### `ActionBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a flow.

### `FlowUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a flow.

### `DeploymentScheduleCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `validate_max_scheduled_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_max_scheduled_runs(cls, v: PositiveInteger | None) -> PositiveInteger | None
```

### `DeploymentScheduleUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `validate_max_scheduled_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_max_scheduled_runs(cls, v: PositiveInteger | None) -> PositiveInteger | None
```

### `DeploymentCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a deployment.

**Methods:**

#### `check_valid_configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_valid_configuration(self, base_job_template: dict[str, Any]) -> None
```

Check that the combination of base\_job\_template defaults and job\_variables
conforms to the specified schema.

NOTE: This method does not hydrate block references in default values within the
base job template to validate them. Failing to do this can cause user-facing
errors. Instead of this method, use `validate_job_variables_for_deployment`
function from `prefect_cloud.orion.api.validation`.

#### `remove_old_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_old_fields(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `DeploymentUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a deployment.

**Methods:**

#### `check_valid_configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_valid_configuration(self, base_job_template: dict[str, Any]) -> None
```

Check that the combination of base\_job\_template defaults and job\_variables
conforms to the schema specified in the base\_job\_template.

NOTE: This method does not hydrate block references in default values within the
base job template to validate them. Failing to do this can cause user-facing
errors. Instead of this method, use `validate_job_variables_for_deployment`
function from `prefect_cloud.orion.api.validation`.

#### `remove_old_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_old_fields(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `FlowRunUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a flow run.

**Methods:**

#### `set_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L399" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_name(cls, name: str) -> str
```

### `StateCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a new state.

**Methods:**

#### `default_name_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_name_from_type(self)
```

If a name is not provided, use the type

#### `default_scheduled_start_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_scheduled_start_time(self)
```

### `TaskRunCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L444" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a task run

**Methods:**

#### `set_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L516" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_name(cls, name: str) -> str
```

#### `validate_cache_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L521" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_cache_key(cls, cache_key: str | None) -> str | None
```

### `TaskRunUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L525" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a task run

**Methods:**

#### `set_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L534" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_name(cls, name: str) -> str
```

### `FlowRunCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L538" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a flow run.

**Methods:**

#### `set_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L613" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_name(cls, name: str) -> str
```

### `DeploymentFlowRunCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L617" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a flow run from a deployment.

**Methods:**

#### `set_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L672" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_name(cls, name: str) -> str
```

### `SavedSearchCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L676" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a saved search.

### `ConcurrencyLimitCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L685" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a concurrency limit.

### `ConcurrencyLimitV2Create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L694" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a v2 concurrency limit.

### `ConcurrencyLimitV2Update` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L714" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a v2 concurrency limit.

### `BlockTypeCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L725" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a block type.

### `BlockTypeUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L746" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a block type.

**Methods:**

#### `updatable_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L755" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
updatable_fields(cls) -> set[str]
```

### `BlockSchemaCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L759" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a block schema.

### `BlockDocumentCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L777" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a block document.

**Methods:**

#### `validate_name_is_present_if_not_anonymous` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L802" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_name_is_present_if_not_anonymous(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `BlockDocumentUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L808" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a block document.

### `BlockDocumentReferenceCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L820" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used to create block document reference.

**Methods:**

#### `validate_parent_and_ref_are_different` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L837" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_parent_and_ref_are_different(cls, values)
```

### `LogCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L841" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a log.

### `WorkPoolCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L883" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a work pool.

### `WorkPoolUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L912" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a work pool.

### `WorkQueueCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L928" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a work queue.

### `WorkQueueUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L957" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a work queue.

### `ArtifactCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L978" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create an artifact.

**Methods:**

#### `from_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L1018" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_result(cls, data: Any | dict[str, Any]) -> 'ArtifactCreate'
```

### `ArtifactUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L1036" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update an artifact.

### `VariableCreate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L1046" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to create a Variable.

### `VariableUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/actions.py#L1062" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Data used by the Prefect REST API to update a Variable.


# core
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-core



# `prefect.server.schemas.core`

Full schemas of Prefect REST API objects.

## Classes

### `Flow` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of flow data.

### `FlowRunPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines of how a flow run should retry.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `populate_deprecated_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
populate_deprecated_fields(cls, values: dict[str, Any]) -> dict[str, Any]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `CreatedBy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `UpdatedBy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `ConcurrencyLimitStrategy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of concurrency collision strategies.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `ConcurrencyOptions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Class for storing the concurrency config in database.

### `FlowRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of flow run data.

**Methods:**

#### `set_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_name(cls, name: str) -> str
```

### `TaskRunPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines of how a task run should retry.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `populate_deprecated_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
populate_deprecated_fields(cls, values: dict[str, Any]) -> dict[str, Any]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `validate_configured_retry_delays` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_configured_retry_delays(cls, v: int | float | list[int] | list[float] | None) -> int | float | list[int] | list[float] | None
```

#### `validate_jitter_factor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_jitter_factor(cls, v: float | None) -> float | None
```

### `RunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for classes that represent inputs to runs, which
could include, constants, parameters, task runs or flow runs.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TaskRunResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a task run result input to another task run.

### `FlowRunResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Parameter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L408" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a parameter input to a task run.

### `Constant` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L415" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents constant input value to a task run.

### `TaskRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L422" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of task run data.

**Methods:**

#### `set_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L537" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_name(cls, name: str) -> str
```

#### `validate_cache_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L542" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_cache_key(cls, cache_key: str) -> str
```

### `DeploymentSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L546" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `validate_max_scheduled_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L571" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_max_scheduled_runs(cls, v: int) -> int
```

### `VersionInfo` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L577" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Deployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L582" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of deployment data.

### `ConcurrencyLimit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L694" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a concurrency limit.

### `ConcurrencyLimitV2` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L707" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a v2 concurrency limit.

### `BlockType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L726" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block type

### `BlockSchema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L750" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block schema.

### `BlockSchemaReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L773" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block schema reference.

### `BlockDocument` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L793" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block document.

**Methods:**

#### `from_orm_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L834" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_orm_model(cls: type[Self], session: AsyncSession, orm_block_document: 'orm_models.ORMBlockDocument', include_secrets: bool = False) -> Self
```

#### `validate_name_is_present_if_not_anonymous` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L828" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_name_is_present_if_not_anonymous(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `BlockDocumentReference` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L881" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a block document reference.

**Methods:**

#### `validate_parent_and_ref_are_different` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L901" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_parent_and_ref_are_different(cls, values: dict[str, Any]) -> dict[str, Any]
```

### `Configuration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L907" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of account info.

### `SavedSearchFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L914" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A filter for a saved search model. Intended for use by the Prefect UI.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `SavedSearch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L931" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of saved search data. Represents a set of filter criteria.

### `Log` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L941" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of log data.

### `QueueFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L956" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter criteria definition for a work queue.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L969" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a work queue

### `WorkQueueHealthPolicy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1002" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `evaluate_health_status` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1018" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
evaluate_health_status(self, late_runs_count: int, last_polled: Optional[DateTime] = None) -> bool
```

Given empirical information about the state of the work queue, evaluate its health status.

**Args:**

* `late_runs`: the count of late runs for the work queue.
* `last_polled`: the last time the work queue was polled, if available.

**Returns:**

* whether or not the work queue is healthy.

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkQueueStatusDetail` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1049" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Agent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1065" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of an agent

### `WorkPoolStorageConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1083" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A representation of a work pool's storage configuration

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkPool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a work pool

**Methods:**

#### `helpful_error_for_missing_default_queue_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
helpful_error_for_missing_default_queue_id(cls, v: UUID | None) -> UUID
```

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: Type[Self], obj: Any) -> Self
```

### `Worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An ORM representation of a worker

### `Artifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `from_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_result(cls, data: Any | dict[str, Any]) -> 'Artifact'
```

#### `validate_metadata_length` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_metadata_length(cls, v: dict[str, str]) -> dict[str, str]
```

### `ArtifactCollection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `FlowRunInput` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `CsrfToken` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/core.py#L1306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# filters
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-filters



# `prefect.server.schemas.filters`

Schemas that define Prefect REST API filtering operations.

Each filter schema includes logic for transforming itself into a SQL `where` clause.

## Classes

### `Operator` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Operators for combining filter criteria.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `PrefectFilterBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base model for Prefect filters

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `PrefectOperatorFilterBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base model for Prefect filters that combines criteria with a user-provided operator

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Flow.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowFilterDeployment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by flows by deployment

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Flow.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Flow.tags`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter for flows. Only flows matching all criteria will be returned.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowRunFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L242" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.tags`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowRunFilterDeploymentId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.deployment_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowRunFilterWorkQueueName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L338" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.work_queue_name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowRunFilterStateType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L366" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.state_type`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterStateName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L387" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.state_name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L408" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.state_type` and `FlowRun.state_name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowRunFilterFlowVersion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.flow_version`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.start_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterEndTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L487" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.end_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterExpectedStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L519" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.expected_start_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterNextScheduledStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L542" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.next_scheduled_start_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilterParentFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L571" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter for subflows of a given flow run

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowRunFilterParentTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L598" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `FlowRun.parent_task_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FlowRunFilterIdempotencyKey` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L624" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by FlowRun.idempotency\_key.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `FlowRunFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L645" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter flow runs. Only flow runs matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

#### `only_filters_on_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L692" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
only_filters_on_id(self) -> bool
```

### `TaskRunFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L748" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.flow_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `TaskRunFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L773" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `TaskRunFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L789" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `TaskRunFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L819" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.tags`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `TaskRunFilterStateType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L847" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.state_type`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `TaskRunFilterStateName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L863" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.state_name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `TaskRunFilterState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L879" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.type` and `TaskRun.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `TaskRunFilterSubFlowRuns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L904" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.subflow_run`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `TaskRunFilterStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L926" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.start_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `TaskRunFilterExpectedStartTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L958" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `TaskRun.expected_start_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `TaskRunFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L981" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter task runs. Only task runs matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `DeploymentFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1034" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `DeploymentFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1055" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `DeploymentOrFlowNameFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1085" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.name` or `Flow.name` with a single input string for ilike filtering.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `DeploymentFilterPaused` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.paused`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `DeploymentFilterWorkQueueName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.work_queue_name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `DeploymentFilterConcurrencyLimit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

DEPRECATED: Prefer `Deployment.concurrency_limit_id` over `Deployment.concurrency_limit`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `DeploymentFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Deployment.tags`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `DeploymentFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter for deployments. Only deployments matching all criteria will be returned.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `DeploymentScheduleFilterActive` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1255" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `DeploymentSchedule.active`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `DeploymentScheduleFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter for deployments. Only deployments matching all criteria will be returned.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `LogFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `LogFilterLevel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1308" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.level`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `LogFilterTimestamp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1334" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.timestamp`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `LogFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1357" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.flow_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `LogFilterTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Log.task_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `LogFilterTextSearch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by text search across log content.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

#### `includes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1414" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
includes(self, log: 'Log') -> bool
```

Check if this text filter includes the given log.

### `LogFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1503" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter logs. Only logs matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `FilterSet` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1541" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A collection of filters for common objects

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `BlockTypeFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1559" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockType.name`

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockTypeFilterSlug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1581" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockType.slug`

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockTypeFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1598" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter BlockTypes

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockSchemaFilterBlockTypeId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1622" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockSchema.block_type_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockSchemaFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1638" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by BlockSchema.id

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockSchemaFilterCapabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1654" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockSchema.capabilities`

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockSchemaFilterVersion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1675" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockSchema.capabilities`

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockSchemaFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1693" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter BlockSchemas

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `BlockDocumentFilterIsAnonymous` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1726" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.is_anonymous`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockDocumentFilterBlockTypeId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1745" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.block_type_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockDocumentFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1761" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockDocumentFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1777" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `BlockDocument.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `BlockDocumentFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1803" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `WorkQueueFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1839" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkQueue.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkQueueFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1856" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkQueue.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkQueueFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1890" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter work queues. Only work queues matching all criteria will be
returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `WorkPoolFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1915" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkPool.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkPoolFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1931" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkPool.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkPoolFilterType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1947" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `WorkPool.type`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkPoolFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1963" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter work pools. Only work pools matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `WorkerFilterWorkPoolId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L1991" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Worker.worker_config_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkerFilterStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2007" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Worker.status`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkerFilterLastHeartbeatTime` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2028" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Worker.last_heartbeat_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `WorkerFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2055" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Worker.last_heartbeat_time`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `ArtifactFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2085" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactFilterKey` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.key`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.flow_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactFilterTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.task_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactFilterType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Artifact.type`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter artifacts. Only artifacts matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `ArtifactCollectionFilterLatestId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.latest_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactCollectionFilterKey` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.key`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactCollectionFilterFlowRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2291" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.flow_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactCollectionFilterTaskRunId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2307" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.task_run_id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactCollectionFilterType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `ArtifactCollection.type`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `ArtifactCollectionFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2344" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter artifact collections. Only artifact collections matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `VariableFilterId` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Variable.id`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `VariableFilterName` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2398" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Variable.name`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.

### `VariableFilterTags` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter by `Variable.tags`.

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```

### `VariableFilter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L2452" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Filter variables. Only variables matching all criteria will be returned

**Methods:**

#### `as_sql_filter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/filters.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_filter(self, db: 'PrefectDBInterface') -> sa.ColumnElement[bool]
```


# graph
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-graph



# `prefect.server.schemas.graph`

## Classes

### `GraphState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/graph.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `GraphArtifact` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/graph.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Edge` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/graph.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Node` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/graph.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `Graph` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/graph.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# internal
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-internal



# `prefect.server.schemas.internal`

Schemas for *internal* use within the Prefect server, but that would not be
appropriate for use on the API itself.

## Classes

### `InternalWorkPoolUpdate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/internal.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# responses
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-responses



# `prefect.server.schemas.responses`

Schemas for special responses from the Prefect REST API.

## Classes

### `SetStateStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumerates return statuses for setting run states.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `StateAcceptDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with an ACCEPT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateRejectDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with a REJECT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateAbortDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with an ABORT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateWaitDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Details associated with a WAIT state transition.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `HistoryResponseState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a single state's history over an interval.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `HistoryResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents a history of aggregation states over an interval

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `validate_timestamps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_timestamps(cls, values: dict) -> dict
```

### `OrchestrationResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A container for the output of state orchestration.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `WorkerFlowRunResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `FlowRunResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: Type[Self], obj: Any) -> Self
```

### `TaskRunResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `DeploymentResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L509" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: Type[Self], obj: Any) -> Self
```

### `WorkQueueResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L530" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: Type[Self], obj: Any) -> Self
```

### `WorkQueueWithStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L559" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Combines a work queue and its status details into a single object

**Methods:**

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: Type[Self], obj: Any) -> Self
```

### `WorkerResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L567" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L574" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: Type[Self], obj: Any) -> Self
```

### `GlobalConcurrencyLimitResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L604" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A response object for global concurrency limits.

### `FlowPaginationResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L623" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `FlowRunPaginationResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L631" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `TaskRunPaginationResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L639" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `DeploymentPaginationResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L647" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `SchemaValuePropertyError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L655" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `SchemaValueIndexError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L660" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `SchemaValuesValidationResponse` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/responses.py#L668" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# schedules
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-schedules



# `prefect.server.schemas.schedules`

Schedule schemas

## Classes

### `IntervalSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A schedule formed by adding `interval` increments to an `anchor_date`. If no
`anchor_date` is supplied, the current UTC time is used.  If a
timezone-naive datetime is provided for `anchor_date`, it is assumed to be
in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,
anchor dates are always stored as UTC offsets, so a `timezone` can be
provided to determine localization behaviors like DST boundary handling. If
none is provided it will be inferred from the anchor date.

NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a
DST-observing timezone, then the schedule will adjust itself appropriately.
Intervals greater than 24 hours will follow DST conventions, while intervals
of less than 24 hours will follow UTC intervals. For example, an hourly
schedule will fire every UTC hour, even across DST boundaries. When clocks
are set back, this will result in two runs that *appear* to both be
scheduled for 1am local time, even though they are an hour apart in UTC
time. For longer intervals, like a daily schedule, the interval schedule
will adjust for DST boundaries so that the clock-hour remains constant. This
means that a daily schedule that always fires at 9am will observe DST and
continue to fire at 9am in the local time zone.

**Args:**

* `interval`: an interval to schedule on.
* `anchor_date`: an anchor date to schedule increments against;
  if not provided, the current timestamp will be used.
* `timezone`: a valid timezone string.

**Methods:**

#### `get_dates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_dates(self, n: Optional[int] = None, start: Optional[datetime.datetime] = None, end: Optional[datetime.datetime] = None) -> List[DateTime]
```

Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
following the start date.

**Args:**

* `n`: The number of dates to generate
* `start`: The first returned date will be on or
  after this date. Defaults to None.  If a timezone-naive datetime is
  provided, it is assumed to be in the schedule's timezone.
* `end`: The maximum scheduled date to return. If
  a timezone-naive datetime is provided, it is assumed to be in the
  schedule's timezone.

**Returns:**

* List\[DateTime]: A list of dates

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `validate_timezone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_timezone(self)
```

### `CronSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Cron schedule

NOTE: If the timezone is a DST-observing one, then the schedule will adjust
itself appropriately. Cron's rules for DST are based on schedule times, not
intervals. This means that an hourly cron schedule will fire on every new
schedule hour, not every elapsed hour; for example, when clocks are set back
this will result in a two-hour pause as the schedule will fire *the first
time* 1am is reached and *the first time* 2am is reached, 120 minutes later.
Longer schedules, such as one that fires at 9am every morning, will
automatically adjust for DST.

**Args:**

* `cron`: a valid cron string
* `timezone`: a valid timezone string in IANA tzdata format (for example,
  America/New\_York).
* `day_or`: Control how croniter handles `day` and `day_of_week`
  entries. Defaults to True, matching cron which connects those values using
  OR. If the switch is set to False, the values are connected using AND. This
  behaves like fcron and enables you to e.g. define a job that executes each
  2nd friday of a month by setting the days of month and the weekday.

**Methods:**

#### `get_dates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_dates(self, n: Optional[int] = None, start: Optional[datetime.datetime] = None, end: Optional[datetime.datetime] = None) -> List[DateTime]
```

Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
following the start date.

**Args:**

* `n`: The number of dates to generate
* `start`: The first returned date will be on or
  after this date. Defaults to None.  If a timezone-naive datetime is
  provided, it is assumed to be in the schedule's timezone.
* `end`: The maximum scheduled date to return. If
  a timezone-naive datetime is provided, it is assumed to be in the
  schedule's timezone.

**Returns:**

* List\[DateTime]: A list of dates

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `valid_cron_string` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L344" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
valid_cron_string(cls, v: str) -> str
```

#### `validate_timezone` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L338" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_timezone(self)
```

### `RRuleSchedule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L477" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

RRule schedule, based on the iCalendar standard
([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as
implemented in `dateutils.rrule`.

RRules are appropriate for any kind of calendar-date manipulation, including
irregular intervals, repetition, exclusions, week day or day-of-month
adjustments, and more.

Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to
to the initial timezone provided. A 9am daily schedule with a daylight saving
time-aware start date will maintain a local 9am time through DST boundaries;
a 9am daily schedule with a UTC start date will maintain a 9am UTC time.

**Args:**

* `rrule`: a valid RRule string
* `timezone`: a valid timezone string

**Methods:**

#### `from_rrule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L508" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_rrule(cls, rrule: dateutil.rrule.rrule | dateutil.rrule.rruleset) -> 'RRuleSchedule'
```

#### `get_dates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L620" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_dates(self, n: Optional[int] = None, start: datetime.datetime = None, end: datetime.datetime = None) -> List[DateTime]
```

Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
following the start date.

**Args:**

* `n`: The number of dates to generate
* `start`: The first returned date will be on or
  after this date. Defaults to None.  If a timezone-naive datetime is
  provided, it is assumed to be in the schedule's timezone.
* `end`: The maximum scheduled date to return. If
  a timezone-naive datetime is provided, it is assumed to be in the
  schedule's timezone.

**Returns:**

* List\[DateTime]: A list of dates

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

#### `to_rrule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L565" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_rrule(self) -> dateutil.rrule.rrule
```

Since rrule doesn't properly serialize/deserialize timezones, we localize dates
here

#### `validate_rrule_str` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/schedules.py#L504" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_rrule_str(cls, v: str) -> str
```


# sorting
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-sorting



# `prefect.server.schemas.sorting`

Schemas for sorting Prefect REST API objects.

## Classes

### `FlowRunSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines flow run sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort flow runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `TaskRunSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines task run sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `LogSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines log sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `FlowSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines flow sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `DeploymentSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines deployment sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `ArtifactSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines artifact sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `ArtifactCollectionSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines artifact collection sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `VariableSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines variables sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `BlockDocumentSort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Defines block document sorting options.

**Methods:**

#### `as_sql_sort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/sorting.py#L217" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_sql_sort(self, db: 'PrefectDBInterface') -> Iterable[sa.ColumnElement[Any]]
```

Return an expression used to sort task runs

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`


# states
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-states



# `prefect.server.schemas.states`

State schemas.

## Functions

### `Scheduled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Scheduled(scheduled_time: Optional[DateTime] = None, cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Scheduled` states.

**Returns:**

* a Scheduled state

### `Completed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Completed(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Completed` states.

**Returns:**

* a Completed state

### `Running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Running(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Running` states.

**Returns:**

* a Running state

### `Failed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Failed(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Failed` states.

**Returns:**

* a Failed state

### `Crashed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Crashed(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Crashed` states.

**Returns:**

* a Crashed state

### `Cancelling` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Cancelling(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Cancelling` states.

**Returns:**

* a Cancelling state

### `Cancelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Cancelled(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Cancelled` states.

**Returns:**

* a Cancelled state

### `Pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L391" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Pending(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Pending` states.

**Returns:**

* a Pending state

### `Paused` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Paused(cls: type[_State] = State, timeout_seconds: Optional[int] = None, pause_expiration_time: Optional[DateTime] = None, reschedule: bool = False, pause_key: Optional[str] = None, **kwargs: Any) -> _State
```

Convenience function for creating `Paused` states.

**Returns:**

* a Paused state

### `Suspended` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Suspended(cls: type[_State] = State, timeout_seconds: Optional[int] = None, pause_expiration_time: Optional[DateTime] = None, pause_key: Optional[str] = None, **kwargs: Any) -> _State
```

Convenience function for creating `Suspended` states.

**Returns:**

* a Suspended state

### `AwaitingRetry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L457" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
AwaitingRetry(cls: type[_State] = State, scheduled_time: Optional[DateTime] = None, **kwargs: Any) -> _State
```

Convenience function for creating `AwaitingRetry` states.

**Returns:**

* an AwaitingRetry state

### `AwaitingConcurrencySlot` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L472" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
AwaitingConcurrencySlot(cls: type[_State] = State, scheduled_time: Optional[DateTime] = None, **kwargs: Any) -> _State
```

Convenience function for creating `AwaitingConcurrencySlot` states.

**Returns:**

* an AwaitingConcurrencySlot state

### `Retrying` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Retrying(cls: type[_State] = State, **kwargs: Any) -> _State
```

Convenience function for creating `Retrying` states.

**Returns:**

* a Retrying state

### `Late` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Late(cls: type[_State] = State, scheduled_time: Optional[DateTime] = None, **kwargs: Any) -> _State
```

Convenience function for creating `Late` states.

**Returns:**

* a Late state

## Classes

### `StateType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of state types.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `CountByState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `check_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_key(cls, value: Optional[Any], info: ValidationInfo) -> Optional[Any]
```

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateDetails` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `StateBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `orm_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orm_dict(self, *args: Any, **kwargs: Any) -> dict[str, Any]
```

This method is used as a convenience method for constructing fixtues by first
building a `State` schema object and converting it into an ORM-compatible
format. Because the `data` field is not writable on ORM states, this method
omits the `data` field entirely for the purposes of constructing an ORM model.
If state data is required, an artifact must be created separately.

### `State` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Represents the state of a run.

**Methods:**

#### `default_name_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_name_from_type(self) -> Self
```

If a name is not provided, use the type

#### `default_scheduled_start_time` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_scheduled_start_time(self) -> Self
```

#### `fresh_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fresh_copy(self, **kwargs: Any) -> Self
```

Return a fresh copy of the state with a new ID.

#### `from_orm_without_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_orm_without_result(cls, orm_state: Union['ORMFlowRunState', 'ORMTaskRunState'], with_data: Optional[Any] = None) -> Self
```

During orchestration, ORM states can be instantiated prior to inserting results
into the artifact table and the `data` field will not be eagerly loaded. In
these cases, sqlalchemy will attempt to lazily load the the relationship, which
will fail when called within a synchronous pydantic method.

This method will construct a `State` object from an ORM model without a loaded
artifact and attach data passed using the `with_data` argument to the `data`
field.

#### `is_cancelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_cancelled(self) -> bool
```

#### `is_cancelling` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_cancelling(self) -> bool
```

#### `is_completed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_completed(self) -> bool
```

#### `is_crashed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_crashed(self) -> bool
```

#### `is_failed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_failed(self) -> bool
```

#### `is_final` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_final(self) -> bool
```

#### `is_paused` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_paused(self) -> bool
```

#### `is_pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_pending(self) -> bool
```

#### `is_running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_running(self) -> bool
```

#### `is_scheduled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_scheduled(self) -> bool
```

#### `orm_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orm_dict(self, *args: Any, **kwargs: Any) -> dict[str, Any]
```

This method is used as a convenience method for constructing fixtues by first
building a `State` schema object and converting it into an ORM-compatible
format. Because the `data` field is not writable on ORM states, this method
omits the `data` field entirely for the purposes of constructing an ORM model.
If state data is required, an artifact must be created separately.

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: Literal[True] = ...) -> Any
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: Literal[False] = False) -> Union[Any, Exception]
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: bool = ...) -> Union[Any, Exception]
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L242" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: bool = True) -> Union[Any, Exception]
```

#### `to_state_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/states.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_state_create(self) -> 'StateCreate'
```


# statuses
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-statuses



# `prefect.server.schemas.statuses`

## Classes

### `WorkPoolStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/statuses.py#L4" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of work pool statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

#### `in_kebab_case` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/statuses.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
in_kebab_case(self) -> str
```

### `WorkerStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/statuses.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of worker statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `DeploymentStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/statuses.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of deployment statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

#### `in_kebab_case` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/statuses.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
in_kebab_case(self) -> str
```

### `WorkQueueStatus` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/statuses.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enumeration of work queue statuses.

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

#### `in_kebab_case` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/statuses.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
in_kebab_case(self) -> str
```


# ui
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-schemas-ui



# `prefect.server.schemas.ui`

Schemas for UI endpoints.

## Classes

### `UITaskRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/schemas/ui.py#L8" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A task run with additional details for display in the UI.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-__init__



# `prefect.server.services`

*This module is empty or contains only private/internal implementations.*


# base
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-base



# `prefect.server.services.base`

## Functions

### `run_multiple_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_multiple_services(loop_services: List[LoopService]) -> NoReturn
```

Only one signal handler can be active at a time, so this function takes a list
of loop services and runs all of them with a global signal handler.

## Classes

### `Service` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service

### `RunInEphemeralServers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A marker class for services that should run even when running an ephemeral server

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service

### `RunInWebservers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A marker class for services that should run when running a webserver

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service

### `LoopService` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Loop services are relatively lightweight maintenance routines that need to run
periodically.

This class makes it straightforward to design and integrate them. Users only need to
define the `run_once` coroutine to describe the behavior of the service on each
loop.

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: int) -> None
```

Run the service `loops` time.

**Args:**

* `loops`: the number of loops to run before exiting.

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: int | None = None) -> None | NoReturn
```

Run the service `loops` time. Pass loops=None to run forever.

**Args:**

* `loops`: the number of loops to run before exiting.

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service


# cancellation_cleanup
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-cancellation_cleanup



# `prefect.server.services.cancellation_cleanup`

The CancellationCleanup service. Responsible for cancelling tasks and subflows that haven't finished.

## Classes

### `CancellationCleanup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/cancellation_cleanup.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Cancels tasks and subflows of flow runs that have been cancelled

**Methods:**

#### `clean_up_cancelled_flow_run_task_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/cancellation_cleanup.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clean_up_cancelled_flow_run_task_runs(self, db: PrefectDBInterface) -> None
```

#### `clean_up_cancelled_subflow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/cancellation_cleanup.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clean_up_cancelled_subflow_runs(self, db: PrefectDBInterface) -> None
```

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/cancellation_cleanup.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self, db: PrefectDBInterface) -> None
```

* cancels active tasks belonging to recently cancelled flow runs
* cancels any active subflow that belongs to a cancelled flow

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/cancellation_cleanup.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.


# foreman
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-foreman



# `prefect.server.services.foreman`

Foreman is a loop service designed to monitor workers.

## Classes

### `Foreman` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/foreman.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Monitors the status of workers and their associated work pools

**Methods:**

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/foreman.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self, db: PrefectDBInterface) -> None
```

Iterate over workers current marked as online. Mark workers as offline
if they have an old last\_heartbeat\_time. Marks work pools as not ready
if they do not have any online workers and are currently marked as ready.
Mark deployments as not ready if they have a last\_polled time that is
older than the configured deployment last polled timeout.

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/foreman.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.


# late_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-late_runs



# `prefect.server.services.late_runs`

The MarkLateRuns service. Responsible for putting flow runs in a Late state if they are not started on time.
The threshold for a late run can be configured by changing `PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS`.

## Classes

### `MarkLateRuns` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/late_runs.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Finds flow runs that are later than their scheduled start time

A flow run is defined as "late" if has not scheduled within a certain amount
of time after its scheduled start time. The exact amount is configurable in
Prefect REST API Settings.

**Methods:**

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/late_runs.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self, db: PrefectDBInterface) -> None
```

Mark flow runs as late by:

* Querying for flow runs in a scheduled state that are Scheduled to start in the past
* For any runs past the "late" threshold, setting the flow run state to a new `Late` state

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/late_runs.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.


# pause_expirations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-pause_expirations



# `prefect.server.services.pause_expirations`

The FailExpiredPauses service. Responsible for putting Paused flow runs in a Failed state if they are not resumed on time.

## Classes

### `FailExpiredPauses` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/pause_expirations.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Fails flow runs that have been paused and never resumed

**Methods:**

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/pause_expirations.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self, db: PrefectDBInterface) -> None
```

Mark flow runs as failed by:

* Querying for flow runs in a Paused state that have timed out
* For any runs past the "expiration" threshold, setting the flow run state to a
  new `Failed` state

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/pause_expirations.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.


# repossessor
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-repossessor



# `prefect.server.services.repossessor`

## Classes

### `Repossessor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/repossessor.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Handles the reconciliation of expired leases; no tow truck dependency.

**Methods:**

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/repossessor.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/repossessor.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.


# scheduler
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-scheduler



# `prefect.server.services.scheduler`

The Scheduler service.

## Classes

### `TryAgain` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Internal control-flow exception used to retry the Scheduler's main loop

### `Scheduler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Schedules flow runs from deployments.

**Methods:**

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self, db: PrefectDBInterface) -> None
```

Schedule flow runs by:

* Querying for deployments with active schedules
* Generating the next set of flow runs based on each deployments schedule
* Inserting all scheduled flow runs into the database

All inserted flow runs are committed to the database at the termination of the
loop.

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.

### `RecentDeploymentsScheduler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Schedules deployments that were updated very recently

This scheduler can run on a tight loop and ensure that runs from
newly-created or updated deployments are rapidly scheduled without having to
wait for the "main" scheduler to complete its loop.

Note that scheduling is idempotent, so its ok for this scheduler to attempt
to schedule the same deployments as the main scheduler. It's purpose is to
accelerate scheduling for any deployments that users are interacting with.

**Methods:**

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self, db: PrefectDBInterface) -> None
```

Schedule flow runs by:

* Querying for deployments with active schedules
* Generating the next set of flow runs based on each deployments schedule
* Inserting all scheduled flow runs into the database

All inserted flow runs are committed to the database at the termination of the
loop.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/scheduler.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```


# task_run_recorder
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-task_run_recorder



# `prefect.server.services.task_run_recorder`

## Functions

### `task_run_from_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_from_event(event: ReceivedEvent) -> TaskRun
```

### `record_task_run_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_task_run_event(event: ReceivedEvent, depth: int = 0) -> None
```

### `record_lost_follower_task_run_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_lost_follower_task_run_events() -> None
```

### `periodically_process_followers` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
periodically_process_followers(periodic_granularity: timedelta) -> NoReturn
```

Periodically process followers that are waiting on a leader event that never arrived

### `consumer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
consumer() -> AsyncGenerator[MessageHandler, None]
```

## Classes

### `TaskRunRecorder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Constructs task runs and states from client-emitted events

**Methods:**

#### `all_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_services(cls) -> Sequence[type[Self]]
```

Get list of all service classes

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

Whether the service is enabled

#### `enabled_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled_services(cls) -> list[type[Self]]
```

Get list of enabled service classes

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_services` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_services(cls) -> NoReturn
```

Run enabled services until cancelled.

#### `running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
running(cls) -> AsyncGenerator[None, None]
```

A context manager that runs enabled services on entry and stops them on
exit.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

The Prefect setting that controls whether the service is enabled

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> NoReturn
```

Start running the service, which may run indefinitely

#### `started_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
started_event(self) -> asyncio.Event
```

#### `started_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
started_event(self, value: asyncio.Event) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/task_run_recorder.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the service


# telemetry
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-services-telemetry



# `prefect.server.services.telemetry`

The Telemetry service.

## Classes

### `Telemetry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/telemetry.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Sends anonymous data to Prefect to help us improve

It can be toggled off with the PREFECT\_SERVER\_ANALYTICS\_ENABLED setting.

**Methods:**

#### `enabled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/telemetry.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(cls) -> bool
```

#### `environment_variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/telemetry.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
environment_variable_name(cls) -> str
```

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/telemetry.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Sends a heartbeat to the sens-o-matic

#### `run_once` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_once(self) -> None
```

Represents one loop of the service.

Subclasses must override this method.

To actually run the service once, call `LoopService().start(loops=1)`
instead of `LoopService().run_once()`, because this method will not invoke setup
and teardown methods properly.

#### `service_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/telemetry.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
service_settings(cls) -> ServicesBaseSetting
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, loops: None = None) -> NoReturn
```

Run the service indefinitely.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/base.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self, block: bool = True) -> None
```

Gracefully stops a running LoopService and optionally blocks until the
service stops.

**Args:**

* `block`: if True, blocks until the service is
  finished running. Otherwise it requests a stop and returns but
  the service may still be running a final loop.


# task_queue
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-task_queue



# `prefect.server.task_queue`

Implements an in-memory task queue for delivering background task runs to TaskWorkers.

## Classes

### `TaskQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `configure_task_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
configure_task_key(cls, task_key: str, scheduled_size: Optional[int] = None, retry_size: Optional[int] = None) -> None
```

#### `enqueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enqueue(cls, task_run: schemas.core.TaskRun) -> None
```

#### `for_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
for_key(cls, task_key: str) -> Self
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self) -> schemas.core.TaskRun
```

#### `get_nowait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_nowait(self) -> schemas.core.TaskRun
```

#### `put` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
put(self, task_run: schemas.core.TaskRun) -> None
```

#### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(cls) -> None
```

A unit testing utility to reset the state of the task queues subsystem

#### `retry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
retry(self, task_run: schemas.core.TaskRun) -> None
```

### `MultiQueue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A queue that can pull tasks from from any of a number of task queues

**Methods:**

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/task_queue.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self) -> schemas.core.TaskRun
```

Gets the next task\_run from any of the given queues


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-__init__



# `prefect.server.utilities`

*This module is empty or contains only private/internal implementations.*


# database
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-database



# `prefect.server.utilities.database`

Utilities for interacting with Prefect REST API database and ORM layer.

Prefect supports both SQLite and Postgres. Many of these utilities
allow the Prefect REST API to seamlessly switch between the two.

## Functions

### `db_injector` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
db_injector(func: Union[_DBMethod[T, P, R], _DBFunction[P, R]]) -> Union[_Method[T, P, R], _Function[P, R]]
```

### `generate_uuid_postgresql` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_uuid_postgresql(element: GenerateUUID, compiler: SQLCompiler, **kwargs: Any) -> str
```

Generates a random UUID in Postgres; requires the pgcrypto extension.

### `generate_uuid_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_uuid_sqlite(element: GenerateUUID, compiler: SQLCompiler, **kwargs: Any) -> str
```

Generates a random UUID in other databases (SQLite) by concatenating
bytes in a way that approximates a UUID hex representation. This is
sufficient for our purposes of having a random client-generated ID
that is compatible with a UUID spec.

### `bindparams_from_clause` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bindparams_from_clause(query: sa.ClauseElement) -> dict[str, sa.BindParameter[Any]]
```

Retrieve all non-anonymous bind parameters defined in a SQL clause

### `datetime_or_interval_add_postgresql` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L425" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
datetime_or_interval_add_postgresql(element: Union[date_add, interval_add, date_diff], compiler: SQLCompiler, **kwargs: Any) -> str
```

### `date_diff_seconds_postgresql` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
date_diff_seconds_postgresql(element: date_diff_seconds, compiler: SQLCompiler, **kwargs: Any) -> str
```

### `current_timestamp_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
current_timestamp_sqlite(element: functions.now, compiler: SQLCompiler, **kwargs: Any) -> str
```

Generates the current timestamp for SQLite

### `date_add_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L515" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
date_add_sqlite(element: date_add, compiler: SQLCompiler, **kwargs: Any) -> str
```

### `interval_add_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L523" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
interval_add_sqlite(element: interval_add, compiler: SQLCompiler, **kwargs: Any) -> str
```

### `date_diff_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L532" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
date_diff_sqlite(element: date_diff, compiler: SQLCompiler, **kwargs: Any) -> str
```

### `date_diff_seconds_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
date_diff_seconds_sqlite(element: date_diff_seconds, compiler: SQLCompiler, **kwargs: Any) -> str
```

### `sqlite_json_operators` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L690" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
sqlite_json_operators(element: sa.BinaryExpression[Any], compiler: SQLCompiler, override_operator: Optional[OperatorType] = None, **kwargs: Any) -> str
```

Intercept the PostgreSQL-only JSON / JSONB operators and translate them to SQLite

### `sqlite_greatest_as_max` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L709" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
sqlite_greatest_as_max(element: greatest[Any], compiler: SQLCompiler, **kwargs: Any) -> str
```

### `get_dialect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L727" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_dialect(obj: Union[str, Session, sa.Engine]) -> type[sa.Dialect]
```

Get the dialect of a session, engine, or connection url.

Primary use case is figuring out whether the Prefect REST API is communicating with
SQLite or Postgres.

## Classes

### `GenerateUUID` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Platform-independent UUID default generator.
Note the actual functionality for this class is specified in the
`compiles`-decorated functions below

### `Timestamp` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

TypeDecorator that ensures that timestamps have a timezone.

For SQLite, all timestamps are converted to UTC (since they are stored
as naive timestamps without timezones) and recovered as UTC.

**Methods:**

#### `load_dialect_impl` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_dialect_impl(self, dialect: sa.Dialect) -> TypeEngine[Any]
```

#### `process_bind_param` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_bind_param(self, value: Optional[datetime.datetime], dialect: sa.Dialect) -> Optional[datetime.datetime]
```

#### `process_result_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_result_value(self, value: Optional[datetime.datetime], dialect: sa.Dialect) -> Optional[datetime.datetime]
```

### `UUID` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Platform-independent UUID type.

Uses PostgreSQL's UUID type, otherwise uses
CHAR(36), storing as stringified hex values with
hyphens.

**Methods:**

#### `load_dialect_impl` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_dialect_impl(self, dialect: sa.Dialect) -> TypeEngine[Any]
```

#### `process_bind_param` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_bind_param(self, value: Optional[Union[str, uuid.UUID]], dialect: sa.Dialect) -> Optional[str]
```

#### `process_result_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_result_value(self, value: Optional[Union[str, uuid.UUID]], dialect: sa.Dialect) -> Optional[uuid.UUID]
```

### `JSON` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L224" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

JSON type that returns SQLAlchemy's dialect-specific JSON types, where
possible. Uses generic JSON otherwise.

The "base" type is postgresql.JSONB to expose useful methods prior
to SQL compilation

**Methods:**

#### `load_dialect_impl` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_dialect_impl(self, dialect: sa.Dialect) -> TypeEngine[Any]
```

#### `process_bind_param` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_bind_param(self, value: Optional[Any], dialect: sa.Dialect) -> Optional[Any]
```

Prepares the given value to be used as a JSON field in a parameter binding

### `Pydantic` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A pydantic type that converts inserted parameters to
json and converts read values to the pydantic type.

**Methods:**

#### `process_bind_param` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_bind_param(self, value: Optional[T], dialect: sa.Dialect) -> Optional[str]
```

#### `process_result_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L320" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_result_value(self, value: Optional[Any], dialect: sa.Dialect) -> Optional[T]
```

### `date_add` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Platform-independent way to add a timestamp and an interval

### `interval_add` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Platform-independent way to add two intervals.

### `date_diff` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Platform-independent difference of two timestamps. Computes d1 - d2.

### `date_diff_seconds` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L401" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Platform-independent calculation of the number of seconds between two timestamps or from 'now'

### `greatest` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/database.py#L704" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# encryption
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-encryption



# `prefect.server.utilities.encryption`

Encryption utilities

## Functions

### `encrypt_fernet` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/encryption.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
encrypt_fernet(session: AsyncSession, data: Mapping[str, Any]) -> str
```

### `decrypt_fernet` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/encryption.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
decrypt_fernet(session: AsyncSession, data: str) -> dict[str, Any]
```


# http
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-http



# `prefect.server.utilities.http`

## Functions

### `should_redact_header` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/http.py#L1" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
should_redact_header(key: str) -> bool
```

Indicates whether an HTTP header is sensitive or noisy and should be redacted
from events and templates.


# leasing
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-leasing



# `prefect.server.utilities.leasing`

## Classes

### `ResourceLease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/leasing.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `LeaseStorage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/leasing.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `create_lease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/leasing.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_lease(self, resource_ids: list[UUID], ttl: timedelta, metadata: T | None = None) -> ResourceLease[T]
```

Create a new resource lease.

**Args:**

* `resource_ids`: The IDs of the resources that the lease is associated with.
* `ttl`: How long the lease should initially be held for.
* `metadata`: Additional metadata associated with the lease.

**Returns:**

* A ResourceLease object representing the lease.

#### `read_expired_lease_ids` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/leasing.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_expired_lease_ids(self, limit: int = 100) -> list[UUID]
```

Read the IDs of expired leases.

**Args:**

* `limit`: The maximum number of expired leases to read.

**Returns:**

* A list of UUIDs representing the expired leases.

#### `read_lease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/leasing.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_lease(self, lease_id: UUID) -> ResourceLease[T] | None
```

Read a resource lease.

**Args:**

* `lease_id`: The ID of the lease to read.

**Returns:**

* A ResourceLease object representing the lease, or None if not found.

#### `renew_lease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/leasing.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
renew_lease(self, lease_id: UUID, ttl: timedelta) -> None
```

Renew a resource lease.

**Args:**

* `lease_id`: The ID of the lease to renew.
* `ttl`: The new amount of time the lease should be held for.

#### `revoke_lease` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/leasing.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
revoke_lease(self, lease_id: UUID) -> None
```

Release a resource lease by removing it from list of active leases.

**Args:**

* `lease_id`: The ID of the lease to release.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-messaging-__init__



# `prefect.server.utilities.messaging`

## Functions

### `create_cache` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_cache() -> Cache
```

Creates a new cache with the applications default settings.

**Returns:**

* a new Cache instance

### `create_publisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_publisher(topic: str, cache: Optional[Cache] = None, deduplicate_by: Optional[str] = None) -> Publisher
```

Creates a new publisher with the applications default settings.
Args:
topic: the topic to publish to
Returns:
a new Consumer instance

### `ephemeral_subscription` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ephemeral_subscription(topic: str) -> AsyncGenerator[Mapping[str, Any], Any]
```

Creates an ephemeral subscription to the given source, removing it when the context
exits.

### `create_consumer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_consumer(topic: str, **kwargs: Any) -> Consumer
```

Creates a new consumer with the applications default settings.
Args:
topic: the topic to consume from
Returns:
a new Consumer instance

## Classes

### `Message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A protocol representing a message sent to a message broker.

**Methods:**

#### `attributes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
attributes(self) -> Mapping[str, Any]
```

#### `data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
data(self) -> Union[str, bytes]
```

### `Cache` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `clear_recently_seen_messages` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_recently_seen_messages(self) -> None
```

#### `forget_duplicates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_duplicates(self, attribute: str, messages: Iterable[Message]) -> None
```

#### `without_duplicates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
without_duplicates(self, attribute: str, messages: Iterable[M]) -> list[M]
```

### `Publisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `publish_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_data(self, data: bytes, attributes: Mapping[str, str]) -> None
```

### `CapturedMessage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `CapturingPublisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `publish_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_data(self, data: bytes, attributes: Mapping[str, str]) -> None
```

#### `publish_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_data(self, data: bytes, attributes: Mapping[str, str]) -> None
```

### `StopConsumer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Exception to raise to stop a consumer.

### `Consumer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Abstract base class for consumers that receive messages from a message broker and
call a handler function for each message received.

**Methods:**

#### `run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run(self, handler: MessageHandler) -> None
```

Runs the consumer (indefinitely)

### `CacheModule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BrokerModule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/__init__.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# memory
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-messaging-memory



# `prefect.server.utilities.messaging.memory`

## Functions

### `log_metrics_periodically` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
log_metrics_periodically(interval: float = 2.0) -> None
```

### `update_metric` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_metric(topic: str, key: str, amount: int = 1) -> None
```

### `break_topic` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
break_topic()
```

### `ephemeral_subscription` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ephemeral_subscription(topic: str) -> AsyncGenerator[Mapping[str, Any], None]
```

## Classes

### `MemoryMessage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Subscription` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A subscription to a topic.

Messages are delivered to the subscription's queue and retried up to a
maximum number of times. If a message cannot be delivered after the maximum
number of retries it is moved to the dead letter queue.

The dead letter queue is a directory of JSON files containing the serialized
message.

Messages remain in the dead letter queue until they are removed manually.

**Methods:**

#### `deliver` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deliver(self, message: MemoryMessage) -> None
```

Deliver a message to the subscription's queue.

**Args:**

* `message`: The message to deliver.

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self) -> MemoryMessage
```

Get a message from the subscription's queue.

#### `retry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
retry(self, message: MemoryMessage) -> None
```

Place a message back on the retry queue.

If the message has retried more than the maximum number of times it is
moved to the dead letter queue.

**Args:**

* `message`: The message to retry.

#### `send_to_dead_letter_queue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
send_to_dead_letter_queue(self, message: MemoryMessage) -> None
```

Send a message to the dead letter queue.

The dead letter queue is a directory of JSON files containing the
serialized messages.

**Args:**

* `message`: The message to send to the dead letter queue.

### `Topic` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `by_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
by_name(cls, name: str) -> 'Topic'
```

#### `clear` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear(self) -> None
```

#### `clear_all` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_all(cls) -> None
```

#### `publish` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish(self, message: MemoryMessage) -> None
```

#### `subscribe` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
subscribe(self, **subscription_kwargs: Any) -> Subscription
```

#### `unsubscribe` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unsubscribe(self, subscription: Subscription) -> None
```

### `Cache` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `clear_recently_seen_messages` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear_recently_seen_messages(self) -> None
```

#### `forget_duplicates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forget_duplicates(self, attribute: str, messages: Iterable[M]) -> None
```

#### `without_duplicates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
without_duplicates(self, attribute: str, messages: Iterable[M]) -> list[M]
```

### `Publisher` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `publish_data` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
publish_data(self, data: bytes, attributes: Mapping[str, str]) -> None
```

### `Consumer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L326" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/messaging/memory.py#L341" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run(self, handler: MessageHandler) -> None
```


# names
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-names



# `prefect.server.utilities.names`

This module is deprecated. Use `prefect.utilities.names` instead.


# postgres_listener
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-postgres_listener



# `prefect.server.utilities.postgres_listener`

## Functions

### `get_pg_notify_connection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/postgres_listener.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_pg_notify_connection() -> Connection | None
```

Establishes and returns a raw asyncpg connection for LISTEN/NOTIFY.
Returns None if not a PostgreSQL connection URL.

### `pg_listen` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/postgres_listener.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
pg_listen(connection: Connection, channel_name: str, heartbeat_interval: float = 5.0) -> AsyncGenerator[str, None]
```

Listens to a specific Postgres channel and yields payloads.
Manages adding and removing the listener on the given connection.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-schemas-__init__



# `prefect.server.utilities.schemas`

*This module is empty or contains only private/internal implementations.*


# bases
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-schemas-bases



# `prefect.server.utilities.schemas.bases`

## Functions

### `get_class_fields_only` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_class_fields_only(model: type[BaseModel]) -> set[str]
```

Gets all the field names defined on the model class but not any parent classes.
Any fields that are on the parent but redefined on the subclass are included.

## Classes

### `PrefectDescriptorBase` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base class for descriptor objects used with PrefectBaseModel

Pydantic needs to be told about any kind of non-standard descriptor
objects used on a model, in order for these not to be treated as a field
type instead.

This base class is registered as an ignored type with PrefectBaseModel
and any classes that inherit from it will also be ignored. This allows
such descriptors to be used as properties, methods or other bound
descriptor use cases.

### `PrefectBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base pydantic.BaseModel for all Prefect schemas and pydantic models.

As the basis for most Prefect schemas, this base model ignores extra
fields that are passed to it at instantiation. Because adding new fields to
API payloads is not considered a breaking change, this ensures that any
Prefect client loading data from a server running a possibly-newer version
of Prefect will be able to process those new fields gracefully.

**Methods:**

#### `model_dump_for_orm` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump_for_orm(self) -> dict[str, Any]
```

Prefect extension to `BaseModel.model_dump`.  Generate a Python dictionary
representation of the model suitable for passing to SQLAlchemy model
constructors, `INSERT` statements, etc.  The critical difference here is that
this method will return any nested BaseModel objects as `BaseModel` instances,
rather than serialized Python dictionaries.

Accepts the standard Pydantic `model_dump` arguments, except for `mode` (which
is always "python"), `round_trip`, and `warnings`.

Usage docs: [https://docs.pydantic.dev/2.6/concepts/serialization/#modelmodel\_dump](https://docs.pydantic.dev/2.6/concepts/serialization/#modelmodel_dump)

**Args:**

* `include`: A list of fields to include in the output.
* `exclude`: A list of fields to exclude from the output.
* `by_alias`: Whether to use the field's alias in the dictionary key if defined.
* `exclude_unset`: Whether to exclude fields that have not been explicitly set.
* `exclude_defaults`: Whether to exclude fields that are set to their default
  value.
* `exclude_none`: Whether to exclude fields that have a value of `None`.

**Returns:**

* A dictionary representation of the model, suitable for passing
* to SQLAlchemy model constructors, INSERT statements, etc.

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `IDBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A PrefectBaseModel with an auto-generated UUID ID value.

The ID is reset on copy() and not included in equality comparisons.

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.

### `TimeSeriesBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A PrefectBaseModel with a time-oriented UUIDv7 ID value.  Used for models that
operate like timeseries, such as runs, states, and logs.

### `ORMBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A PrefectBaseModel with an auto-generated UUID ID value and created /
updated timestamps, intended for compatibility with our standard ORM models.

The ID, created, and updated fields are reset on copy() and not included in
equality comparisons.

### `ActionBaseModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/bases.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate_list(cls, obj: Any) -> list[Self]
```

#### `reset_fields` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/schemas/bases.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_fields(self: Self) -> Self
```

Reset the fields of the model that are in the `_reset_fields` set.

**Returns:**

* A new instance of the model with the reset fields.


# serializers
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-schemas-serializers



# `prefect.server.utilities.schemas.serializers`

## Functions

### `orjson_dumps` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/serializers.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orjson_dumps(v: Any) -> str
```

Utility for dumping a value to JSON using orjson.

orjson.dumps returns bytes, to match standard json.dumps we need to decode.

### `orjson_dumps_extra_compatible` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/schemas/serializers.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
orjson_dumps_extra_compatible(v: Any) -> str
```

Utility for dumping a value to JSON using orjson, but allows for

1. non-string keys: this is helpful for situations like pandas dataframes,
   which can result in non-string keys
2. numpy types: for serializing numpy arrays

orjson.dumps returns bytes, to match standard json.dumps we need to decode.


# server
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-server



# `prefect.server.utilities.server`

Utilities for the Prefect REST API server.

## Functions

### `method_paths_from_routes` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/server.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
method_paths_from_routes(routes: Sequence[BaseRoute]) -> set[str]
```

Generate a set of strings describing the given routes in the format: \<method> \<path>

For example, "GET /logs/"

## Classes

### `PrefectAPIRoute` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/server.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A FastAPIRoute class which attaches an async stack to requests that exits before
a response is returned.

Requests already have `request.scope['fastapi_astack']` which is an async stack for
the full scope of the request. This stack is used for managing contexts of FastAPI
dependencies. If we want to close a dependency before the request is complete
(i.e. before returning a response to the user), we need a stack with a different
scope. This extension adds this stack at `request.state.response_scoped_stack`.

**Methods:**

#### `get_route_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/server.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]
```

### `PrefectRouter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/server.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base class for Prefect REST API routers.

**Methods:**

#### `add_api_route` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/server.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_api_route(self, path: str, endpoint: Callable[..., Any], **kwargs: Any) -> None
```

Add an API route.

For routes that return content and have not specified a `response_model`,
use return type annotation to infer the response model.

For routes that return No-Content status codes, explicitly set
a `response_class` to ensure nothing is returned in the response body.


# subscriptions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-subscriptions



# `prefect.server.utilities.subscriptions`

## Functions

### `accept_prefect_socket` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/subscriptions.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
accept_prefect_socket(websocket: WebSocket) -> Optional[WebSocket]
```

### `still_connected` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/subscriptions.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
still_connected(websocket: WebSocket) -> bool
```

Checks that a client websocket still seems to be connected during a period where
the server is expected to be sending messages.


# text_search_parser
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-text_search_parser



# `prefect.server.utilities.text_search_parser`

Text search query parser

Parses text search queries according to the following syntax:

* Space-separated terms → OR logic (include)
* Prefix with `-` or `!` → Exclude term
* Prefix with `+` → Required term (AND logic, future)
* Quote phrases → Match exact phrase
* Backslash escapes → Allow quotes within phrases (")
* Case-insensitive, substring matching
* 200 character limit

## Functions

### `parse_text_search_query` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/text_search_parser.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_text_search_query(query: str) -> TextSearchQuery
```

Parse a text search query string into structured components

**Args:**

* `query`: The query string to parse

**Returns:**

* TextSearchQuery with parsed include/exclude/required terms

## Classes

### `TextSearchQuery` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/text_search_parser.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Parsed text search query structure


# user_templates
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-server-utilities-user_templates



# `prefect.server.utilities.user_templates`

Utilities to support safely rendering user-supplied templates

## Functions

### `register_user_template_filters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_user_template_filters(filters: dict[str, Any]) -> None
```

Register additional filters that will be available to user templates

### `validate_user_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_user_template(template: str) -> None
```

### `matching_types_in_templates` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
matching_types_in_templates(templates: list[str], types: set[str]) -> list[str]
```

### `maybe_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
maybe_template(possible: str) -> bool
```

### `render_user_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
render_user_template(template: str, context: dict[str, Any]) -> str
```

### `render_user_template_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
render_user_template_sync(template: str, context: dict[str, Any]) -> str
```

## Classes

### `UserTemplateEnvironment` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `TemplateSecurityError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/utilities/user_templates.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when extended validation of a template fails.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-__init__



# `prefect.settings`

Prefect settings are defined using `BaseSettings` from `pydantic_settings`. `BaseSettings` can load setting values
from system environment variables and each additionally specified `env_file`.

The recommended user-facing way to access Prefect settings at this time is to import specific setting objects directly,
like `from prefect.settings import PREFECT_API_URL; print(PREFECT_API_URL.value())`.

Importantly, we replace the `callback` mechanism for updating settings with an "after" model\_validator that updates dependent settings.
After [https://github.com/pydantic/pydantic/issues/9789](https://github.com/pydantic/pydantic/issues/9789) is resolved, we will be able to define context-aware defaults
for settings, at which point we will not need to use the "after" model\_validator.


# base
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-base



# `prefect.settings.base`

## Functions

### `build_settings_config` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_settings_config(path: tuple[str, ...] = tuple(), frozen: bool = False) -> PrefectSettingsConfigDict
```

## Classes

### `PrefectBaseSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `PrefectSettingsConfigDict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Configuration for the behavior of Prefect settings models.


# constants
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-constants



# `prefect.settings.constants`

*This module is empty or contains only private/internal implementations.*


# context
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-context



# `prefect.settings.context`

## Functions

### `get_current_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/context.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_current_settings() -> Settings
```

Returns a settings object populated with values from the current settings context
or, if no settings context is active, the environment.

### `temporary_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/context.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_settings(updates: Optional[Mapping['Setting', Any]] = None, set_defaults: Optional[Mapping['Setting', Any]] = None, restore_defaults: Optional[Iterable['Setting']] = None) -> Generator[Settings, None, None]
```

Temporarily override the current settings by entering a new profile.

See `Settings.copy_with_update` for details on different argument behavior.

Examples:

```python
from prefect.settings import PREFECT_API_URL

with temporary_settings(updates={PREFECT_API_URL: "foo"}):
   assert PREFECT_API_URL.value() == "foo"

   with temporary_settings(set_defaults={PREFECT_API_URL: "bar"}):
        assert PREFECT_API_URL.value() == "foo"

   with temporary_settings(restore_defaults={PREFECT_API_URL}):
        assert PREFECT_API_URL.value() is None

        with temporary_settings(set_defaults={PREFECT_API_URL: "bar"})
            assert PREFECT_API_URL.value() == "bar"
assert PREFECT_API_URL.value() is None
```


# legacy
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-legacy



# `prefect.settings.legacy`

## Classes

### `Setting` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/legacy.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Mimics the old Setting object for compatibility with existing code.

**Methods:**

#### `default` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/legacy.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default(self) -> Any
```

#### `is_secret` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/legacy.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_secret(self) -> bool
```

#### `name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/legacy.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
name(self) -> str
```

#### `value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/legacy.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
value(self: Self) -> Any
```

#### `value_from` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/legacy.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
value_from(self: Self, settings: Settings) -> Any
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-__init__



# `prefect.settings.models`

*This module is empty or contains only private/internal implementations.*


# api
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-api



# `prefect.settings.models.api`

## Classes

### `APISettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/api.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for interacting with the Prefect API

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# cli
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-cli



# `prefect.settings.models.cli`

## Classes

### `CLISettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/cli.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling CLI behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# client
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-client



# `prefect.settings.models.client`

## Classes

### `ClientMetricsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/client.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling metrics reporting from the client

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `ClientSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/client.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling API client behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# cloud
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-cloud



# `prefect.settings.models.cloud`

## Functions

### `default_cloud_ui_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/cloud.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
default_cloud_ui_url(settings: 'CloudSettings') -> Optional[str]
```

## Classes

### `CloudSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/cloud.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for interacting with Prefect Cloud

**Methods:**

#### `post_hoc_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/cloud.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
post_hoc_settings(self) -> Self
```

refactor on resolution of [https://github.com/pydantic/pydantic/issues/9789](https://github.com/pydantic/pydantic/issues/9789)

we should not be modifying **pydantic\_fields\_set** directly, but until we can
define dependencies between defaults in a first-class way, we need clean up
post-hoc default assignments to keep set/unset fields correct after instantiation.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# deployments
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-deployments



# `prefect.settings.models.deployments`

## Classes

### `DeploymentsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/deployments.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for configuring deployments defaults

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# experiments
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-experiments



# `prefect.settings.models.experiments`

## Classes

### `ExperimentsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/experiments.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for configuring experimental features

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# flows
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-flows



# `prefect.settings.models.flows`

## Classes

### `FlowsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/flows.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling flow behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# internal
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-internal



# `prefect.settings.models.internal`

## Classes

### `InternalSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/internal.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# logging
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-logging



# `prefect.settings.models.logging`

## Functions

### `max_log_size_smaller_than_batch_size` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/logging.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
max_log_size_smaller_than_batch_size(values: dict[str, Any]) -> dict[str, Any]
```

Validator for settings asserting the batch size and match log size are compatible

## Classes

### `LoggingToAPISettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/logging.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling logging to the API

**Methods:**

#### `emit_warnings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/logging.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_warnings(self) -> Self
```

Emits warnings for misconfiguration of logging settings.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `LoggingSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/logging.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling logging behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# results
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-results



# `prefect.settings.models.results`

## Classes

### `ResultsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/results.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling result storage behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# root
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-root



# `prefect.settings.models.root`

## Functions

### `canonical_environment_prefix` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/root.py#L375" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
canonical_environment_prefix(settings: 'Settings') -> str
```

## Classes

### `Settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/root.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for Prefect using Pydantic settings.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings)

**Methods:**

#### `copy_with_update` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/root.py#L252" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
copy_with_update(self: Self, updates: Optional[Mapping['Setting', Any]] = None, set_defaults: Optional[Mapping['Setting', Any]] = None, restore_defaults: Optional[Iterable['Setting']] = None) -> Self
```

Create a new Settings object with validation.

**Args:**

* `updates`: A mapping of settings to new values. Existing values for the
  given settings will be overridden.
* `set_defaults`: A mapping of settings to new default values. Existing values for
  the given settings will only be overridden if they were not set.
* `restore_defaults`: An iterable of settings to restore to their default values.

**Returns:**

* A new Settings object.

#### `emit_warnings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/root.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_warnings(self) -> Self
```

More post-hoc validation of settings, including warnings for misconfigurations.

#### `hash_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/root.py#L323" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hash_key(self) -> str
```

Return a hash key for the settings object.  This is needed since some
settings may be unhashable, like lists.

#### `post_hoc_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/root.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
post_hoc_settings(self) -> Self
```

Handle remaining complex default assignments that aren't yet migrated to dependent settings.

With Pydantic 2.10's dependent settings feature, we've migrated simple path-based defaults
to use default\_factory. The remaining items here require access to the full Settings instance
or have complex interdependencies that will be migrated in future PRs.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# runner
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-runner



# `prefect.settings.models.runner`

## Classes

### `RunnerServerSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/runner.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling runner server behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `RunnerSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/runner.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling runner behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-__init__



# `prefect.settings.models.server`

*This module is empty or contains only private/internal implementations.*


# api
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-api



# `prefect.settings.models.server.api`

## Classes

### `ServerAPISettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/api.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling API server behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# concurrency
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-concurrency



# `prefect.settings.models.server.concurrency`

## Classes

### `ServerConcurrencySettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/concurrency.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# database
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-database



# `prefect.settings.models.server.database`

## Functions

### `warn_on_database_password_value_without_usage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/database.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
warn_on_database_password_value_without_usage(settings: ServerDatabaseSettings) -> None
```

Validator for settings warning if the database password is set but not used.

## Classes

### `SQLAlchemyTLSSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/database.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling SQLAlchemy mTLS context when
using a PostgreSQL database.

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `SQLAlchemyConnectArgsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/database.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling SQLAlchemy connection behavior; note that these settings only take effect when
using a PostgreSQL database.

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `SQLAlchemySettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/database.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling SQLAlchemy behavior; note that these settings only take effect when
using a PostgreSQL database.

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `ServerDatabaseSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/database.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling server database behavior

**Methods:**

#### `emit_warnings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/database.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_warnings(self) -> Self
```

More post-hoc validation of settings, including warnings for misconfigurations.

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `set_deprecated_sqlalchemy_settings_on_child_model_and_warn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/database.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_deprecated_sqlalchemy_settings_on_child_model_and_warn(cls, values: dict[str, Any]) -> dict[str, Any]
```

Set deprecated settings on the child model.

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# deployments
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-deployments



# `prefect.settings.models.server.deployments`

## Classes

### `ServerDeploymentsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/deployments.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# ephemeral
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-ephemeral



# `prefect.settings.models.server.ephemeral`

## Classes

### `ServerEphemeralSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/ephemeral.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling ephemeral server behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# events
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-events



# `prefect.settings.models.server.events`

## Classes

### `ServerEventsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/events.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling behavior of the events subsystem

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# flow_run_graph
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-flow_run_graph



# `prefect.settings.models.server.flow_run_graph`

## Classes

### `ServerFlowRunGraphSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/flow_run_graph.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling behavior of the flow run graph

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# logs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-logs



# `prefect.settings.models.server.logs`

## Classes

### `ServerLogsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/logs.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling behavior of the logs subsystem

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# root
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-root



# `prefect.settings.models.server.root`

## Classes

### `ServerSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/root.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling server behavior

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# services
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-services



# `prefect.settings.models.server.services`

## Classes

### `ServicesBaseSetting` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `ServerServicesCancellationCleanupSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the cancellation cleanup service

### `ServerServicesEventPersisterSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the event persister service

### `ServerServicesEventLoggerSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the event logger service

### `ServerServicesForemanSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the foreman service

### `ServerServicesLateRunsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the late runs service

### `ServerServicesSchedulerSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the scheduler service

### `ServerServicesPauseExpirationsSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L376" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the pause expiration service

### `ServerServicesRepossessorSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L412" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the repossessor service

### `ServerServicesTaskRunRecorderSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L432" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the task run recorder service

### `ServerServicesTriggersSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L452" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling the triggers service

### `ServerServicesSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/services.py#L498" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling server services

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# tasks
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-tasks



# `prefect.settings.models.server.tasks`

## Classes

### `ServerTasksSchedulingSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/tasks.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling server-side behavior related to task scheduling

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `ServerTasksSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/tasks.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Settings for controlling server-side behavior related to tasks

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# ui
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-server-ui



# `prefect.settings.models.server.ui`

## Classes

### `ServerUISettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/server/ui.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# tasks
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-tasks



# `prefect.settings.models.tasks`

## Classes

### `TasksRunnerSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/tasks.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `TasksSchedulingSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/tasks.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `TasksSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/tasks.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# testing
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-testing



# `prefect.settings.models.testing`

## Classes

### `TestingSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/testing.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# worker
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-models-worker



# `prefect.settings.models.worker`

## Classes

### `WorkerWebserverSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/worker.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.

### `WorkerSettings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/models/worker.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `settings_customise_sources` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...]
```

Define an order for Prefect settings sources.

The order of the returned callables decides the priority of inputs; first item is the highest priority.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/base.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self, exclude_unset: bool = False, include_secrets: bool = True, include_aliases: bool = False) -> dict[str, str]
```

Convert the settings object to a dictionary of environment variables.


# profiles
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-profiles



# `prefect.settings.profiles`

## Functions

### `load_profiles` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_profiles(include_defaults: bool = True) -> ProfilesCollection
```

Load profiles from the current profile path. Optionally include profiles from the
default profile path.

### `load_current_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L341" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_current_profile() -> Profile
```

Load the current profile from the default and current profile paths.

This will *not* include settings from the current settings context. Only settings
that have been persisted to the profiles file will be saved.

### `save_profiles` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L359" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save_profiles(profiles: ProfilesCollection) -> None
```

Writes all non-default profiles to the current profiles path.

### `load_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_profile(name: str) -> Profile
```

Load a single profile by name.

### `update_current_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_current_profile(settings: dict[str | Setting, Any]) -> Profile
```

Update the persisted data for the profile currently in-use.

If the profile does not exist in the profiles file, it will be created.

Given settings will be merged with the existing settings as described in
`ProfilesCollection.update_profile`.

**Returns:**

* The new profile.

## Classes

### `Profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A user profile containing settings.

**Methods:**

#### `to_environment_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_environment_variables(self) -> dict[str, str]
```

Convert the profile settings to a dictionary of environment variables.

#### `validate_settings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_settings(self) -> None
```

Validate all settings in this profile by creating a partial Settings object
with the nested structure properly constructed using accessor paths.

### `ProfilesCollection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

"
A utility class for working with a collection of profiles.

Profiles in the collection must have unique names.

The collection may store the name of the active profile.

**Methods:**

#### `active_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
active_profile(self) -> Profile | None
```

Retrieve the active profile in this collection.

#### `add_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_profile(self, profile: Profile) -> None
```

Add a profile to the collection.

If the profile name already exists, an exception will be raised.

#### `items` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
items(self) -> list[tuple[str, Profile]]
```

#### `names` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
names(self) -> set[str]
```

Return a set of profile names in this collection.

#### `remove_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_profile(self, name: str) -> None
```

Remove a profile from the collection.

#### `set_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_active(self, name: str | None, check: bool = True) -> None
```

Set the active profile name in the collection.

A null value may be passed to indicate that this collection does not determine
the active profile.

#### `to_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_dict(self) -> dict[str, Any]
```

Convert to a dictionary suitable for writing to disk.

#### `update_profile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_profile(self, name: str, settings: dict[Setting, Any], source: Path | None = None) -> Profile
```

Add a profile to the collection or update the existing on if the name is already
present in this collection.

If updating an existing profile, the settings will be merged. Settings can
be dropped from the existing profile by setting them to `None` in the new
profile.

Returns the new profile object.

#### `without_profile_source` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/profiles.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
without_profile_source(self, path: Path | None) -> 'ProfilesCollection'
```

Remove profiles that were loaded from a given path.

Returns a new collection.


# sources
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-settings-sources



# `prefect.settings.sources`

## Classes

### `EnvFilterSettingsSource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Custom pydantic settings source to filter out specific environment variables.

All validation aliases are loaded from environment variables by default. We use
`AliasPath` to maintain the ability set fields via model initialization, but those
shouldn't be loaded from environment variables. This loader allows use to say which
environment variables should be ignored.

### `FilteredDotEnvSettingsSource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `ProfileSettingsTomlLoader` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Custom pydantic settings source to load profile settings from a toml file.

See [https://docs.pydantic.dev/latest/concepts/pydantic\_settings/#customise-settings-sources](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources)

**Methods:**

#### `get_field_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_field_value(self, field: FieldInfo, field_name: str) -> Tuple[Any, str, bool]
```

Concrete implementation to get the field value from the profile settings

### `TomlConfigSettingsSourceBase` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `get_field_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]
```

Concrete implementation to get the field value from toml data

### `PrefectTomlConfigSettingsSource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Custom pydantic settings source to load settings from a prefect.toml file

**Methods:**

#### `get_field_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]
```

Concrete implementation to get the field value from toml data

### `PyprojectTomlConfigSettingsSource` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L293" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Custom pydantic settings source to load settings from a pyproject.toml file

**Methods:**

#### `get_field_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/settings/sources.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]
```

Concrete implementation to get the field value from toml data


# states
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-states



# `prefect.states`

## Functions

### `to_state_create` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_state_create(state: State) -> 'StateCreate'
```

Convert the state to a `StateCreate` type which can be used to set the state of
a run in the API.

This method will drop this state's `data` if it is not a result type. Only
results should be sent to the API. Other data is only available locally.

### `get_state_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_state_result(state: 'State[R]', raise_on_failure: bool = True, retry_result_failure: bool = True) -> 'R'
```

Get the result from a state.

See `State.result()`

### `format_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format_exception(exc: BaseException, tb: TracebackType = None) -> str
```

### `exception_to_crashed_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exception_to_crashed_state(exc: BaseException, result_store: Optional['ResultStore'] = None) -> State
```

Takes an exception that occurs *outside* of user code and converts it to a
'Crash' exception with a 'Crashed' state.

### `exception_to_failed_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exception_to_failed_state(exc: Optional[BaseException] = None, result_store: Optional['ResultStore'] = None, write_result: bool = False, **kwargs: Any) -> State[BaseException]
```

Convenience function for creating `Failed` states from exceptions

### `return_value_to_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L304" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
return_value_to_state(retval: 'R', result_store: 'ResultStore', key: Optional[str] = None, expiration: Optional[datetime.datetime] = None, write_result: bool = False) -> 'State[R]'
```

Given a return value from a user's function, create a `State` the run should
be placed in.

* If data is returned, we create a 'COMPLETED' state with the data
* If a single, manually created state is returned, we use that state as given
  (manual creation is determined by the lack of ids)
* If an upstream state or iterable of upstream states is returned, we apply the
  aggregate rule

The aggregate rule says that given multiple states we will determine the final state
such that:

* If any states are not COMPLETED the final state is FAILED
* If all of the states are COMPLETED the final state is COMPLETED
* The states will be placed in the final state `data` attribute

Callers should resolve all futures into states before passing return values to this
function.

### `get_state_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L446" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_state_exception(state: State) -> BaseException
```

If not given a FAILED or CRASHED state, this raise a value error.

If the state result is a state, its exception will be returned.

If the state result is an iterable of states, the exception of the first failure
will be returned.

If the state result is a string, a wrapper exception will be returned with the
string as the message.

If the state result is null, a wrapper exception will be returned with the state
message attached.

If the state result is not of a known type, a `TypeError` will be returned.

When a wrapper exception is returned, the type will be:

* `FailedRun` if the state type is FAILED.
* `CrashedRun` if the state type is CRASHED.
* `CancelledRun` if the state type is CANCELLED.

### `raise_state_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L530" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_state_exception(state: State) -> None
```

Given a FAILED or CRASHED state, raise the contained exception.

### `is_state_iterable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_state_iterable(obj: Any) -> TypeGuard[Iterable[State]]
```

Check if a the given object is an iterable of states types

Supported iterables are:

* set
* list
* tuple

Other iterables will return `False` even if they contain states.

### `Scheduled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L626" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Scheduled(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Scheduled` states.

**Returns:**

* a Scheduled state

### `Completed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L646" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Completed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Completed` states.

**Returns:**

* a Completed state

### `Running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L656" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Running(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Running` states.

**Returns:**

* a Running state

### `Failed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L665" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Failed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Failed` states.

**Returns:**

* a Failed state

### `Crashed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L674" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Crashed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Crashed` states.

**Returns:**

* a Crashed state

### `Cancelling` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L683" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Cancelling(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Cancelling` states.

**Returns:**

* a Cancelling state

### `Cancelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L692" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Cancelled(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Cancelled` states.

**Returns:**

* a Cancelled state

### `Pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L701" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Pending(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Pending` states.

**Returns:**

* a Pending state

### `Paused` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L710" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Paused(cls: Type['State[R]'] = State, timeout_seconds: Optional[int] = None, pause_expiration_time: Optional[datetime.datetime] = None, reschedule: bool = False, pause_key: Optional[str] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Paused` states.

**Returns:**

* a Paused state

### `Suspended` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L748" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Suspended(cls: Type['State[R]'] = State, timeout_seconds: Optional[int] = None, pause_expiration_time: Optional[datetime.datetime] = None, pause_key: Optional[str] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Suspended` states.

**Returns:**

* a Suspended state

### `AwaitingRetry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L771" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
AwaitingRetry(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `AwaitingRetry` states.

**Returns:**

* an AwaitingRetry state

### `AwaitingConcurrencySlot` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L786" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
AwaitingConcurrencySlot(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `AwaitingConcurrencySlot` states.

**Returns:**

* an AwaitingConcurrencySlot state

### `Retrying` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L801" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Retrying(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Retrying` states.

**Returns:**

* a Retrying state

### `Late` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L810" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
Late(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Late` states.

**Returns:**

* a Late state

## Classes

### `StateGroup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L563" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `all_completed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L577" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_completed(self) -> bool
```

#### `all_final` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L592" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
all_final(self) -> bool
```

#### `any_cancelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L580" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
any_cancelled(self) -> bool
```

#### `any_failed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L583" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
any_failed(self) -> bool
```

#### `any_paused` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
any_paused(self) -> bool
```

#### `counts_message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L595" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
counts_message(self) -> str
```

#### `fail_count` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L574" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fail_count(self) -> int
```


# task_engine
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-task_engine



# `prefect.task_engine`

## Functions

### `run_task_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1486" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_task_sync(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Union[R, State, None]
```

### `run_task_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1517" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_task_async(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Union[R, State, None]
```

### `run_generator_task_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1548" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_generator_task_sync(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Generator[R, None, None]
```

### `run_generator_task_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1607" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_generator_task_async(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> AsyncGenerator[R, None]
```

### `run_task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1693" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_task(task: 'Task[P, Union[R, Coroutine[Any, Any, R]]]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Union[R, State, None, Coroutine[Any, Any, Union[R, State, None]]]
```

Runs the provided task.

**Args:**

* `task`: The task to run
* `task_run_id`: The ID of the task run; if not provided, a new task run
  will be created
* `task_run`: The task run object; if not provided, a new task run
  will be created
* `parameters`: The parameters to pass to the task
* `wait_for`: A list of futures to wait for before running the task
* `return_type`: The return type to return; either "state" or "result"
* `dependencies`: A dictionary of task run inputs to use for dependency tracking
* `context`: A dictionary containing the context to use for the task run; only
  required if the task is running on in a remote environment

**Returns:**

* The result of the task run

## Classes

### `TaskRunTimeoutError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a task run exceeds its timeout.

### `BaseTaskRunEngine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `compute_transaction_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
compute_transaction_key(self) -> Optional[str]
```

#### `handle_rollback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_rollback(self, txn: Transaction) -> None
```

#### `is_cancelled` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_cancelled(self) -> bool
```

#### `is_running` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_running(self) -> bool
```

Whether or not the engine is currently running a task.

#### `log_finished_message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
log_finished_message(self) -> None
```

#### `record_terminal_state_timing` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_terminal_state_timing(self, state: State) -> None
```

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

### `SyncTaskRunEngine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `asset_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L676" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asset_context(self)
```

#### `begin_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_run(self) -> None
```

#### `call_hooks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_hooks(self, state: Optional[State] = None) -> None
```

#### `call_task_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L877" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_task_fn(self, transaction: Transaction) -> Union[ResultRecord[Any], None, Coroutine[Any, Any, R], R]
```

Convenience method to call the task function. Returns a coroutine if the
task is async.

#### `can_retry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
can_retry(self, exc_or_state: Exception | State[R]) -> bool
```

#### `client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L319" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client(self) -> SyncPrefectClient
```

#### `handle_crash` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L622" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_crash(self, exc: BaseException) -> None
```

#### `handle_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L590" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_exception(self, exc: Exception) -> None
```

#### `handle_retry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L538" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_retry(self, exc_or_state: Exception | State[R]) -> bool
```

Handle any task run retries.

* If the task has retries left, and the retry condition is met, set the task to retrying and return True.
* If the task has a retry delay, place in AwaitingRetry state with a delayed scheduled time.
* If the task has no retries left, or the retry condition is not met, return False.

#### `handle_success` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L498" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_success(self, result: R, transaction: Transaction) -> Union[ResultRecord[R], None, Coroutine[Any, Any, R], R]
```

#### `handle_timeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L607" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_timeout(self, exc: TimeoutError) -> None
```

#### `initialize_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L694" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
initialize_run(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> Generator[Self, Any, Any]
```

Enters a client context and creates a task run if needed.

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L483" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: bool = True) -> 'Union[R, State, None]'
```

#### `run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L857" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_context(self)
```

#### `set_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L432" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state(self, state: State[R], force: bool = False) -> State[R]
```

#### `setup_run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L632" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_run_context(self, client: Optional[SyncPrefectClient] = None)
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L788" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> Generator[None, None, None]
```

#### `transaction_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L830" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
transaction_context(self) -> Generator[Transaction, None, None]
```

#### `wait_until_ready` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L768" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_until_ready(self) -> None
```

Waits until the scheduled time (if its the future), then enters Running.

### `AsyncTaskRunEngine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L894" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `asset_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asset_context(self)
```

#### `begin_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L975" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_run(self) -> None
```

#### `call_hooks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L940" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_hooks(self, state: Optional[State] = None) -> None
```

#### `call_task_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1470" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_task_fn(self, transaction: AsyncTransaction) -> Union[ResultRecord[Any], None, Coroutine[Any, Any, R], R]
```

Convenience method to call the task function. Returns a coroutine if the
task is async.

#### `can_retry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L904" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
can_retry(self, exc_or_state: Exception | State[R]) -> bool
```

#### `client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L899" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client(self) -> PrefectClient
```

#### `handle_crash` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_crash(self, exc: BaseException) -> None
```

#### `handle_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_exception(self, exc: Exception) -> None
```

#### `handle_retry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_retry(self, exc_or_state: Exception | State[R]) -> bool
```

Handle any task run retries.

* If the task has retries left, and the retry condition is met, set the task to retrying and return True.
* If the task has a retry delay, place in AwaitingRetry state with a delayed scheduled time.
* If the task has no retries left, or the retry condition is not met, return False.

#### `handle_success` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1093" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_success(self, result: R, transaction: AsyncTransaction) -> Union[ResultRecord[R], None, Coroutine[Any, Any, R], R]
```

#### `handle_timeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_timeout(self, exc: TimeoutError) -> None
```

#### `initialize_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
initialize_run(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> AsyncGenerator[Self, Any]
```

Enters a client context and creates a task run if needed.

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1078" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, raise_on_failure: bool = True) -> 'Union[R, State, None]'
```

#### `run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1450" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_context(self)
```

#### `set_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1025" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_state(self, state: State, force: bool = False) -> State
```

#### `setup_run_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_run_context(self, client: Optional[PrefectClient] = None)
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> AsyncGenerator[None, None]
```

#### `transaction_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
transaction_context(self) -> AsyncGenerator[AsyncTransaction, None]
```

#### `wait_until_ready` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_until_ready(self) -> None
```

Waits until the scheduled time (if its the future), then enters Running.


# task_runners
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-task_runners



# `prefect.task_runners`

## Classes

### `TaskRunner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Abstract base class for task runners.

A task runner is responsible for submitting tasks to the task run engine running
in an execution environment. Submitted tasks are non-blocking and return a future
object that can be used to wait for the task to complete and retrieve the result.

Task runners are context managers and should be used in a `with` block to ensure
proper cleanup of resources.

**Methods:**

#### `duplicate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
duplicate(self) -> Self
```

Return a new instance of this task runner with the same configuration.

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any | unmapped[Any] | allow_failure[Any]], wait_for: Iterable[PrefectFuture[R]] | None = None) -> PrefectFutureList[F]
```

Submit multiple tasks to the task run engine.

**Args:**

* `task`: The task to submit.
* `parameters`: The parameters to use when running the task.
* `wait_for`: A list of futures that the task depends on.

**Returns:**

* An iterable of future objects that can be used to wait for the tasks to
* complete and retrieve the results.

#### `name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
name(self) -> str
```

The name of this task runner

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> F
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[Any, R]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> F
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> F
```

### `ThreadPoolTaskRunner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A task runner that executes tasks in a separate thread pool.

**Examples:**

Use a thread pool task runner with a flow:

```python
from prefect import flow, task
from prefect.task_runners import ThreadPoolTaskRunner

@task
def some_io_bound_task(x: int) -> int:
    # making a query to a database, reading a file, etc.
    return x * 2

@flow(task_runner=ThreadPoolTaskRunner(max_workers=3)) # use at most 3 threads at a time
def my_io_bound_flow():
    futures = []
    for i in range(10):
        future = some_io_bound_task.submit(i * 100)
        futures.append(future)

    return [future.result() for future in futures]
```

Use a thread pool task runner as a context manager:

```python
from prefect.task_runners import ThreadPoolTaskRunner

@task
def some_io_bound_task(x: int) -> int:
    # making a query to a database, reading a file, etc.
    return x * 2

# Use the runner directly
with ThreadPoolTaskRunner(max_workers=2) as runner:
    future1 = runner.submit(some_io_bound_task, {"x": 1})
    future2 = runner.submit(some_io_bound_task, {"x": 2})

    result1 = future1.result()  # 2
    result2 = future2.result()  # 4
```

Configure max workers via settings:

```python
# Set via environment variable
# export PREFECT_TASK_RUNNER_THREAD_POOL_MAX_WORKERS=8

from prefect import flow
from prefect.task_runners import ThreadPoolTaskRunner

@flow(task_runner=ThreadPoolTaskRunner())  # Uses 8 workers from setting
def my_flow():
    ...
```

**Methods:**

#### `cancel_all` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cancel_all(self) -> None
```

#### `duplicate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
duplicate(self) -> 'ThreadPoolTaskRunner[R]'
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L413" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[P, CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectConcurrentFuture[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L421" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[Any, R]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectConcurrentFuture[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L428" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectConcurrentFuture[R]]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectConcurrentFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[Any, R]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectConcurrentFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L339" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectConcurrentFuture[R]
```

Submit a task to the task run engine running in a separate thread.

**Args:**

* `task`: The task to submit.
* `parameters`: The parameters to use when running the task.
* `wait_for`: A list of futures that the task depends on.

**Returns:**

* A future object that can be used to wait for the task to complete and
* retrieve the result.

### `ProcessPoolTaskRunner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L535" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A task runner that executes tasks in a separate process pool.

This task runner uses `ProcessPoolExecutor` to run tasks in separate processes,
providing true parallelism for CPU-bound tasks and process isolation. Tasks
are executed with proper context propagation and error handling.

**Examples:**

Use a process pool task runner with a flow:

```python
from prefect import flow, task
from prefect.task_runners import ProcessPoolTaskRunner

@task
def compute_heavy_task(n: int) -> int:
    # CPU-intensive computation that benefits from process isolation
    return sum(i ** 2 for i in range(n))

@flow(task_runner=ProcessPoolTaskRunner(max_workers=4))
def my_flow():
    futures = []
    for i in range(10):
        future = compute_heavy_task.submit(i * 1000)
        futures.append(future)

    return [future.result() for future in futures]
```

Use a process pool task runner as a context manager:

```python
from prefect.task_runners import ProcessPoolTaskRunner

@task
def my_task(x: int) -> int:
    return x * 2

# Use the runner directly
with ProcessPoolTaskRunner(max_workers=2) as runner:
    future1 = runner.submit(my_task, {"x": 1})
    future2 = runner.submit(my_task, {"x": 2})

    result1 = future1.result()  # 2
    result2 = future2.result()  # 4
```

Configure max workers via settings:

```python
# Set via environment variable
# export PREFECT_TASKS_RUNNER_PROCESS_POOL_MAX_WORKERS=8

from prefect import flow
from prefect.task_runners import ProcessPoolTaskRunner

@flow(task_runner=ProcessPoolTaskRunner())  # Uses 8 workers from setting
def my_flow():
    ...
```

**Methods:**

#### `cancel_all` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L748" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cancel_all(self) -> None
```

#### `duplicate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L626" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
duplicate(self) -> Self
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L725" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[P, CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectConcurrentFuture[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L733" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[Any, R]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectConcurrentFuture[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L740" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectConcurrentFuture[R]]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L630" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectConcurrentFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L639" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[Any, R]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectConcurrentFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L647" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectConcurrentFuture[R]
```

Submit a task to the task run engine running in a separate process.

**Args:**

* `task`: The task to submit.
* `parameters`: The parameters to use when running the task.
* `wait_for`: A list of futures that the task depends on.
* `dependencies`: A dictionary of dependencies for the task.

**Returns:**

* A future object that can be used to wait for the task to complete and
* retrieve the result.

### `PrefectTaskRunner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L788" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `duplicate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L792" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
duplicate(self) -> 'PrefectTaskRunner[R]'
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L851" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[P, CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectDistributedFuture[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L859" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[Any, R]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectDistributedFuture[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L866" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None) -> PrefectFutureList[PrefectDistributedFuture[R]]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L796" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectDistributedFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L805" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[Any, R]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectDistributedFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runners.py#L813" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, task: 'Task[P, R | CoroutineType[Any, Any, R]]', parameters: dict[str, Any], wait_for: Iterable[PrefectFuture[Any]] | None = None, dependencies: dict[str, set[RunInput]] | None = None) -> PrefectDistributedFuture[R]
```

Submit a task to the task run engine running in a separate thread.

**Args:**

* `task`: The task to submit.
* `parameters`: The parameters to use when running the task.
* `wait_for`: A list of futures that the task depends on.

**Returns:**

* A future object that can be used to wait for the task to complete and
* retrieve the result.


# task_runs
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-task_runs



# `prefect.task_runs`

## Classes

### `TaskRunWaiter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runs.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A service used for waiting for a task run to finish.

This service listens for task run events and provides a way to wait for a specific
task run to finish. This is useful for waiting for a task run to finish before
continuing execution.

The service is a singleton and must be started before use. The service will
automatically start when the first instance is created. A single websocket
connection is used to listen for task run events.

The service can be used to wait for a task run to finish by calling
`TaskRunWaiter.wait_for_task_run` with the task run ID to wait for. The method
will return when the task run has finished or the timeout has elapsed.

The service will automatically stop when the Python process exits or when the
global loop thread is stopped.

Example:

```python
import asyncio
from uuid import uuid4

from prefect import task
from prefect.task_engine import run_task_async
from prefect.task_runs import TaskRunWaiter


@task
async def test_task():
    await asyncio.sleep(5)
    print("Done!")


async def main():
    task_run_id = uuid4()
    asyncio.create_task(run_task_async(task=test_task, task_run_id=task_run_id))

    await TaskRunWaiter.wait_for_task_run(task_run_id)
    print("Task run finished")


if __name__ == "__main__":
    asyncio.run(main())
```

**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runs.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(cls, task_run_id: uuid.UUID, callback: Callable[[], None]) -> None
```

Add a callback to be called when a task run finishes.

**Args:**

* `task_run_id`: The ID of the task run to wait for.
* `callback`: The callback to call when the task run finishes.

#### `instance` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runs.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
instance(cls) -> Self
```

Get the singleton instance of TaskRunWaiter.

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runs.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self) -> None
```

Start the TaskRunWaiter service.

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runs.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self) -> None
```

Stop the TaskRunWaiter service.

#### `wait_for_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_runs.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_for_task_run(cls, task_run_id: uuid.UUID, timeout: Optional[float] = None) -> Optional[State[Any]]
```

Wait for a task run to finish and return its final state.

Note this relies on a websocket connection to receive events from the server
and will not work with an ephemeral server.

**Args:**

* `task_run_id`: The ID of the task run to wait for.
* `timeout`: The maximum time to wait for the task run to
  finish. Defaults to None.

**Returns:**

* The final state of the task run if available, None otherwise.


# task_worker
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-task_worker



# `prefect.task_worker`

## Functions

### `should_try_to_read_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
should_try_to_read_parameters(task: Task[P, R], task_run: TaskRun) -> bool
```

Determines whether a task run should read parameters from the result store.

### `create_status_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_status_server(task_worker: TaskWorker) -> FastAPI
```

### `serve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve(*tasks: Task[P, R])
```

Serve the provided tasks so that their runs may be submitted to
and executed in the engine. Tasks do not need to be within a flow run context to be
submitted. You must `.submit` the same task object that you pass to `serve`.

**Args:**

* `- tasks`: A list of tasks to serve. When a scheduled task run is found for a
  given task, the task run will be submitted to the engine for execution.
* `- limit`: The maximum number of tasks that can be run concurrently. Defaults to 10.
  Pass `None` to remove the limit.
* `- status_server_port`: An optional port on which to start an HTTP server
  exposing status information about the task worker. If not provided, no
  status server will run.
* `- timeout`: If provided, the task worker will exit after the given number of
  seconds. Defaults to None, meaning the task worker will run indefinitely.

### `store_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L522" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
store_parameters(result_store: ResultStore, identifier: UUID, parameters: dict[str, Any]) -> None
```

Store parameters for a task run in the result store.

**Args:**

* `result_store`: The result store to store the parameters in.
* `identifier`: The identifier of the task run.
* `parameters`: The parameters to store.

### `read_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L551" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read_parameters(result_store: ResultStore, identifier: UUID) -> dict[str, Any]
```

Read parameters for a task run from the result store.

**Args:**

* `result_store`: The result store to read the parameters from.
* `identifier`: The identifier of the task run.

**Returns:**

* The parameters for the task run.

## Classes

### `StopTaskWorker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when the task worker is stopped.

### `TaskWorker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

This class is responsible for serving tasks that may be executed in the background
by a task runner via the traditional engine machinery.

When `start()` is called, the task worker will open a websocket connection to a
server-side queue of scheduled task runs. When a scheduled task run is found, the
scheduled task run is submitted to the engine for execution with a minimal `EngineContext`
so that the task run can be governed by orchestration rules.

**Args:**

* `- tasks`: A list of tasks to serve. These tasks will be submitted to the engine
  when a scheduled task run is found.
* `- limit`: The maximum number of tasks that can be run concurrently. Defaults to 10.
  Pass `None` to remove the limit.

**Methods:**

#### `available_tasks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
available_tasks(self) -> Optional[int]
```

#### `client_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client_id(self) -> str
```

#### `current_tasks` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
current_tasks(self) -> Optional[int]
```

#### `execute_task_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
execute_task_run(self, task_run: TaskRun) -> None
```

Execute a task run in the task worker.

#### `handle_sigterm` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_sigterm(self, signum: int, frame: object) -> None
```

Shuts down the task worker when a SIGTERM is received.

#### `limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
limit(self) -> Optional[int]
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, timeout: Optional[float] = None) -> None
```

Starts a task worker, which runs the tasks provided in the constructor.

**Args:**

* `timeout`: If provided, the task worker will exit after the given number of
  seconds. Defaults to None, meaning the task worker will run indefinitely.

#### `started` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
started(self) -> bool
```

#### `started_at` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
started_at(self) -> Optional[DateTime]
```

#### `stop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_worker.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop(self)
```

Stops the task worker's polling cycle.


# tasks
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-tasks



# `prefect.tasks`

Module containing the base workflow task class and decorator - for most use cases, using the `@task` decorator is preferred.

## Functions

### `task_input_hash` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_input_hash(context: 'TaskRunContext', arguments: dict[str, Any]) -> Optional[str]
```

A task cache key implementation which hashes all inputs to the task using a JSON or
cloudpickle serializer. If any arguments are not JSON serializable, the pickle
serializer is used as a fallback. If cloudpickle fails, this will return a null key
indicating that a cache key could not be generated for the given inputs.

**Args:**

* `context`: the active `TaskRunContext`
* `arguments`: a dictionary of arguments to be passed to the underlying task

**Returns:**

* a string hash if hashing succeeded, else `None`

### `exponential_backoff` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exponential_backoff(backoff_factor: float) -> Callable[[int], list[float]]
```

A task retry backoff utility that configures exponential backoff for task retries.
The exponential backoff design matches the urllib3 implementation.

**Args:**

* `backoff_factor`: the base delay for the first retry, subsequent retries will
  increase the delay time by powers of 2.

**Returns:**

* a callable that can be passed to the task constructor

### `task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1869" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task(__fn: Optional[Callable[P, R]] = None)
```

Decorator to designate a function as a task in a Prefect workflow.

This decorator may be used for asynchronous or synchronous functions.

**Args:**

* `name`: An optional name for the task; if not provided, the name will be inferred
  from the given function.
* `description`: An optional string description for the task.
* `tags`: An optional set of tags to be associated with runs of this task. These
  tags are combined with any tags defined by a `prefect.tags` context at
  task runtime.
* `version`: An optional string specifying the version of this task definition
* `cache_key_fn`: An optional callable that, given the task run context and call
  parameters, generates a string key; if the key matches a previous completed
  state, that state result will be restored instead of running the task again.
* `cache_expiration`: An optional amount of time indicating how long cached states
  for this task should be restorable; if not provided, cached states will
  never expire.
* `task_run_name`: An optional name to distinguish runs of this task; this name can be provided
  as a string template with the task's keyword arguments as variables,
  or a function that returns a string.
* `retries`: An optional number of times to retry on task run failure
* `retry_delay_seconds`: Optionally configures how long to wait before retrying the
  task after failure. This is only applicable if `retries` is nonzero. This
  setting can either be a number of seconds, a list of retry delays, or a
  callable that, given the total number of retries, generates a list of retry
  delays. If a number of seconds, that delay will be applied to all retries.
  If a list, each retry will wait for the corresponding delay before retrying.
  When passing a callable or a list, the number of
  configured retry delays cannot exceed 50.
* `retry_jitter_factor`: An optional factor that defines the factor to which a
  retry can be jittered in order to avoid a "thundering herd".
* `persist_result`: A toggle indicating whether the result of this task
  should be persisted to result storage. Defaults to `None`, which
  indicates that the global default should be used (which is `True` by
  default).
* `result_storage`: An optional block to use to persist the result of this task.
  Defaults to the value set in the flow the task is called in.
* `result_storage_key`: An optional key to store the result in storage at when persisted.
  Defaults to a unique identifier.
* `result_serializer`: An optional serializer to use to serialize the result of this
  task for persistence. Defaults to the value set in the flow the task is
  called in.
* `timeout_seconds`: An optional number of seconds indicating a maximum runtime for
  the task. If the task exceeds this runtime, it will be marked as failed.
* `log_prints`: If set, `print` statements in the task will be redirected to the
  Prefect logger for the task run. Defaults to `None`, which indicates
  that the value from the flow should be used.
* `refresh_cache`: If set, cached results for the cache key are not used.
  Defaults to `None`, which indicates that a cached result from a previous
  execution with matching cache key is used.
* `on_failure`: An optional list of callables to run when the task enters a failed state.
* `on_completion`: An optional list of callables to run when the task enters a completed state.
* `retry_condition_fn`: An optional callable run when a task run returns a Failed state. Should
  return `True` if the task should continue to its retry policy (e.g. `retries=3`), and `False` if the task
  should end as failed. Defaults to `None`, indicating the task should always continue
  to its retry policy.
* `viz_return_value`: An optional value to return when the task dependency tree is visualized.
* `asset_deps`: An optional list of upstream assets that this task depends on.

**Returns:**

* A callable `Task` object which, when called, will submit the task for execution.

**Examples:**

Define a simple task

```python
@task
def add(x, y):
    return x + y
```

Define an async task

```python
@task
async def add(x, y):
    return x + y
```

Define a task with tags and a description

```python
@task(tags={"a", "b"}, description="This task is empty but its my first!")
def my_task():
    pass
```

Define a task with a custom name

```python
@task(name="The Ultimate Task")
def my_task():
    pass
```

Define a task that retries 3 times with a 5 second delay between attempts

```python
from random import randint

@task(retries=3, retry_delay_seconds=5)
def my_task():
    x = randint(0, 5)
    if x >= 3:  # Make a task that fails sometimes
        raise ValueError("Retry me please!")
    return x
```

Define a task that is cached for a day based on its inputs

```python
from prefect.tasks import task_input_hash
from datetime import timedelta

@task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))
def my_task():
    return "hello"
```

## Classes

### `TaskRunNameCallbackWithParameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_callback_with_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_callback_with_parameters(cls, callable: Callable[..., str]) -> TypeIs[Self]
```

### `TaskOptions` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A TypedDict representing all available task configuration options.

This can be used with `Unpack` to provide type hints for \*\*kwargs.

### `Task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L300" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A Prefect task definition.

Wraps a function with an entrypoint to the Prefect engine. Calling this class within a flow function
creates a new task run.

To preserve the input and output types, we use the generic type variables P and R for "Parameters" and
"Returns" respectively.

**Args:**

* `fn`: The function defining the task.
* `name`: An optional name for the task; if not provided, the name will be inferred
  from the given function.
* `description`: An optional string description for the task.
* `tags`: An optional set of tags to be associated with runs of this task. These
  tags are combined with any tags defined by a `prefect.tags` context at
  task runtime.
* `version`: An optional string specifying the version of this task definition
* `cache_policy`: A cache policy that determines the level of caching for this task
* `cache_key_fn`: An optional callable that, given the task run context and call
  parameters, generates a string key; if the key matches a previous completed
  state, that state result will be restored instead of running the task again.
* `cache_expiration`: An optional amount of time indicating how long cached states
  for this task should be restorable; if not provided, cached states will
  never expire.
* `task_run_name`: An optional name to distinguish runs of this task; this name can be provided
  as a string template with the task's keyword arguments as variables,
  or a function that returns a string.
* `retries`: An optional number of times to retry on task run failure.
* `retry_delay_seconds`: Optionally configures how long to wait before retrying the
  task after failure. This is only applicable if `retries` is nonzero. This
  setting can either be a number of seconds, a list of retry delays, or a
  callable that, given the total number of retries, generates a list of retry
  delays. If a number of seconds, that delay will be applied to all retries.
  If a list, each retry will wait for the corresponding delay before retrying.
  When passing a callable or a list, the number of configured retry delays
  cannot exceed 50.
* `retry_jitter_factor`: An optional factor that defines the factor to which a retry
  can be jittered in order to avoid a "thundering herd".
* `persist_result`: A toggle indicating whether the result of this task
  should be persisted to result storage. Defaults to `None`, which
  indicates that the global default should be used (which is `True` by
  default).
* `result_storage`: An optional block to use to persist the result of this task.
  Defaults to the value set in the flow the task is called in.
* `result_storage_key`: An optional key to store the result in storage at when persisted.
  Defaults to a unique identifier.
* `result_serializer`: An optional serializer to use to serialize the result of this
  task for persistence. Defaults to the value set in the flow the task is
  called in.
* `timeout_seconds`: An optional number of seconds indicating a maximum runtime for
  the task. If the task exceeds this runtime, it will be marked as failed.
* `log_prints`: If set, `print` statements in the task will be redirected to the
  Prefect logger for the task run. Defaults to `None`, which indicates
  that the value from the flow should be used.
* `refresh_cache`: If set, cached results for the cache key are not used.
  Defaults to `None`, which indicates that a cached result from a previous
  execution with matching cache key is used.
* `on_failure`: An optional list of callables to run when the task enters a failed state.
* `on_completion`: An optional list of callables to run when the task enters a completed state.
* `on_commit`: An optional list of callables to run when the task's idempotency record is committed.
* `on_rollback`: An optional list of callables to run when the task rolls back.
* `retry_condition_fn`: An optional callable run when a task run returns a Failed state. Should
  return `True` if the task should continue to its retry policy (e.g. `retries=3`), and `False` if the task
  should end as failed. Defaults to `None`, indicating the task should always continue
  to its retry policy.
* `viz_return_value`: An optional value to return when the task dependency tree is visualized.
* `asset_deps`: An optional list of upstream assets that this task depends on.

**Methods:**

#### `apply_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
apply_async(self, args: Optional[tuple[Any, ...]] = None, kwargs: Optional[dict[str, Any]] = None, wait_for: Optional[Iterable[PrefectFuture[R]]] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> PrefectDistributedFuture[R]
```

Create a pending task run for a task worker to execute.

**Args:**

* `args`: Arguments to run the task with
* `kwargs`: Keyword arguments to run the task with

**Returns:**

* A PrefectDistributedFuture object representing the pending task run

Examples:

Define a task

```python
from prefect import task
@task
def my_task(name: str = "world"):
    return f"hello {name}"
```

Create a pending task run for the task

```python
from prefect import flow
@flow
def my_flow():
    my_task.apply_async(("marvin",))
```

Wait for a task to finish

```python
@flow
def my_flow():
    my_task.apply_async(("marvin",)).wait()
```

```python
@flow
def my_flow():
    print(my_task.apply_async(("marvin",)).result())

my_flow()
# hello marvin
```

TODO: Enforce ordering between tasks that do not exchange data

```python
@task
def task_1():
    pass

@task
def task_2():
    pass

@flow
def my_flow():
    x = task_1.apply_async()

    # task 2 will wait for task_1 to complete
    y = task_2.apply_async(wait_for=[x])
```

#### `create_local_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L947" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_local_run(self, client: Optional['PrefectClient'] = None, id: Optional[UUID] = None, parameters: Optional[dict[str, Any]] = None, flow_run_context: Optional[FlowRunContext] = None, parent_task_run_context: Optional[TaskRunContext] = None, wait_for: Optional[OneOrManyFutureOrResult[Any]] = None, extra_task_inputs: Optional[dict[str, set[RunInput]]] = None, deferred: bool = False) -> TaskRun
```

#### `create_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L844" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_run(self, client: Optional['PrefectClient'] = None, id: Optional[UUID] = None, parameters: Optional[dict[str, Any]] = None, flow_run_context: Optional[FlowRunContext] = None, parent_task_run_context: Optional[TaskRunContext] = None, wait_for: Optional[OneOrManyFutureOrResult[Any]] = None, extra_task_inputs: Optional[dict[str, set[RunInput]]] = None, deferred: bool = False) -> TaskRun
```

#### `delay` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1683" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delay(self, *args: P.args, **kwargs: P.kwargs) -> PrefectDistributedFuture[R]
```

An alias for `apply_async` with simpler calling semantics.

Avoids having to use explicit "args" and "kwargs" arguments. Arguments
will pass through as-is to the task.

Examples:

Define a task

```python
from prefect import task
@task
def my_task(name: str = "world"):
    return f"hello {name}"
```

Create a pending task run for the task

```python
from prefect import flow
@flow
def my_flow():
    my_task.delay("marvin")
```

Wait for a task to finish

```python
@flow
def my_flow():
    my_task.delay("marvin").wait()
```

Use the result from a task in a flow

```python
@flow
def my_flow():
    print(my_task.delay("marvin").result())

my_flow()
# hello marvin
```

#### `isclassmethod` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L617" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
isclassmethod(self) -> bool
```

#### `ismethod` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L613" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ismethod(self) -> bool
```

#### `isstaticmethod` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L621" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
isstaticmethod(self) -> bool
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1329" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self: 'Task[P, R]', *args: Any, **kwargs: Any) -> list[State[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1339" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self: 'Task[P, R]', *args: Any, **kwargs: Any) -> PrefectFutureList[R]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1348" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self: 'Task[P, R]', *args: Any, **kwargs: Any) -> list[State[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self: 'Task[P, R]', *args: Any, **kwargs: Any) -> PrefectFutureList[R]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self: 'Task[P, Coroutine[Any, Any, R]]', *args: Any, **kwargs: Any) -> list[State[R]]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1377" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self: 'Task[P, Coroutine[Any, Any, R]]', *args: Any, **kwargs: Any) -> PrefectFutureList[R]
```

#### `map` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
map(self, *args: Any, **kwargs: Any) -> Union[list[State[R]], PrefectFutureList[R]]
```

Submit a mapped run of the task to a worker.

Must be called within a flow run context. Will return a list of futures
that should be waited on before exiting the flow context to ensure all
mapped tasks have completed.

Must be called with at least one iterable and all iterables must be
the same length. Any arguments that are not iterable will be treated as
a static value and each task run will receive the same value.

Will create as many task runs as the length of the iterable(s) in the
backing API and submit the task runs to the flow's task runner. This
call blocks if given a future as input while the future is resolved. It
also blocks while the tasks are being submitted, once they are
submitted, the flow function will continue executing.

This method is always synchronous, even if the underlying user function is asynchronous.

**Args:**

* `*args`: Iterable and static arguments to run the tasks with
* `return_state`: Return a list of Prefect States that wrap the results
  of each task run.
* `wait_for`: Upstream task futures to wait for before starting the
  task
* `**kwargs`: Keyword iterable arguments to run the task with

**Returns:**

* A list of futures allowing asynchronous access to the state of the
* tasks

Examples:

Define a task

```python
from prefect import task
@task
def my_task(x):
    return x + 1
```

Create mapped tasks

```python
from prefect import flow
@flow
def my_flow():
    return my_task.map([1, 2, 3])
```

Wait for all mapped tasks to finish

```python
@flow
def my_flow():
    futures = my_task.map([1, 2, 3])
    futures.wait():
    # Now all of the mapped tasks have finished
    my_task(10)
```

Use the result from mapped tasks in a flow

```python
@flow
def my_flow():
    futures = my_task.map([1, 2, 3])
    for x in futures.result():
        print(x)
my_flow()
# 2
# 3
# 4
```

Enforce ordering between tasks that do not exchange data

```python
@task
def task_1(x):
    pass

@task
def task_2(y):
    pass

@flow
def my_flow():
    x = task_1.submit()

    # task 2 will wait for task_1 to complete
    y = task_2.map([1, 2, 3], wait_for=[x])
    return y
```

Use a non-iterable input as a constant across mapped tasks

```python
@task
def display(prefix, item):
   print(prefix, item)

@flow
def my_flow():
    return display.map("Check it out: ", [1, 2, 3])

my_flow()
# Check it out: 1
# Check it out: 2
# Check it out: 3
```

Use `unmapped` to treat an iterable argument as a constant

```python
from prefect import unmapped

@task
def add_n_to_items(items, n):
    return [item + n for item in items]

@flow
def my_flow():
    return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])

my_flow()
# [[11, 21], [12, 22], [13, 23]]
```

#### `on_commit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L832" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_commit(self, fn: Callable[['Transaction'], None]) -> Callable[['Transaction'], None]
```

#### `on_completion` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L824" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_completion(self, fn: StateHookCallable) -> StateHookCallable
```

#### `on_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L828" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_failure(self, fn: StateHookCallable) -> StateHookCallable
```

#### `on_rollback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L838" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_rollback(self, fn: Callable[['Transaction'], None]) -> Callable[['Transaction'], None]
```

#### `serve` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1732" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serve(self) -> NoReturn
```

Serve the task using the provided task runner. This method is used to
establish a websocket connection with the Prefect server and listen for
submitted task runs to execute.

**Args:**

* `task_runner`: The task runner to use for serving the task. If not provided,
  the default task runner will be used.

**Examples:**

Serve a task using the default task runner

```python
@task
def my_task():
    return 1

my_task.serve()
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self: 'Task[P, R]', *args: P.args, **kwargs: P.kwargs) -> PrefectFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self: 'Task[P, Coroutine[Any, Any, R]]', *args: P.args, **kwargs: P.kwargs) -> PrefectFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self: 'Task[P, R]', *args: P.args, **kwargs: P.kwargs) -> PrefectFuture[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self: 'Task[P, Coroutine[Any, Any, R]]', *args: P.args, **kwargs: P.kwargs) -> State[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self: 'Task[P, R]', *args: P.args, **kwargs: P.kwargs) -> State[R]
```

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L1189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self: 'Union[Task[P, R], Task[P, Coroutine[Any, Any, R]]]', *args: Any, **kwargs: Any)
```

Submit a run of the task to the engine.

Will create a new task run in the backing API and submit the task to the flow's
task runner. This call only blocks execution while the task is being submitted,
once it is submitted, the flow function will continue executing.

This method is always synchronous, even if the underlying user function is asynchronous.

**Args:**

* `*args`: Arguments to run the task with
* `return_state`: Return the result of the flow run wrapped in a
  Prefect State.
* `wait_for`: Upstream task futures to wait for before starting the task
* `**kwargs`: Keyword arguments to run the task with

**Returns:**

* If `return_state` is False a future allowing asynchronous access to
  the state of the task
* If `return_state` is True a future wrapped in a Prefect State allowing asynchronous access to
  the state of the task

Examples:

Define a task

```python
from prefect import task
@task
def my_task():
    return "hello"
```

Run a task in a flow

```python
from prefect import flow
@flow
def my_flow():
    my_task.submit()
```

Wait for a task to finish

```python
@flow
def my_flow():
    my_task.submit().wait()
```

Use the result from a task in a flow

```python
@flow
def my_flow():
    print(my_task.submit().result())

my_flow()
# hello
```

Run an async task in an async flow

```python
@task
async def my_async_task():
    pass

@flow
async def my_flow():
    my_async_task.submit()
```

Run a sync task in an async flow

```python
@flow
async def my_flow():
    my_task.submit()
```

Enforce ordering between tasks that do not exchange data

```python
@task
def task_1():
    pass

@task
def task_2():
    pass

@flow
def my_flow():
    x = task_1.submit()

    # task 2 will wait for task_1 to complete
    y = task_2.submit(wait_for=[x])
```

#### `with_options` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L645" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_options(self) -> 'Task[P, R]'
```

Create a new task from the current object, updating provided options.

**Args:**

* `name`: A new name for the task.
* `description`: A new description for the task.
* `tags`: A new set of tags for the task. If given, existing tags are ignored,
  not merged.
* `cache_key_fn`: A new cache key function for the task.
* `cache_expiration`: A new cache expiration time for the task.
* `task_run_name`: An optional name to distinguish runs of this task; this name can be provided
  as a string template with the task's keyword arguments as variables,
  or a function that returns a string.
* `retries`: A new number of times to retry on task run failure.
* `retry_delay_seconds`: Optionally configures how long to wait before retrying
  the task after failure. This is only applicable if `retries` is nonzero.
  This setting can either be a number of seconds, a list of retry delays,
  or a callable that, given the total number of retries, generates a list
  of retry delays. If a number of seconds, that delay will be applied to
  all retries. If a list, each retry will wait for the corresponding delay
  before retrying. When passing a callable or a list, the number of
  configured retry delays cannot exceed 50.
* `retry_jitter_factor`: An optional factor that defines the factor to which a
  retry can be jittered in order to avoid a "thundering herd".
* `persist_result`: A new option for enabling or disabling result persistence.
* `result_storage`: A new storage type to use for results.
* `result_serializer`: A new serializer to use for results.
* `result_storage_key`: A new key for the persisted result to be stored at.
* `timeout_seconds`: A new maximum time for the task to complete in seconds.
* `log_prints`: A new option for enabling or disabling redirection of `print` statements.
* `refresh_cache`: A new option for enabling or disabling cache refresh.
* `on_completion`: A new list of callables to run when the task enters a completed state.
* `on_failure`: A new list of callables to run when the task enters a failed state.
* `retry_condition_fn`: An optional callable run when a task run returns a Failed state.
  Should return `True` if the task should continue to its retry policy, and `False`
  if the task should end as failed. Defaults to `None`, indicating the task should
  always continue to its retry policy.
* `viz_return_value`: An optional value to return when the task dependency tree is visualized.

**Returns:**

* A new `Task` instance.

Examples:

Create a new task from an existing task and update the name:

```python
@task(name="My task")
def my_task():
    return 1

new_task = my_task.with_options(name="My new task")
```

Create a new task from an existing task and update the retry settings:

```python
from random import randint

@task(retries=1, retry_delay_seconds=5)
def my_task():
    x = randint(0, 5)
    if x >= 3:  # Make a task that fails sometimes
        raise ValueError("Retry me please!")
    return x

new_task = my_task.with_options(retries=5, retry_delay_seconds=2)
```

Use a task with updated options within a flow:

```python
@task(name="My task")
def my_task():
    return 1

@flow
my_flow():
    new_task = my_task.with_options(name="My new task")
    new_task()
```

### `MaterializingTask` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L2084" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A task that materializes Assets.

**Args:**

* `assets`: List of Assets that this task materializes (can be str or Asset)
* `materialized_by`: An optional tool that materialized the asset e.g. "dbt" or "spark"
* `**task_kwargs`: All other Task arguments

**Methods:**

#### `with_options` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/tasks.py#L2109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
with_options(self, assets: Optional[Sequence[Union[str, Asset]]] = None, **task_kwargs: Unpack[TaskOptions]) -> 'MaterializingTask[P, R]'
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-telemetry-__init__



# `prefect.telemetry`

*This module is empty or contains only private/internal implementations.*


# run_telemetry
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-telemetry-run_telemetry



# `prefect.telemetry.run_telemetry`

## Classes

### `OTELSetter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A setter for OpenTelemetry that supports Prefect's custom labels.

**Methods:**

#### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, carrier: KeyValueLabels, key: str, value: str) -> None
```

### `RunTelemetry` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A class for managing the telemetry of runs.

**Methods:**

#### `async_start_span` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
async_start_span(self, run: FlowOrTaskRun, client: PrefectClient, parameters: dict[str, Any] | None = None) -> Span | None
```

#### `end_span_on_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
end_span_on_failure(self, terminal_message: str | None = None) -> None
```

End a span for a run on failure.

#### `end_span_on_success` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
end_span_on_success(self) -> None
```

End a span for a run on success.

#### `record_exception` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
record_exception(self, exc: BaseException) -> None
```

Record an exception on a span.

#### `start_span` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_span(self, run: FlowOrTaskRun, client: SyncPrefectClient, parameters: dict[str, Any] | None = None) -> Span | None
```

#### `traceparent_from_span` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
traceparent_from_span(span: Span) -> str | None
```

#### `update_run_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_run_name(self, name: str) -> None
```

Update the name of the run.

#### `update_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/telemetry/run_telemetry.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_state(self, new_state: State) -> None
```

Update a span with the state of a run.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-testing-__init__



# `prefect.testing`

*This module is empty or contains only private/internal implementations.*


# cli
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-testing-cli



# `prefect.testing.cli`

## Functions

### `check_contains` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/cli.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_contains(cli_result: Result, content: str, should_contain: bool) -> None
```

Utility function to see if content is or is not in a CLI result.

**Args:**

* `should_contain`: if True, checks that content is in cli\_result,
  if False, checks that content is not in cli\_result

### `invoke_and_assert` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/cli.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
invoke_and_assert(command: str | list[str], user_input: str | None = None, prompts_and_responses: list[tuple[str, str] | tuple[str, str, str]] | None = None, expected_output: str | None = None, expected_output_contains: str | Iterable[str] | None = None, expected_output_does_not_contain: str | Iterable[str] | None = None, expected_line_count: int | None = None, expected_code: int | None = 0, echo: bool = True, temp_dir: str | None = None) -> Result
```

Test utility for the Prefect CLI application, asserts exact match with CLI output.

**Args:**

* `command`: Command passed to the Typer CliRunner
* `user_input`: User input passed to the Typer CliRunner when running interactive
  commands.
* `expected_output`: Used when you expect the CLI output to be an exact match with
  the provided text.
* `expected_output_contains`: Used when you expect the CLI output to contain the
  string or strings.
* `expected_output_does_not_contain`: Used when you expect the CLI output to not
  contain the string or strings.
* `expected_code`: 0 if we expect the app to exit cleanly, else 1 if we expect
  the app to exit with an error.
* `temp_dir`: if provided, the CLI command will be run with this as its present
  working directory.

### `temporary_console_width` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/cli.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_console_width(console: Console, width: int)
```


# docker
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-testing-docker



# `prefect.testing.docker`

## Functions

### `capture_builders` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/docker.py#L9" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
capture_builders() -> Generator[list[ImageBuilder], None, None]
```

Captures any instances of ImageBuilder created while this context is active


# fixtures
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-testing-fixtures



# `prefect.testing.fixtures`

## Functions

### `add_prefect_loggers_to_caplog` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_prefect_loggers_to_caplog(caplog: pytest.LogCaptureFixture) -> Generator[None, None, None]
```

### `is_port_in_use` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_port_in_use(port: int) -> bool
```

### `hosted_api_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hosted_api_server(unused_tcp_port_factory: Callable[[], int]) -> AsyncGenerator[str, None]
```

Runs an instance of the Prefect API server in a subprocess instead of the using the
ephemeral application.

Uses the same database as the rest of the tests.

### `use_hosted_api_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
use_hosted_api_server(hosted_api_server: str) -> Generator[str, None, None]
```

Sets `PREFECT_API_URL` to the test session's hosted API endpoint.

### `disable_hosted_api_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
disable_hosted_api_server() -> Generator[None, None, None]
```

Disables the hosted API server by setting `PREFECT_API_URL` to `None`.

### `enable_ephemeral_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enable_ephemeral_server(disable_hosted_api_server: None) -> Generator[None, None, None]
```

Enables the ephemeral server by setting `PREFECT_SERVER_ALLOW_EPHEMERAL_MODE` to `True`.

### `mock_anyio_sleep` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
mock_anyio_sleep(monkeypatch: pytest.MonkeyPatch) -> Generator[Callable[[float], None], None, None]
```

Mock sleep used to not actually sleep but to set the current time to now + sleep
delay seconds while still yielding to other tasks in the event loop.

Provides "assert\_sleeps\_for" context manager which asserts a sleep time occurred
within the context while using the actual runtime of the context as a tolerance.

### `recorder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L292" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
recorder() -> Recorder
```

### `puppeteer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
puppeteer() -> Puppeteer
```

### `events_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_server(unused_tcp_port: int, recorder: Recorder, puppeteer: Puppeteer) -> AsyncGenerator[Server, None]
```

### `events_api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L375" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_api_url(events_server: Server, unused_tcp_port: int) -> str
```

### `events_cloud_api_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_cloud_api_url(events_server: Server, unused_tcp_port: int) -> str
```

### `mock_should_emit_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
mock_should_emit_events(monkeypatch: pytest.MonkeyPatch) -> mock.Mock
```

### `asserting_events_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asserting_events_worker(monkeypatch: pytest.MonkeyPatch) -> Generator[EventsWorker, None, None]
```

### `asserting_and_emitting_events_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asserting_and_emitting_events_worker(monkeypatch: pytest.MonkeyPatch) -> Generator[EventsWorker, None, None]
```

### `events_pipeline` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
events_pipeline(asserting_events_worker: EventsWorker) -> AsyncGenerator[EventsPipeline, None]
```

### `emitting_events_pipeline` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L456" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emitting_events_pipeline(asserting_and_emitting_events_worker: EventsWorker) -> AsyncGenerator[EventsPipeline, None]
```

### `reset_worker_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L472" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_worker_events(asserting_events_worker: EventsWorker) -> Generator[None, None, None]
```

### `enable_lineage_events` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L481" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enable_lineage_events() -> Generator[None, None, None]
```

A fixture that ensures lineage events are enabled.

## Classes

### `Recorder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Puppeteer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/fixtures.py#L275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# standard_test_suites
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-testing-standard_test_suites



# `prefect.testing.standard_test_suites`

*This module is empty or contains only private/internal implementations.*


# utilities
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-testing-utilities



# `prefect.testing.utilities`

Internal utilities for tests.

## Functions

### `exceptions_equal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exceptions_equal(a: Exception, b: Exception) -> bool
```

Exceptions cannot be compared by `==`. They can be compared using `is` but this
will fail if the exception is serialized/deserialized so this utility does its
best to assert equality using the type and args used to initialize the exception

### `kubernetes_environments_equal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
kubernetes_environments_equal(actual: list[dict[str, str]], expected: list[dict[str, str]] | dict[str, str]) -> bool
```

### `assert_does_not_warn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_does_not_warn(ignore_warnings: list[type[Warning]] | None = None) -> Generator[None, None, None]
```

Converts warnings to errors within this context to assert warnings are not raised,
except for those specified in ignore\_warnings.

Parameters:

* ignore\_warnings: List of warning types to ignore. Example: \[DeprecationWarning, UserWarning]

### `prefect_test_harness` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prefect_test_harness(server_startup_timeout: int | None = 30)
```

Temporarily run flows against a local SQLite database for testing.

**Args:**

* `server_startup_timeout`: The maximum time to wait for the server to start.
  Defaults to 30 seconds. If set to `None`, the value of
  `PREFECT_SERVER_EPHEMERAL_STARTUP_TIMEOUT_SECONDS` will be used.

**Examples:**

```python
from prefect import flow
from prefect.testing.utilities import prefect_test_harness


@flow
def my_flow():
    return 'Done!'

with prefect_test_harness():
    assert my_flow() == 'Done!' # run against temporary db
```

### `get_most_recent_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_most_recent_flow_run(client: 'PrefectClient | None' = None, flow_name: str | None = None) -> 'FlowRun'
```

### `assert_blocks_equal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_blocks_equal(found: Block, expected: Block, exclude_private: bool = True, **kwargs: Any) -> None
```

### `assert_uses_result_serializer` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_uses_result_serializer(state: State, serializer: str | Serializer, client: 'PrefectClient') -> None
```

### `assert_uses_result_storage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_uses_result_storage(state: State, storage: 'str | ReadableFileSystem', client: 'PrefectClient') -> None
```

### `a_test_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
a_test_step(**kwargs: Any) -> dict[str, Any]
```

### `b_test_step` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/testing/utilities.py#L296" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
b_test_step(**kwargs: Any) -> dict[str, Any]
```


# transactions
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-transactions



# `prefect.transactions`

## Functions

### `get_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L656" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_transaction() -> BaseTransaction | None
```

### `transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L661" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
transaction(key: str | None = None, store: ResultStore | None = None, commit_mode: CommitMode | None = None, isolation_level: IsolationLevel | None = None, overwrite: bool = False, write_on_commit: bool = True, logger: logging.Logger | LoggingAdapter | None = None) -> Generator[Transaction, None, None]
```

A context manager for opening and managing a transaction.

**Args:**

* `- key`: An identifier to use for the transaction
* `- store`: The store to use for persisting the transaction result. If not provided,
  a default store will be used based on the current run context.
* `- commit_mode`: The commit mode controlling when the transaction and
  child transactions are committed
* `- overwrite`: Whether to overwrite an existing transaction record in the store
* `- write_on_commit`: Whether to write the result to the store on commit. If not provided,
  will default will be determined by the current run context. If no run context is
  available, the value of `PREFECT_RESULTS_PERSIST_BY_DEFAULT` will be used.

### `atransaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L713" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
atransaction(key: str | None = None, store: ResultStore | None = None, commit_mode: CommitMode | None = None, isolation_level: IsolationLevel | None = None, overwrite: bool = False, write_on_commit: bool = True, logger: logging.Logger | LoggingAdapter | None = None) -> AsyncGenerator[AsyncTransaction, None]
```

An asynchronous context manager for opening and managing an asynchronous transaction.

**Args:**

* `- key`: An identifier to use for the transaction
* `- store`: The store to use for persisting the transaction result. If not provided,
  a default store will be used based on the current run context.
* `- commit_mode`: The commit mode controlling when the transaction and
  child transactions are committed
* `- overwrite`: Whether to overwrite an existing transaction record in the store
* `- write_on_commit`: Whether to write the result to the store on commit. If not provided,
  the default will be determined by the current run context. If no run context is
  available, the value of `PREFECT_RESULTS_PERSIST_BY_DEFAULT` will be used.

## Classes

### `IsolationLevel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `CommitMode` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `TransactionState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `BaseTransaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A base model for transaction state.

**Methods:**

#### `add_child` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_child(self, transaction: Self) -> None
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, name: str, default: Any = NotSet) -> Any
```

Get a stored value from the transaction.

Child transactions will return values from their parents unless a value with
the same name is set in the child transaction.

Direct changes to returned values will not update the stored value. To update the
stored value, use the `set` method.

**Args:**

* `name`: The name of the value to get
* `default`: The default value to return if the value is not found

**Returns:**

* The value from the transaction

**Examples:**

Get a value from the transaction:

```python
with transaction() as txn:
    txn.set("key", "value")
    ...
    assert txn.get("key") == "value"
```

Get a value from a parent transaction:

```python
with transaction() as parent:
    parent.set("key", "parent_value")
    with transaction() as child:
        assert child.get("key") == "parent_value"
```

Update a stored value:

```python
with transaction() as txn:
    txn.set("key", [1, 2, 3])
    value = txn.get("key")
    value.append(4)
    # Stored value is not updated until `.set` is called
    assert value == [1, 2, 3, 4]
    assert txn.get("key") == [1, 2, 3]

    txn.set("key", value)
    assert txn.get("key") == [1, 2, 3, 4]
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls: type[Self]) -> Optional[Self]
```

Get the current context instance

#### `get_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_active(cls: Type[Self]) -> Optional[Self]
```

#### `get_parent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parent(self) -> Self | None
```

#### `is_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_active(self) -> bool
```

#### `is_committed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_committed(self) -> bool
```

#### `is_pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_pending(self) -> bool
```

#### `is_rolled_back` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_rolled_back(self) -> bool
```

#### `is_staged` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_staged(self) -> bool
```

#### `model_copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_copy(self: Self) -> Self
```

Duplicate the context model, optionally choosing which fields to include, exclude, or change.

**Returns:**

* A new model instance.

#### `prepare_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_transaction(self) -> None
```

Helper method to prepare transaction state and validate configuration.

#### `serialize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/context.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
serialize(self, include_secrets: bool = True) -> dict[str, Any]
```

Serialize the context model to a dictionary that can be pickled with cloudpickle.

#### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, name: str, value: Any) -> None
```

Set a stored value in the transaction.

**Args:**

* `name`: The name of the value to set
* `value`: The value to set

**Examples:**

Set a value for use later in the transaction:

```python
with transaction() as txn:
    txn.set("key", "value")
    ...
    assert txn.get("key") == "value"
```

#### `stage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stage(self, value: Any, on_rollback_hooks: Optional[list[Callable[..., Any]]] = None, on_commit_hooks: Optional[list[Callable[..., Any]]] = None) -> None
```

Stage a value to be committed later.

### `Transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A model representing the state of a transaction.

**Methods:**

#### `add_child` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_child(self, transaction: Self) -> None
```

#### `begin` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L300" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin(self) -> None
```

#### `commit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
commit(self) -> bool
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, name: str, default: Any = NotSet) -> Any
```

Get a stored value from the transaction.

Child transactions will return values from their parents unless a value with
the same name is set in the child transaction.

Direct changes to returned values will not update the stored value. To update the
stored value, use the `set` method.

**Args:**

* `name`: The name of the value to get
* `default`: The default value to return if the value is not found

**Returns:**

* The value from the transaction

**Examples:**

Get a value from the transaction:

```python
with transaction() as txn:
    txn.set("key", "value")
    ...
    assert txn.get("key") == "value"
```

Get a value from a parent transaction:

```python
with transaction() as parent:
    parent.set("key", "parent_value")
    with transaction() as child:
        assert child.get("key") == "parent_value"
```

Update a stored value:

```python
with transaction() as txn:
    txn.set("key", [1, 2, 3])
    value = txn.get("key")
    value.append(4)
    # Stored value is not updated until `.set` is called
    assert value == [1, 2, 3, 4]
    assert txn.get("key") == [1, 2, 3]

    txn.set("key", value)
    assert txn.get("key") == [1, 2, 3, 4]
```

#### `get_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_active(cls: Type[Self]) -> Optional[Self]
```

#### `get_parent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parent(self) -> Self | None
```

#### `is_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_active(self) -> bool
```

#### `is_committed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_committed(self) -> bool
```

#### `is_pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_pending(self) -> bool
```

#### `is_rolled_back` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_rolled_back(self) -> bool
```

#### `is_staged` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_staged(self) -> bool
```

#### `prepare_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_transaction(self) -> None
```

Helper method to prepare transaction state and validate configuration.

#### `read` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read(self) -> ResultRecord[Any] | None
```

#### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(self) -> None
```

#### `rollback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rollback(self) -> bool
```

#### `run_hook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L394" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_hook(self, hook: Callable[..., Any], hook_type: str) -> None
```

#### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, name: str, value: Any) -> None
```

Set a stored value in the transaction.

**Args:**

* `name`: The name of the value to set
* `value`: The value to set

**Examples:**

Set a value for use later in the transaction:

```python
with transaction() as txn:
    txn.set("key", "value")
    ...
    assert txn.get("key") == "value"
```

#### `stage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stage(self, value: Any, on_rollback_hooks: Optional[list[Callable[..., Any]]] = None, on_commit_hooks: Optional[list[Callable[..., Any]]] = None) -> None
```

Stage a value to be committed later.

### `AsyncTransaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L453" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A model representing the state of an asynchronous transaction.

**Methods:**

#### `add_child` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L218" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_child(self, transaction: Self) -> None
```

#### `begin` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L458" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin(self) -> None
```

#### `commit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L494" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
commit(self) -> bool
```

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, name: str, default: Any = NotSet) -> Any
```

Get a stored value from the transaction.

Child transactions will return values from their parents unless a value with
the same name is set in the child transaction.

Direct changes to returned values will not update the stored value. To update the
stored value, use the `set` method.

**Args:**

* `name`: The name of the value to get
* `default`: The default value to return if the value is not found

**Returns:**

* The value from the transaction

**Examples:**

Get a value from the transaction:

```python
with transaction() as txn:
    txn.set("key", "value")
    ...
    assert txn.get("key") == "value"
```

Get a value from a parent transaction:

```python
with transaction() as parent:
    parent.set("key", "parent_value")
    with transaction() as child:
        assert child.get("key") == "parent_value"
```

Update a stored value:

```python
with transaction() as txn:
    txn.set("key", [1, 2, 3])
    value = txn.get("key")
    value.append(4)
    # Stored value is not updated until `.set` is called
    assert value == [1, 2, 3, 4]
    assert txn.get("key") == [1, 2, 3]

    txn.set("key", value)
    assert txn.get("key") == [1, 2, 3, 4]
```

#### `get_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_active(cls: Type[Self]) -> Optional[Self]
```

#### `get_parent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parent(self) -> Self | None
```

#### `is_active` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_active(self) -> bool
```

#### `is_committed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_committed(self) -> bool
```

#### `is_pending` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_pending(self) -> bool
```

#### `is_rolled_back` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_rolled_back(self) -> bool
```

#### `is_staged` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_staged(self) -> bool
```

#### `prepare_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_transaction(self) -> None
```

Helper method to prepare transaction state and validate configuration.

#### `read` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L474" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
read(self) -> ResultRecord[Any] | None
```

#### `reset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L479" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset(self) -> None
```

#### `rollback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L577" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rollback(self) -> bool
```

#### `run_hook` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_hook(self, hook: Callable[..., Any], hook_type: str) -> None
```

#### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, name: str, value: Any) -> None
```

Set a stored value in the transaction.

**Args:**

* `name`: The name of the value to set
* `value`: The value to set

**Examples:**

Set a value for use later in the transaction:

```python
with transaction() as txn:
    txn.set("key", "value")
    ...
    assert txn.get("key") == "value"
```

#### `stage` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/transactions.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stage(self, value: Any, on_rollback_hooks: Optional[list[Callable[..., Any]]] = None, on_commit_hooks: Optional[list[Callable[..., Any]]] = None) -> None
```

Stage a value to be committed later.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-types-__init__



# `prefect.types`

## Functions

### `check_variable_value` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/__init__.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_variable_value(value: object) -> object
```

### `cast_none_to_empty_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/__init__.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cast_none_to_empty_dict(value: Any) -> dict[str, Any]
```

### `validate_set_T_from_delim_string` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/__init__.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_set_T_from_delim_string(value: Union[str, T, set[T], None], type_: Any, delim: str | None = None) -> set[T]
```

"no-info" before validator useful in scooping env vars

e.g. `PREFECT_CLIENT_RETRY_EXTRA_CODES=429,502,503` -> `{429, 502, 503}`
e.g. `PREFECT_CLIENT_RETRY_EXTRA_CODES=429` -> `{429}`

### `parse_retry_delay_input` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/__init__.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_retry_delay_input(value: Any) -> Any
```

Parses various inputs (string, int, float, list) into a format suitable
for TaskRetryDelaySeconds (int, float, list\[float], or None).
Handles comma-separated strings for lists of delays.

### `convert_none_to_empty_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/__init__.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
convert_none_to_empty_dict(v: Optional[KeyValueLabels]) -> KeyValueLabels
```

## Classes

### `SecretDict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/__init__.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# entrypoint
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-types-entrypoint



# `prefect.types.entrypoint`

## Classes

### `EntrypointType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/entrypoint.py#L4" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Enum representing a entrypoint type.

File path entrypoints are in the format: `path/to/file.py:function_name`.
Module path entrypoints are in the format: `path.to.module.function_name`.


# names
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-types-names



# `prefect.types.names`

## Functions

### `raise_on_name_alphanumeric_dashes_only` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/names.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_on_name_alphanumeric_dashes_only(value: str | None, field_name: str = 'value') -> str | None
```

### `raise_on_name_alphanumeric_underscores_only` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/names.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_on_name_alphanumeric_underscores_only(value: str | None, field_name: str = 'value') -> str | None
```

### `raise_on_name_alphanumeric_dashes_underscores_only` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/names.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_on_name_alphanumeric_dashes_underscores_only(value: str, field_name: str = 'value') -> str
```

### `non_emptyish` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/names.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
non_emptyish(value: str) -> str
```

### `validate_uri` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/names.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_uri(value: str) -> str
```

Validate that a string is a valid URI with lowercase protocol.

### `validate_valid_asset_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/types/names.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_valid_asset_key(value: str) -> str
```

Validate asset key with character restrictions and length limit.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-__init__



# `prefect.utilities`

*This module is empty or contains only private/internal implementations.*


# annotations
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-annotations



# `prefect.utilities.annotations`

## Classes

### `BaseAnnotation` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Base class for Prefect annotation types.

Inherits from `tuple` for unpacking support in other tools.

**Methods:**

#### `rewrap` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
rewrap(self, value: T) -> Self
```

#### `unwrap` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unwrap(self) -> T
```

### `unmapped` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Wrapper for iterables.

Indicates that this input should be sent as-is to all runs created during a mapping
operation instead of being split.

### `allow_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Wrapper for states or futures.

Indicates that the upstream run for this input can be failed.

Generally, Prefect will not allow a downstream run to start if any of its inputs
are failed. This annotation allows you to opt into receiving a failed input
downstream.

If the input is from a failed run, the attached exception will be passed to your
function.

### `quote` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Simple wrapper to mark an expression as a different type so it will not be coerced
by Prefect. For example, if you want to return a state from a flow without having
the flow assume that state.

quote will also instruct prefect to ignore introspection of the wrapped object
when passed as flow or task parameter. Parameter introspection can be a
significant performance hit when the object is a large collection,
e.g. a large dictionary or DataFrame, and each element needs to be visited. This
will disable task dependency tracking for the wrapped object, but likely will
increase performance.

```
@task
def my_task(df):
    ...

@flow
def my_flow():
    my_task(quote(df))
```

**Methods:**

#### `unquote` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unquote(self) -> T
```

### `Quote` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `NotSet` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Singleton to distinguish `None` from a value that is not provided by the user.

### `freeze` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Wrapper for parameters in deployments.

Indicates that this parameter should be frozen in the UI and not editable
when creating flow runs from this deployment.

Example:

```python
@flow
def my_flow(customer_id: str):
    # flow logic

deployment = my_flow.deploy(parameters={"customer_id": freeze("customer123")})
```

**Methods:**

#### `unfreeze` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/annotations.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unfreeze(self) -> T
```

Return the unwrapped value.


# asyncutils
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-asyncutils



# `prefect.utilities.asyncutils`

Utilities for interoperability with async functions and workers from various contexts.

## Functions

### `get_thread_limiter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_thread_limiter() -> anyio.CapacityLimiter
```

### `is_async_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_async_fn(func: _SyncOrAsyncCallable[P, R]) -> TypeGuard[Callable[P, Coroutine[Any, Any, Any]]]
```

Returns `True` if a function returns a coroutine.

See [https://github.com/microsoft/pyright/issues/2142](https://github.com/microsoft/pyright/issues/2142) for an example use

### `is_async_gen_fn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_async_gen_fn(func: Callable[P, Any]) -> TypeGuard[Callable[P, AsyncGenerator[Any, Any]]]
```

Returns `True` if a function is an async generator.

### `create_task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_task(coroutine: Coroutine[Any, Any, R]) -> asyncio.Task[R]
```

Replacement for asyncio.create\_task that will ensure that tasks aren't
garbage collected before they complete. Allows for "fire and forget"
behavior in which tasks can be created and the application can move on.
Tasks can also be awaited normally.

See [https://docs.python.org/3/library/asyncio-task.html#asyncio.create\_task](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task)
for details (and essentially this implementation)

### `run_coro_as_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_coro_as_sync(coroutine: Coroutine[Any, Any, R]) -> Optional[R]
```

Runs a coroutine from a synchronous context, as if it were a synchronous
function.

The coroutine is scheduled to run in the "run sync" event loop, which is
running in its own thread and is started the first time it is needed. This
allows us to share objects like async httpx clients among all coroutines
running in the loop.

If run\_sync is called from within the run\_sync loop, it will run the
coroutine in a new thread, because otherwise a deadlock would occur. Note
that this behavior should not appear anywhere in the Prefect codebase or in
user code.

**Args:**

* `coroutine`: The coroutine to be run as a synchronous function.
* `force_new_thread`: If True, the coroutine will always be run in a new thread.
  Defaults to False.
* `wait_for_result`: If True, the function will wait for the coroutine to complete
  and return the result. If False, the function will submit the coroutine to the "run sync"
  event loop and return immediately, where it will eventually be run. Defaults to True.

**Returns:**

* The result of the coroutine if wait\_for\_result is True, otherwise None.

### `run_sync_in_worker_thread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_sync_in_worker_thread(__fn: Callable[P, R], *args: P.args, **kwargs: P.kwargs) -> R
```

Runs a sync function in a new worker thread so that the main thread's event loop
is not blocked.

Unlike the anyio function, this defaults to a cancellable thread and does not allow
passing arguments to the anyio function so users can pass kwargs to their function.

Note that cancellation of threads will not result in interrupted computation, the
thread may continue running — the outcome will just be ignored.

### `call_with_mark` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_with_mark(call: Callable[..., R]) -> R
```

### `run_async_from_worker_thread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_async_from_worker_thread(__fn: Callable[P, Awaitable[R]], *args: P.args, **kwargs: P.kwargs) -> R
```

Runs an async function in the main thread's event loop, blocking the worker
thread until completion

### `run_async_in_new_loop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_async_in_new_loop(__fn: Callable[P, Awaitable[R]], *args: P.args, **kwargs: P.kwargs) -> R
```

### `mark_as_worker_thread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
mark_as_worker_thread() -> None
```

### `in_async_worker_thread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
in_async_worker_thread() -> bool
```

### `in_async_main_thread` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
in_async_main_thread() -> bool
```

### `sync_compatible` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
sync_compatible(async_fn: Callable[P, Coroutine[Any, Any, R]]) -> Callable[P, Union[R, Coroutine[Any, Any, R]]]
```

Converts an async function into a dual async and sync function.

When the returned function is called, we will attempt to determine the best way
to enter the async function.

* If in a thread with a running event loop, we will return the coroutine for the
  caller to await. This is normal async behavior.
* If in a blocking worker thread with access to an event loop in another thread, we
  will submit the async method to the event loop.
* If we cannot find an event loop, we will create a new one and run the async method
  then tear down the loop.

Note: Type checkers will infer functions decorated with `@sync_compatible` are synchronous. If
you want to use the decorated function in an async context, you will need to ignore the types
and "cast" the return type to a coroutine. For example:

```
python result: Coroutine = sync_compatible(my_async_function)(arg1, arg2) # type: ignore
```

### `asyncnullcontext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L377" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asyncnullcontext(value: Optional[R] = None, *args: Any, **kwargs: Any) -> AsyncGenerator[Any, Optional[R]]
```

### `sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
sync(__async_fn: Callable[P, Awaitable[T]], *args: P.args, **kwargs: P.kwargs) -> T
```

Call an async function from a synchronous context. Block until completion.

If in an asynchronous context, we will run the code in a separate loop instead of
failing but a warning will be displayed since this is not recommended.

### `add_event_loop_shutdown_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L407" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_event_loop_shutdown_callback(coroutine_fn: Callable[[], Awaitable[Any]]) -> None
```

Adds a callback to the given callable on event loop closure. The callable must be
a coroutine function. It will be awaited when the current event loop is shutting
down.

Requires use of `asyncio.run()` which waits for async generator shutdown by
default or explicit call of `asyncio.shutdown_asyncgens()`. If the application
is entered with `asyncio.run_until_complete()` and the user calls
`asyncio.close()` without the generator shutdown call, this will not trigger
callbacks.

asyncio does not provided *any* other way to clean up a resource when the event
loop is about to close.

### `create_gather_task_group` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L525" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_gather_task_group() -> GatherTaskGroup
```

Create a new task group that gathers results

### `gather` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L533" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
gather(*calls: Callable[[], Coroutine[Any, Any, T]]) -> list[T]
```

Run calls concurrently and gather their results.

Unlike `asyncio.gather` this expects to receive *callables* not *coroutines*.
This matches `anyio` semantics.

## Classes

### `GatherIncomplete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L456" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Used to indicate retrieving gather results before completion

### `GatherTaskGroup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L460" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A task group that gathers results.

AnyIO does not include `gather` support. This class extends the `TaskGroup`
interface to allow simple gathering.

See [https://github.com/agronholm/anyio/issues/100](https://github.com/agronholm/anyio/issues/100)

This class should be instantiated with `create_gather_task_group`.

**Methods:**

#### `get_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L504" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_result(self, key: UUID) -> Any
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, func: object, *args: object) -> NoReturn
```

Since `start` returns the result of `task_status.started()` but here we must
return the key instead, we just won't support this method for now.

#### `start_soon` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L485" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_soon(self, func: Callable[[Unpack[PosArgsT]], Awaitable[Any]], *args: Unpack[PosArgsT]) -> UUID
```

### `LazySemaphore` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/asyncutils.py#L547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# callables
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-callables



# `prefect.utilities.callables`

Utilities for working with Python callables.

## Functions

### `get_call_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_call_parameters(fn: Callable[..., Any], call_args: tuple[Any, ...], call_kwargs: dict[str, Any], apply_defaults: bool = True) -> dict[str, Any]
```

Bind a call to a function to get parameter/value mapping. Default values on
the signature will be included if not overridden.

If the function has a `__prefect_self__` attribute, it will be included as
the first parameter. This attribute is set when Prefect decorates a bound
method, so this approach allows Prefect to work with bound methods in a way
that is consistent with how Python handles them (i.e. users don't have to
pass the instance argument to the method) while still making the implicit self
argument visible to all of Prefect's parameter machinery (such as cache key
functions).

Raises a ParameterBindError if the arguments/kwargs are not valid for the
function

### `get_parameter_defaults` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_parameter_defaults(fn: Callable[..., Any]) -> dict[str, Any]
```

Get default parameter values for a callable.

### `explode_variadic_parameter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
explode_variadic_parameter(fn: Callable[..., Any], parameters: dict[str, Any]) -> dict[str, Any]
```

Given a parameter dictionary, move any parameters stored in a variadic keyword
argument parameter (i.e. \*\*kwargs) into the top level.

Example:

```python
def foo(a, b, **kwargs):
    pass

parameters = {"a": 1, "b": 2, "kwargs": {"c": 3, "d": 4}}
explode_variadic_parameter(foo, parameters)
# {"a": 1, "b": 2, "c": 3, "d": 4}
```

### `collapse_variadic_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
collapse_variadic_parameters(fn: Callable[..., Any], parameters: dict[str, Any]) -> dict[str, Any]
```

Given a parameter dictionary, move any parameters stored not present in the
signature into the variadic keyword argument.

Example:

```python
def foo(a, b, **kwargs):
    pass

parameters = {"a": 1, "b": 2, "c": 3, "d": 4}
collapse_variadic_parameters(foo, parameters)
# {"a": 1, "b": 2, "kwargs": {"c": 3, "d": 4}}
```

### `parameters_to_args_kwargs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parameters_to_args_kwargs(fn: Callable[..., Any], parameters: dict[str, Any]) -> tuple[tuple[Any, ...], dict[str, Any]]
```

Convert a `parameters` dictionary to positional and keyword arguments

The function *must* have an identical signature to the original function or this
will return an empty tuple and dict.

### `call_with_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_with_parameters(fn: Callable[..., R], parameters: dict[str, Any]) -> R
```

Call a function with parameters extracted with `get_call_parameters`

The function *must* have an identical signature to the original function or this
will fail. If you need to send to a function with a different signature, extract
the args/kwargs using `parameters_to_positional_and_keyword` directly

### `cloudpickle_wrapped_call` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cloudpickle_wrapped_call(__fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Callable[[], bytes]
```

Serializes a function call using cloudpickle then returns a callable which will
execute that call and return a cloudpickle serialized return value

This is particularly useful for sending calls to libraries that only use the Python
built-in pickler (e.g. `anyio.to_process` and `multiprocessing`) but may require
a wider range of pickling support.

### `parameter_docstrings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parameter_docstrings(docstring: Optional[str]) -> dict[str, str]
```

Given a docstring in Google docstring format, parse the parameter section
and return a dictionary that maps parameter names to docstring.

**Args:**

* `docstring`: The function's docstring.

**Returns:**

* Mapping from parameter names to docstrings.

### `process_v1_params` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L282" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_v1_params(param: inspect.Parameter) -> tuple[str, Any, Any]
```

### `create_v1_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L313" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_v1_schema(name_: str, model_cfg: type[Any], model_fields: Optional[dict[str, Any]] = None) -> dict[str, Any]
```

### `parameter_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parameter_schema(fn: Callable[..., Any]) -> ParameterSchema
```

Given a function, generates an OpenAPI-compatible description
of the function's arguments, including:

* name
* typing information
* whether it is required
* a default value
* additional constraints (like possible enum values)

**Args:**

* `fn`: The function whose arguments will be serialized

**Returns:**

* the argument schema

### `parameter_schema_from_entrypoint` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L357" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parameter_schema_from_entrypoint(entrypoint: str) -> ParameterSchema
```

Generate a parameter schema from an entrypoint string.

Will load the source code of the function and extract the signature and docstring
to generate the schema.

Useful for generating a schema for a function when instantiating the function may
not be possible due to missing imports or other issues.

**Args:**

* `entrypoint`: A string representing the entrypoint to a function. The string
  should be in the format of `module.path.to.function\:do_stuff`.

**Returns:**

* The parameter schema for the function.

### `generate_parameter_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L391" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_parameter_schema(signature: inspect.Signature, docstrings: dict[str, str]) -> ParameterSchema
```

Generate a parameter schema from a function signature and docstrings.

To get a signature from a function, use `inspect.signature(fn)` or
`_generate_signature_from_source(source_code, func_name)`.

**Args:**

* `signature`: The function signature.
* `docstrings`: A dictionary mapping parameter names to docstrings.

**Returns:**

* The parameter schema.

### `raise_for_reserved_arguments` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L447" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_for_reserved_arguments(fn: Callable[..., Any], reserved_arguments: Iterable[str]) -> None
```

Raise a ReservedArgumentError if `fn` has any parameters that conflict
with the names contained in `reserved_arguments`.

### `expand_mapping_parameters` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L661" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
expand_mapping_parameters(func: Callable[..., Any], parameters: dict[str, Any]) -> list[dict[str, Any]]
```

Generates a list of call parameters to be used for individual calls in a mapping
operation.

**Args:**

* `func`: The function to be called
* `parameters`: A dictionary of parameters with iterables to be mapped over

**Returns:**

* A list of dictionaries to be used as parameters for each
  call in the mapping operation

## Classes

### `ParameterSchema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Simple data model corresponding to an OpenAPI `Schema`.

**Methods:**

#### `model_dump_for_openapi` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/callables.py#L247" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump_for_openapi(self) -> dict[str, Any]
```


# collections
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-collections



# `prefect.utilities.collections`

Utilities for extensions of and operations on Python collections.

## Functions

### `dict_to_flatdict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
dict_to_flatdict(dct: NestedDict[KT, VT]) -> dict[tuple[KT, ...], VT]
```

Converts a (nested) dictionary to a flattened representation.

Each key of the flat dict will be a CompoundKey tuple containing the "chain of keys"
for the corresponding value.

**Args:**

* `dct`: The dictionary to flatten

**Returns:**

* A flattened dict of the same type as dct

### `flatdict_to_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flatdict_to_dict(dct: dict[tuple[KT, ...], VT]) -> NestedDict[KT, VT]
```

Converts a flattened dictionary back to a nested dictionary.

**Args:**

* `dct`: The dictionary to be nested. Each key should be a tuple of keys
  as generated by `dict_to_flatdict`

Returns
A nested dict of the same type as dct

### `isiterable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
isiterable(obj: Any) -> bool
```

Return a boolean indicating if an object is iterable.

Excludes types that are iterable but typically used as singletons:

* str
* bytes
* IO objects

### `ensure_iterable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ensure_iterable(obj: Union[T, Iterable[T]]) -> Collection[T]
```

### `listrepr` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
listrepr(objs: Iterable[Any], sep: str = ' ') -> str
```

### `extract_instances` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
extract_instances(objects: Iterable[Any], types: Union[type[T], tuple[type[T], ...]] = object) -> Union[list[T], dict[type[T], list[T]]]
```

Extract objects from a file and returns a dict of type -> instances

**Args:**

* `objects`: An iterable of objects
* `types`: A type or tuple of types to extract, defaults to all objects

**Returns:**

* If a single type is given: a list of instances of that type
* If a tuple of types is given: a mapping of type to a list of instances

### `batched_iterable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
batched_iterable(iterable: Iterable[T], size: int) -> Generator[tuple[T, ...], None, None]
```

Yield batches of a certain size from an iterable

**Args:**

* `iterable`: An iterable
* `size`: The batch size to return

### `visit_collection` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
visit_collection(expr: Any, visit_fn: Union[Callable[[Any, dict[str, VT]], Any], Callable[[Any], Any]]) -> Optional[Any]
```

Visits and potentially transforms every element of an arbitrary Python collection.

If an element is a Python collection, it will be visited recursively. If an element
is not a collection, `visit_fn` will be called with the element. The return value of
`visit_fn` can be used to alter the element if `return_data` is set to `True`.

Note:

* When `return_data` is `True`, a copy of each collection is created only if
  `visit_fn` modifies an element within that collection. This approach minimizes
  performance penalties by avoiding unnecessary copying.
* When `return_data` is `False`, no copies are created, and only side effects from
  `visit_fn` are applied. This mode is faster and should be used when no transformation
  of the collection is required, because it never has to copy any data.

Supported types:

* List (including iterators)
* Tuple
* Set
* Dict (note: keys are also visited recursively)
* Dataclass
* Pydantic model
* Prefect annotations

Note that visit\_collection will not consume generators or async generators, as it would prevent
the caller from iterating over them.

**Args:**

* `expr`: A Python object or expression.
* `visit_fn`: A function
  that will be applied to every non-collection element of `expr`. The function can
  accept one or two arguments. If two arguments are accepted, the second argument
  will be the context dictionary.
* `return_data`: If `True`, a copy of `expr` containing data modified by `visit_fn`
  will be returned. This is slower than `return_data=False` (the default).
* `max_depth`: Controls the depth of recursive visitation. If set to zero, no
  recursion will occur. If set to a positive integer `N`, visitation will only
  descend to `N` layers deep. If set to any negative integer, no limit will be
  enforced and recursion will continue until terminal items are reached. By
  default, recursion is unlimited.
* `context`: An optional dictionary. If passed, the context will be sent
  to each call to the `visit_fn`. The context can be mutated by each visitor and
  will be available for later visits to expressions at the given depth. Values
  will not be available "up" a level from a given expression.
  The context will be automatically populated with an 'annotation' key when
  visiting collections within a `BaseAnnotation` type. This requires the caller to
  pass `context={}` and will not be activated by default.
* `remove_annotations`: If set, annotations will be replaced by their contents. By
  default, annotations are preserved but their contents are visited.
* `_seen`: A set of object ids that have already been visited. This
  prevents infinite recursion when visiting recursive data structures.

**Returns:**

* The modified collection if `return_data` is `True`, otherwise `None`.

### `remove_nested_keys` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L554" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
remove_nested_keys(keys_to_remove: list[HashableT], obj: Union[NestedDict[HashableT, VT], Any]) -> Union[NestedDict[HashableT, VT], Any]
```

Recurses a dictionary returns a copy without all keys that match an entry in
`key_to_remove`. Return `obj` unchanged if not a dictionary.

**Args:**

* `keys_to_remove`: A list of keys to remove from obj obj: The object to remove keys
  from.

**Returns:**

* `obj` without keys matching an entry in `keys_to_remove` if `obj` is a
  dictionary. `obj` if `obj` is not a dictionary.

### `distinct` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L588" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
distinct(iterable: Iterable[Union[T, HashableT]], key: Optional[Callable[[T], Hashable]] = None) -> Iterator[Union[T, HashableT]]
```

### `get_from_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L618" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_from_dict(dct: NestedDict[str, VT], keys: Union[str, list[str]], default: Optional[R] = None) -> Union[VT, R, None]
```

Fetch a value from a nested dictionary or list using a sequence of keys.

This function allows to fetch a value from a deeply nested structure
of dictionaries and lists using either a dot-separated string or a list
of keys. If a requested key does not exist, the function returns the
provided default value.

**Args:**

* `dct`: The nested dictionary or list from which to fetch the value.
* `keys`: The sequence of keys to use for access. Can be a
  dot-separated string or a list of keys. List indices can be included
  in the sequence as either integer keys or as string indices in square
  brackets.
* `default`: The default value to return if the requested key path does not
  exist. Defaults to None.

**Returns:**

* The fetched value if the key exists, or the default value if it does not.

Examples:

```python
get_from_dict({'a': {'b': {'c': [1, 2, 3, 4]}}}, 'a.b.c[1]') # 2
get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, ['a', 'b', 1, 'c', 1]) # 2
get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, 'a.b.1.c.2', 'default') # 'default'
```

### `set_in_dict` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L667" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set_in_dict(dct: NestedDict[str, VT], keys: Union[str, list[str]], value: VT) -> None
```

Sets a value in a nested dictionary using a sequence of keys.

This function allows to set a value in a deeply nested structure
of dictionaries and lists using either a dot-separated string or a list
of keys. If a requested key does not exist, the function will create it as
a new dictionary.

**Args:**

* `dct`: The dictionary to set the value in.
* `keys`: The sequence of keys to use for access. Can be a
  dot-separated string or a list of keys.
* `value`: The value to set in the dictionary.

**Returns:**

* The modified dictionary with the value set at the specified key path.

**Raises:**

* `KeyError`: If the key path exists and is not a dictionary.

### `deep_merge` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L701" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deep_merge(dct: NestedDict[str, VT1], merge: NestedDict[str, VT2]) -> NestedDict[str, Union[VT1, VT2]]
```

Recursively merges `merge` into `dct`.

**Args:**

* `dct`: The dictionary to merge into.
* `merge`: The dictionary to merge from.

**Returns:**

* A new dictionary with the merged contents.

### `deep_merge_dicts` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L728" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
deep_merge_dicts(*dicts: NestedDict[str, Any]) -> NestedDict[str, Any]
```

Recursively merges multiple dictionaries.

**Args:**

* `dicts`: The dictionaries to merge.

**Returns:**

* A new dictionary with the merged contents.

## Classes

### `AutoEnum` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An enum class that automatically generates value from variable names.

This guards against common errors where variable names are updated but values are
not.

In addition, because AutoEnums inherit from `str`, they are automatically
JSON-serializable.

See [https://docs.python.org/3/library/enum.html#using-automatic-values](https://docs.python.org/3/library/enum.html#using-automatic-values)

**Methods:**

#### `auto` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
auto() -> str
```

Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`

### `StopVisiting` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/collections.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A special exception used to stop recursive visits in `visit_collection`.

When raised, the expression is returned without modification and recursive visits
in that path will end.


# compat
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-compat



# `prefect.utilities.compat`

Utilities for Python version compatibility


# context
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-context



# `prefect.utilities.context`

## Functions

### `temporary_context` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/context.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_context(context: Context) -> Generator[None, Any, None]
```

### `get_task_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/context.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_run_id() -> Optional[UUID]
```

### `get_flow_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/context.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_flow_run_id() -> Optional[UUID]
```

### `get_task_and_flow_run_ids` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/context.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_and_flow_run_ids() -> tuple[Optional[UUID], Optional[UUID]]
```

Get the task run and flow run ids from the context, if available.

**Returns:**

* tuple\[Optional\[UUID], Optional\[UUID]]: a tuple of the task run id and flow run id


# dispatch
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-dispatch



# `prefect.utilities.dispatch`

Provides methods for performing dynamic dispatch for actions on base type to one of its
subtypes.

Example:

```python
@register_base_type
class Base:
    @classmethod
    def __dispatch_key__(cls):
        return cls.__name__.lower()


class Foo(Base):
    ...

key = get_dispatch_key(Foo)  # 'foo'
lookup_type(Base, key) # Foo
```

## Functions

### `get_registry_for_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dispatch.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_registry_for_type(cls: T) -> Optional[dict[str, T]]
```

Get the first matching registry for a class or any of its base classes.

If not found, `None` is returned.

### `get_dispatch_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dispatch.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_dispatch_key(cls_or_instance: Any, allow_missing: bool = False) -> Optional[str]
```

Retrieve the unique dispatch key for a class type or instance.

This key is defined at the `__dispatch_key__` attribute. If it is a callable, it
will be resolved.

If `allow_missing` is `False`, an exception will be raised if the attribute is not
defined or the key is null. If `True`, `None` will be returned in these cases.

### `register_base_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dispatch.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_base_type(cls: T) -> T
```

Register a base type allowing child types to be registered for dispatch with
`register_type`.

The base class may or may not define a `__dispatch_key__` to allow lookups of the
base type.

### `register_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dispatch.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type(cls: T) -> T
```

Register a type for lookup with dispatch.

The type or one of its parents must define a unique `__dispatch_key__`.

One of the classes base types must be registered using `register_base_type`.

### `lookup_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dispatch.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
lookup_type(cls: T, dispatch_key: str) -> T
```

Look up a dispatch key in the type registry for the given class.


# dockerutils
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-dockerutils



# `prefect.utilities.dockerutils`

## Functions

### `python_version_minor` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
python_version_minor() -> str
```

### `python_version_micro` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
python_version_micro() -> str
```

### `get_prefect_image_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_prefect_image_name(prefect_version: Optional[str] = None, python_version: Optional[str] = None, flavor: Optional[str] = None) -> str
```

Get the Prefect image name matching the current Prefect and Python versions.

**Args:**

* `prefect_version`: An optional override for the Prefect version.
* `python_version`: An optional override for the Python version; must be at the
  minor level e.g. '3.9'.
* `flavor`: An optional alternative image flavor to build, like 'conda'

### `silence_docker_warnings` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
silence_docker_warnings() -> Generator[None, None, None]
```

### `docker_client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
docker_client() -> Generator['DockerClient', None, None]
```

Get the environmentally-configured Docker client

### `build_image` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_image(context: Path, dockerfile: str = 'Dockerfile', tag: Optional[str] = None, pull: bool = False, platform: Optional[str] = None, stream_progress_to: Optional[TextIO] = None, **kwargs: Any) -> str
```

Builds a Docker image, returning the image ID

**Args:**

* `context`: the root directory for the Docker build context
* `dockerfile`: the path to the Dockerfile, relative to the context
* `tag`: the tag to give this image
* `pull`: True to pull the base image during the build
* `stream_progress_to`: an optional stream (like sys.stdout, or an io.TextIO) that
  will collect the build output as it is reported by Docker

**Returns:**

* The image ID

### `push_image` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L411" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
push_image(image_id: str, registry_url: str, name: str, tag: Optional[str] = None, stream_progress_to: Optional[TextIO] = None) -> str
```

Pushes a local image to a Docker registry, returning the registry-qualified tag
for that image

This assumes that the environment's Docker daemon is already authenticated to the
given registry, and currently makes no attempt to authenticate.

**Args:**

* `image_id`: a Docker image ID
* `registry_url`: the URL of a Docker registry
* `name`: the name of this image
* `tag`: the tag to give this image (defaults to a short representation of
  the image's ID)
* `stream_progress_to`: an optional stream (like sys.stdout, or an io.TextIO) that
  will collect the build output as it is reported by Docker

**Returns:**

* A registry-qualified tag, like my-registry.example.com/my-image:abcdefg

### `to_run_command` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L468" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_run_command(command: list[str]) -> str
```

Convert a process-style list of command arguments to a single Dockerfile RUN
instruction.

### `parse_image_tag` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L492" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_image_tag(name: str) -> tuple[str, Optional[str]]
```

Parse Docker Image String

* If a tag or digest exists, this function parses and returns the image registry and tag/digest,
  separately as a tuple.
  * Example 1: 'prefecthq/prefect:latest' -> ('prefecthq/prefect', 'latest')
  * Example 2: 'hostname.io:5050/folder/subfolder:latest' -> ('hostname.io:5050/folder/subfolder', 'latest')
  * Example 3: 'prefecthq/prefect\@sha256:abc123' -> ('prefecthq/prefect', 'sha256:abc123')
* Supports parsing Docker Image strings that follow Docker Image Specification v1.1.0
  * Image building tools typically enforce this standard

**Args:**

* `name`: Name of Docker Image

### `split_repository_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
split_repository_path(repository_path: str) -> tuple[Optional[str], str]
```

Splits a Docker repository path into its namespace and repository components.

**Args:**

* `repository_path`: The Docker repository path to split.

**Returns:**

* Tuple\[Optional\[str], str]: A tuple containing the namespace and repository components.
* namespace (Optional\[str]): The Docker namespace, combining the registry and organization. None if not present.
* repository (Optionals\[str]): The repository name.

### `format_outlier_version_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L571" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
format_outlier_version_name(version: str) -> str
```

Formats outlier docker version names to pass `packaging.version.parse` validation

* Current cases are simple, but creates stub for more complicated formatting if eventually needed.
* Example outlier versions that throw a parsing exception:
  * "20.10.0-ce" (variant of community edition label)
  * "20.10.0-ee" (variant of enterprise edition label)

**Args:**

* `version`: raw docker version value

**Returns:**

* value that can pass `packaging.version.parse` validation

### `generate_default_dockerfile` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_default_dockerfile(context: Optional[Path] = None)
```

Generates a default Dockerfile used for deploying flows. The Dockerfile is written
to a temporary file and yielded. The temporary file is removed after the context
manager exits.

**Args:**

* `- context`: The context to use for the Dockerfile. Defaults to
  the current working directory.

## Classes

### `BuildError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a Docker build fails

### `ImageBuilder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

An interface for preparing Docker build contexts and building images

**Methods:**

#### `add_line` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_line(self, line: str) -> None
```

Add a line to this image's Dockerfile

#### `add_lines` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L268" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_lines(self, lines: Iterable[str]) -> None
```

Add lines to this image's Dockerfile

#### `assert_has_file` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_has_file(self, source: Path, container_path: PurePosixPath) -> None
```

Asserts that the given file or directory will be copied into the container
at the given path

#### `assert_has_line` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L338" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_has_line(self, line: str) -> None
```

Asserts that the given line is in the Dockerfile

#### `assert_line_absent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L348" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_line_absent(self, line: str) -> None
```

Asserts that the given line is absent from the Dockerfile

#### `assert_line_after` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_line_after(self, second: str, first: str) -> None
```

Asserts that the second line appears after the first line

#### `assert_line_before` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L368" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
assert_line_before(self, first: str, second: str) -> None
```

Asserts that the first line appears before the second line

#### `build` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L309" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build(self, pull: bool = False, stream_progress_to: Optional[TextIO] = None) -> str
```

Build the Docker image from the current state of the ImageBuilder

**Args:**

* `pull`: True to pull the base image during the build
* `stream_progress_to`: an optional stream (like sys.stdout, or an io.TextIO)
  that will collect the build output as it is reported by Docker

**Returns:**

* The image ID

#### `copy` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
copy(self, source: Union[str, Path], destination: Union[str, PurePosixPath]) -> None
```

Copy a file to this image

#### `write_text` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
write_text(self, text: str, destination: Union[str, PurePosixPath]) -> None
```

### `PushError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/dockerutils.py#L406" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised when a Docker image push fails


# engine
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-engine



# `prefect.utilities.engine`

## Functions

### `collect_task_run_inputs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
collect_task_run_inputs(expr: Any, max_depth: int = -1) -> set[Union[TaskRunResult, FlowRunResult]]
```

This function recurses through an expression to generate a set of any discernible
task run inputs it finds in the data structure. It produces a set of all inputs
found.

Examples:

```python
task_inputs = {
    k: await collect_task_run_inputs(v) for k, v in parameters.items()
 }
```

### `collect_task_run_inputs_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
collect_task_run_inputs_sync(expr: Any, future_cls: Any = PrefectFuture, max_depth: int = -1) -> set[Union[TaskRunResult, FlowRunResult]]
```

This function recurses through an expression to generate a set of any discernible
task run inputs it finds in the data structure. It produces a set of all inputs
found.

**Examples:**

```python
task_inputs = {
    k: collect_task_run_inputs_sync(v) for k, v in parameters.items()
 }
```

### `capture_sigterm` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
capture_sigterm() -> Generator[None, Any, None]
```

### `resolve_inputs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_inputs(parameters: dict[str, Any], return_data: bool = True, max_depth: int = -1) -> dict[str, Any]
```

Resolve any `Quote`, `PrefectFuture`, or `State` types nested in parameters into
data.

**Returns:**

* A copy of the parameters with resolved data

**Raises:**

* `UpstreamTaskError`: If any of the upstream states are not `COMPLETED`

### `propose_state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
propose_state(client: 'PrefectClient', state: State[Any], flow_run_id: UUID, force: bool = False) -> State[Any]
```

Propose a new state for a flow run, invoking Prefect orchestration logic.

If the proposed state is accepted, the provided `state` will be augmented with
details and returned.

If the proposed state is rejected, a new state returned by the Prefect API will be
returned.

If the proposed state results in a WAIT instruction from the Prefect API, the
function will sleep and attempt to propose the state again.

If the proposed state results in an ABORT instruction from the Prefect API, an
error will be raised.

**Args:**

* `state`: a new state for a flow run
* `flow_run_id`: an optional flow run id, used when proposing flow run states

**Returns:**

* a State model representation of the flow run state

**Raises:**

* `prefect.exceptions.Abort`: if an ABORT instruction is received from
  the Prefect API

### `propose_state_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L413" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
propose_state_sync(client: 'SyncPrefectClient', state: State[Any], flow_run_id: UUID, force: bool = False) -> State[Any]
```

Propose a new state for a flow run, invoking Prefect orchestration logic.

If the proposed state is accepted, the provided `state` will be augmented with
details and returned.

If the proposed state is rejected, a new state returned by the Prefect API will be
returned.

If the proposed state results in a WAIT instruction from the Prefect API, the
function will sleep and attempt to propose the state again.

If the proposed state results in an ABORT instruction from the Prefect API, an
error will be raised.

**Args:**

* `state`: a new state for the flow run
* `flow_run_id`: an optional flow run id, used when proposing flow run states

**Returns:**

* a State model representation of the flow run state

**Raises:**

* `ValueError`: if flow\_run\_id is not provided
* `prefect.exceptions.Abort`: if an ABORT instruction is received from
  the Prefect API

### `get_state_for_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_state_for_result(obj: Any) -> Optional[tuple[State, RunType]]
```

Get the state related to a result object.

`link_state_to_result` must have been called first.

### `link_state_to_flow_run_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L518" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
link_state_to_flow_run_result(state: State, result: Any) -> None
```

Creates a link between a state and flow run result

### `link_state_to_task_run_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L523" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
link_state_to_task_run_result(state: State, result: Any) -> None
```

Creates a link between a state and task run result

### `link_state_to_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L528" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
link_state_to_result(state: State, result: Any, run_type: RunType) -> None
```

Caches a link between a state and a result and its components using
the `id` of the components to map to the state. The cache is persisted to the
current flow run context since task relationships are limited to within a flow run.

This allows dependency tracking to occur when results are passed around.
Note: Because `id` is used, we cannot cache links between singleton objects.

We only cache the relationship between components 1-layer deep.
Example:
Given the result \[1, \["a","b"], ("c",)], the following elements will be
mapped to the state:

* \[1, \["a","b"], ("c",)]
* \["a","b"]
* ("c",)

Note: the int `1` will not be mapped to the state because it is a singleton.

Other Notes:
We do not hash the result because:

* If changes are made to the object in the flow between task calls, we can still
  track that they are related.
* Hashing can be expensive.
* Not all objects are hashable.

We do not set an attribute, e.g. `__prefect_state__`, on the result because:

* Mutating user's objects is dangerous.
* Unrelated equality comparisons can break unexpectedly.
* The field can be preserved on copy.
* We cannot set this attribute on Python built-ins.

### `should_log_prints` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
should_log_prints(flow_or_task: Union['Flow[..., Any]', 'Task[..., Any]']) -> bool
```

### `check_api_reachable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L601" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
check_api_reachable(client: 'PrefectClient', fail_message: str) -> None
```

### `emit_task_run_state_change_event` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L619" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
emit_task_run_state_change_event(task_run: TaskRun, initial_state: Optional[State[Any]], validated_state: State[Any], follows: Optional[Event] = None) -> Optional[Event]
```

### `resolve_to_final_result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L710" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_to_final_result(expr: Any, context: dict[str, Any]) -> Any
```

Resolve any `PrefectFuture`, or `State` types nested in parameters into
data. Designed to be use with `visit_collection`.

### `resolve_inputs_sync` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/engine.py#L781" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_inputs_sync(parameters: dict[str, Any], return_data: bool = True, max_depth: int = -1) -> dict[str, Any]
```

Resolve any `Quote`, `PrefectFuture`, or `State` types nested in parameters into
data.

**Returns:**

* A copy of the parameters with resolved data

**Raises:**

* `UpstreamTaskError`: If any of the upstream states are not `COMPLETED`


# filesystem
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-filesystem



# `prefect.utilities.filesystem`

Utilities for working with file systems

## Functions

### `create_default_ignore_file` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_default_ignore_file(path: str) -> bool
```

Creates default ignore file in the provided path if one does not already exist; returns boolean specifying
whether a file was created.

### `filter_files` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filter_files(root: str = '.', ignore_patterns: Optional[Iterable[AnyStr]] = None, include_dirs: bool = True) -> set[str]
```

This function accepts a root directory path and a list of file patterns to ignore, and returns
a list of files that excludes those that should be ignored.

The specification matches that of [.gitignore files](https://git-scm.com/docs/gitignore).

### `tmpchdir` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
tmpchdir(path: str)
```

Change current-working directories for the duration of the context,
with special handling for UNC paths on Windows.

### `filename` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
filename(path: str) -> str
```

Extract the file name from a path with remote file system support

### `is_local_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_local_path(path: Union[str, pathlib.Path, Any]) -> bool
```

Check if the given path points to a local or remote file system

### `to_display_path` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_display_path(path: Union[pathlib.Path, str], relative_to: Optional[Union[pathlib.Path, str]] = None) -> str
```

Convert a path to a displayable path. The absolute path or relative path to the
current (or given) directory will be returned, whichever is shorter.

### `relative_path_to_current_platform` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
relative_path_to_current_platform(path_str: str) -> Path
```

Converts a relative path generated on any platform to a relative path for the
current platform.

### `get_open_file_limit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/filesystem.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_open_file_limit() -> int
```

Get the maximum number of open files allowed for the current process


# generics
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-generics



# `prefect.utilities.generics`

## Functions

### `validate_list` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/generics.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_list(model: type[T], input: Any) -> list[T]
```


# hashing
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-hashing



# `prefect.utilities.hashing`

## Functions

### `stable_hash` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/hashing.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stable_hash(*args: Union[str, bytes]) -> str
```

Given some arguments, produces a stable 64-bit hash of their contents.

Supports bytes and strings. Strings will be UTF-8 encoded.

**Args:**

* `*args`: Items to include in the hash.
* `hash_algo`: Hash algorithm from hashlib to use.

**Returns:**

* A hex hash.

### `file_hash` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/hashing.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
file_hash(path: str, hash_algo: Callable[..., Any] = _md5) -> str
```

Given a path to a file, produces a stable hash of the file contents.

**Args:**

* `path`: the path to a file
* `hash_algo`: Hash algorithm from hashlib to use.

**Returns:**

* a hash of the file contents

### `hash_objects` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/hashing.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hash_objects(*args: Any, **kwargs: Any) -> Optional[str]
```

Attempt to hash objects by dumping to JSON or serializing with cloudpickle.

**Args:**

* `*args`: Positional arguments to hash
* `hash_algo`: Hash algorithm to use
* `raise_on_failure`: If True, raise exceptions instead of returning None
* `**kwargs`: Keyword arguments to hash

**Returns:**

* A hash string or None if hashing failed

**Raises:**

* `HashError`: If objects cannot be hashed and raise\_on\_failure is True


# importtools
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-importtools



# `prefect.utilities.importtools`

## Functions

### `to_qualified_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_qualified_name(obj: Any) -> str
```

Given an object, returns its fully-qualified name: a string that represents its
Python import path.

**Args:**

* `obj`: an importable Python object

**Returns:**

* the qualified name

### `from_qualified_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_qualified_name(name: str) -> Any
```

Import an object given a fully-qualified name.

**Args:**

* `name`: The fully-qualified name of the object to import.

**Returns:**

* the imported object

**Examples:**

```python
obj = from_qualified_name("random.randint")
import random
obj == random.randint
# True
```

### `load_script_as_module` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_script_as_module(path: str) -> ModuleType
```

Execute a script at the given path.

Sets the module name to a unique identifier to ensure thread safety.
Uses a lock to safely modify sys.path for relative imports.

If an exception occurs during execution of the script, a
`prefect.exceptions.ScriptError` is created to wrap the exception and raised.

### `load_module` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_module(module_name: str) -> ModuleType
```

Import a module with support for relative imports within the module.

### `import_object` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
import_object(import_path: str) -> Any
```

Load an object from an import path.

Import paths can be formatted as one of:

* module.object
* module:object
* /path/to/script.py:object
* module:object.method
* /path/to/script.py:object.method

This function is not thread safe as it modifies the 'sys' module during execution.

### `lazy_import` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
lazy_import(name: str, error_on_import: bool = False, help_message: Optional[str] = None) -> ModuleType
```

Create a lazily-imported module to use in place of the module of the given name.
Use this to retain module-level imports for libraries that we don't want to
actually import until they are needed.

NOTE: Lazy-loading a subpackage can cause the subpackage to be imported
twice if another non-lazy import also imports the subpackage. For example,
using both `lazy_import("docker.errors")` and `import docker.errors` in the
same codebase will import `docker.errors` twice and can lead to unexpected
behavior, e.g. type check failures and import-time side effects running
twice.

Adapted from the [Python documentation][1] and [lazy\_loader][2]

[1]: https://docs.python.org/3/library/importlib.html#implementing-lazy-imports

[2]: https://github.com/scientific-python/lazy_loader

### `safe_load_namespace` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
safe_load_namespace(source_code: str, filepath: Optional[str] = None) -> dict[str, Any]
```

Safely load a namespace from source code, optionally handling relative imports.

If a `filepath` is provided, `sys.path` is modified to support relative imports.
Changes to `sys.path` are reverted after completion, but this function is not thread safe
and use of it in threaded contexts may result in undesirable behavior.

**Args:**

* `source_code`: The source code to load
* `filepath`: Optional file path of the source code. If provided, enables relative imports.

**Returns:**

* The namespace loaded from the source code.

## Classes

### `DelayedImportErrorModule` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A fake module returned by `lazy_import` when the module cannot be found. When any
of the module's attributes are accessed, we will throw a `ModuleNotFoundError`.

Adapted from [lazy\_loader][1]

[1]: https://github.com/scientific-python/lazy_loader

### `AliasedModuleDefinition` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A definition for the `AliasedModuleFinder`.

**Args:**

* `alias`: The import name to create
* `real`: The import name of the module to reference for the alias
* `callback`: A function to call when the alias module is loaded

### `AliasedModuleFinder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L269" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `find_spec` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
find_spec(self, fullname: str, path: Optional[Sequence[str]] = None, target: Optional[ModuleType] = None) -> Optional[ModuleSpec]
```

The fullname is the imported path, e.g. "foo.bar". If there is an alias "phi"
for "foo" then on import of "phi.bar" we will find the spec for "foo.bar" and
create a new spec for "phi.bar" that points to "foo.bar".

### `AliasedModuleLoader` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L303" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `exec_module` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/importtools.py#L314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exec_module(self, module: ModuleType) -> None
```


# math
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-math



# `prefect.utilities.math`

## Functions

### `poisson_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/math.py#L5" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
poisson_interval(average_interval: float, lower: float = 0, upper: float = 1) -> float
```

Generates an "inter-arrival time" for a Poisson process.

Draws a random variable from an exponential distribution using the inverse-CDF
method. Can optionally be passed a lower and upper bound between (0, 1] to clamp
the potential output values.

### `exponential_cdf` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/math.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exponential_cdf(x: float, average_interval: float) -> float
```

### `lower_clamp_multiple` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/math.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
lower_clamp_multiple(k: float) -> float
```

Computes a lower clamp multiple that can be used to bound a random variate drawn
from an exponential distribution.

Given an upper clamp multiple `k` (and corresponding upper bound k \* average\_interval),
this function computes a lower clamp multiple `c` (corresponding to a lower bound
c \* average\_interval) where the probability mass between the lower bound and the
median is equal to the probability mass between the median and the upper bound.

### `clamped_poisson_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/math.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clamped_poisson_interval(average_interval: float, clamping_factor: float = 0.3) -> float
```

Bounds Poisson "inter-arrival times" to a range defined by the clamping factor.

The upper bound for this random variate is: average\_interval \* (1 + clamping\_factor).
A lower bound is picked so that the average interval remains approximately fixed.

### `bounded_poisson_interval` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/math.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
bounded_poisson_interval(lower_bound: float, upper_bound: float) -> float
```

Bounds Poisson "inter-arrival times" to a range.

Unlike `clamped_poisson_interval` this does not take a target average interval.
Instead, the interval is predetermined and the average is calculated as their
midpoint. This allows Poisson intervals to be used in cases where a lower bound
must be enforced.


# names
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-names



# `prefect.utilities.names`

## Functions

### `generate_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/names.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_slug(n_words: int) -> str
```

Generates a random slug.

**Args:**

* `- n_words`: the number of words in the slug

### `obfuscate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/names.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
obfuscate(s: Any, show_tail: bool = False) -> str
```

Obfuscates any data type's string representation. See `obfuscate_string`.

### `obfuscate_string` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/names.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
obfuscate_string(s: str, show_tail: bool = False) -> str
```

Obfuscates a string by returning a new string of 8 characters. If the input
string is longer than 10 characters and show\_tail is True, then up to 4 of
its final characters will become final characters of the obfuscated string;
all other characters are "\*".

"abc"      -> "********"
"abcdefgh" -> "********"
"abcdefghijk" -> "\*\*\*\*\*\*\*k"
"abcdefghijklmnopqrs" -> "\*\*\*\*pqrs"


# processutils
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-processutils



# `prefect.utilities.processutils`

## Functions

### `open_process` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
open_process(command: list[str], **kwargs: Any) -> AsyncGenerator[anyio.abc.Process, Any]
```

Like `anyio.open_process` but with:

* Support for Windows command joining
* Termination of the process on exception during yield
* Forced cleanup of process resources during cancellation

### `run_process` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_process(command: list[str], **kwargs: Any) -> anyio.abc.Process
```

Like `anyio.run_process` but with:

* Use of our `open_process` utility to ensure resources are cleaned up
* Simple `stream_output` support to connect the subprocess to the parent stdout/err
* Support for submission with `TaskGroup.start` marking as 'started' after the
  process has been created. When used, the PID is returned to the task status.

### `consume_process_output` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
consume_process_output(process: anyio.abc.Process, stdout_sink: Optional[TextSink[str]] = None, stderr_sink: Optional[TextSink[str]] = None) -> None
```

### `stream_text` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L352" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stream_text(source: TextReceiveStream, *sinks: Optional[TextSink[str]]) -> None
```

### `forward_signal_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L383" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forward_signal_handler(pid: int, signum: int, *signums: int) -> None
```

Forward subsequent signum events (e.g. interrupts) to respective signums.

### `setup_signal_handlers_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_signal_handlers_server(pid: int, process_name: str, print_fn: PrintFn) -> None
```

Handle interrupts of the server gracefully.

### `setup_signal_handlers_agent` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L437" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_signal_handlers_agent(pid: int, process_name: str, print_fn: PrintFn) -> None
```

Handle interrupts of the agent gracefully.

### `setup_signal_handlers_worker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L455" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_signal_handlers_worker(pid: int, process_name: str, print_fn: PrintFn) -> None
```

Handle interrupts of workers gracefully.

### `get_sys_executable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/processutils.py#L475" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_sys_executable() -> str
```


# pydantic
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-pydantic



# `prefect.utilities.pydantic`

## Functions

### `add_cloudpickle_reduction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_cloudpickle_reduction(__model_cls: Optional[type[M]] = None, **kwargs: Any) -> Union[type[M], Callable[[type[M]], type[M]]]
```

Adds a `__reducer__` to the given class that ensures it is cloudpickle compatible.

Workaround for issues with cloudpickle when using cythonized pydantic which
throws exceptions when attempting to pickle the class which has "compiled"
validator methods dynamically attached to it.

We cannot define this utility in the model class itself because the class is the
type that contains unserializable methods.

Any model using some features of Pydantic (e.g. `Path` validation) with a Cython
compiled Pydantic installation may encounter pickling issues.

See related issue at [https://github.com/cloudpipe/cloudpickle/issues/408](https://github.com/cloudpipe/cloudpickle/issues/408)

### `get_class_fields_only` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_class_fields_only(model: type[BaseModel]) -> set[str]
```

Gets all the field names defined on the model class but not any parent classes.
Any fields that are on the parent but redefined on the subclass are included.

### `add_type_dispatch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_type_dispatch(model_cls: type[M]) -> type[M]
```

Extend a Pydantic model to add a 'type' field that is used as a discriminator field
to dynamically determine the subtype that when deserializing models.

This allows automatic resolution to subtypes of the decorated model.

If a type field already exists, it should be a string literal field that has a
constant value for each subclass. The default value of this field will be used as
the dispatch key.

If a type field does not exist, one will be added. In this case, the value of the
field will be set to the value of the `__dispatch_key__`. The base class should
define a `__dispatch_key__` class method that is used to determine the unique key
for each subclass. Alternatively, each subclass can define the `__dispatch_key__`
as a string literal.

The base class must not define a 'type' field. If it is not desirable to add a field
to the model and the dispatch key can be tracked separately, the lower level
utilities in `prefect.utilities.dispatch` should be used directly.

### `custom_pydantic_encoder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
custom_pydantic_encoder(type_encoders: dict[Any, Callable[[type[Any]], Any]], obj: Any) -> Any
```

### `parse_obj_as` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_obj_as(type_: type[T], data: Any, mode: Literal['python', 'json', 'strings'] = 'python') -> T
```

Parse a given data structure as a Pydantic model via `TypeAdapter`.

Read more about `TypeAdapter` [here](https://docs.pydantic.dev/latest/concepts/type_adapter/).

**Args:**

* `type_`: The type to parse the data as.
* `data`: The data to be parsed.
* `mode`: The mode to use for parsing, either `python`, `json`, or `strings`.
  Defaults to `python`, where `data` should be a Python object (e.g. `dict`).

**Returns:**

* The parsed `data` as the given `type_`.

### `handle_secret_render` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L343" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle_secret_render(value: object, context: dict[str, Any]) -> object
```

## Classes

### `PartialModel` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A utility for creating a Pydantic model in several steps.

Fields may be set at initialization, via attribute assignment, or at finalization
when the concrete model is returned.

Pydantic validation does not occur until finalization.

Each field can only be set once and a `ValueError` will be raised on assignment if
a field already has a value.

**Methods:**

#### `finalize` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
finalize(self, **kwargs: Any) -> M
```

#### `raise_if_already_set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_if_already_set(self, name: str) -> None
```

#### `raise_if_not_in_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/pydantic.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
raise_if_not_in_model(self, name: str) -> None
```


# render_swagger
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-render_swagger



# `prefect.utilities.render_swagger`

## Functions

### `swagger_lib` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/render_swagger.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
swagger_lib(config: MkDocsConfig) -> dict[str, Any]
```

Provides the actual swagger library used

## Classes

### `SwaggerPlugin` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/render_swagger.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `on_page_markdown` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/render_swagger.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_page_markdown() -> Optional[str]
```


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-schema_tools-__init__



# `prefect.utilities.schema_tools`

*This module is empty or contains only private/internal implementations.*


# hydration
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-schema_tools-hydration



# `prefect.utilities.schema_tools.hydration`

## Functions

### `handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handler(kind: PrefectKind) -> Callable[[Handler], Handler]
```

### `call_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
call_handler(kind: PrefectKind, obj: dict[str, Any], ctx: HydrationContext) -> Any
```

### `null_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
null_handler(obj: dict[str, Any], ctx: HydrationContext)
```

### `json_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_handler(obj: dict[str, Any], ctx: HydrationContext)
```

### `jinja_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
jinja_handler(obj: dict[str, Any], ctx: HydrationContext) -> Any
```

### `workspace_variable_handler` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
workspace_variable_handler(obj: dict[str, Any], ctx: HydrationContext) -> Any
```

### `hydrate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
hydrate(obj: dict[str, Any], ctx: Optional[HydrationContext] = None) -> dict[str, Any]
```

## Classes

### `HydrationContext` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `build` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build(cls, session: AsyncSession, raise_on_error: bool = False, render_jinja: bool = False, render_workspace_variables: bool = False) -> Self
```

### `Placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

### `RemoveValue` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

### `HydrationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

### `KeyNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

#### `key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
key(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

### `ValueNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
key(self) -> str
```

#### `key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
key(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

### `TemplateNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
key(self) -> str
```

#### `key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
key(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

### `VariableNameNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
key(self) -> str
```

#### `key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
key(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

### `InvalidJSON` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

### `InvalidJinja` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

### `WorkspaceVariableNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

#### `message` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
message(self) -> str
```

#### `variable_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
variable_name(self) -> str
```

### `WorkspaceVariable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```

### `ValidJinja` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `is_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/hydration.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_error(self) -> bool
```


# validation
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-schema_tools-validation



# `prefect.utilities.schema_tools.validation`

## Functions

### `is_valid_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_valid_schema(schema: ObjectSchema, preprocess: bool = True) -> None
```

### `validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate(obj: dict[str, Any], schema: ObjectSchema, raise_on_error: bool = False, preprocess: bool = True, ignore_required: bool = False, allow_none_with_default: bool = False) -> list[JSONSchemaValidationError]
```

### `is_valid` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_valid(obj: dict[str, Any], schema: ObjectSchema) -> bool
```

### `prioritize_placeholder_errors` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prioritize_placeholder_errors(errors: list[JSONSchemaValidationError]) -> list[JSONSchemaValidationError]
```

### `build_error_obj` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_error_obj(errors: list[JSONSchemaValidationError]) -> dict[str, Any]
```

### `process_properties` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
process_properties(properties: dict[str, dict[str, Any]], required_fields: list[str], allow_none_with_default: bool = False) -> None
```

### `preprocess_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
preprocess_schema(schema: ObjectSchema, allow_none_with_default: bool = False) -> ObjectSchema
```

## Classes

### `CircularSchemaRefError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `ValidationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/schema_tools/validation.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# services
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-services



# `prefect.utilities.services`

## Functions

### `critical_service_loop` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/services.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
critical_service_loop(workload: Callable[..., Coroutine[Any, Any, Any]], interval: float, memory: int = 10, consecutive: int = 3, backoff: int = 1, printer: Callable[..., None] = print, run_once: bool = False, jitter_range: Optional[float] = None) -> None
```

Runs the given `workload` function on the specified `interval`, while being
forgiving of intermittent issues like temporary HTTP errors.  If more than a certain
number of `consecutive` errors occur, print a summary of up to `memory` recent
exceptions to `printer`, then begin backoff.

The loop will exit after reaching the consecutive error limit `backoff` times.
On each backoff, the interval will be doubled. On a successful loop, the backoff
will be reset.

**Args:**

* `workload`: the function to call
* `interval`: how frequently to call it
* `memory`: how many recent errors to remember
* `consecutive`: how many consecutive errors must we see before we begin backoff
* `backoff`: how many times we should allow consecutive errors before exiting
* `printer`: a `print`-like function where errors will be reported
* `run_once`: if set, the loop will only run once then return
* `jitter_range`: if set, the interval will be a random variable (rv) drawn from
  a clamped Poisson distribution where lambda = interval and the rv is bound
  between `interval * (1 - range) < rv < interval * (1 + range)`

### `start_client_metrics_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/services.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_client_metrics_server() -> None
```

Start the process-wide Prometheus metrics server for client metrics (if enabled
with `PREFECT_CLIENT_METRICS_ENABLED`) on the port `PREFECT_CLIENT_METRICS_PORT`.

### `stop_client_metrics_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/services.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
stop_client_metrics_server() -> None
```

Stop the process-wide Prometheus metrics server for client metrics, if it has
previously been started


# slugify
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-slugify



# `prefect.utilities.slugify`

*This module is empty or contains only private/internal implementations.*


# templating
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-templating



# `prefect.utilities.templating`

## Functions

### `determine_placeholder_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/templating.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
determine_placeholder_type(name: str) -> PlaceholderType
```

Determines the type of a placeholder based on its name.

**Args:**

* `name`: The name of the placeholder

**Returns:**

* The type of the placeholder

### `find_placeholders` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/templating.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
find_placeholders(template: T) -> set[Placeholder]
```

Finds all placeholders in a template.

**Args:**

* `template`: template to discover placeholders in

**Returns:**

* A set of all placeholders in the template

### `apply_values` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/templating.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
apply_values(template: T, values: dict[str, Any], remove_notset: bool = True, warn_on_notset: bool = False) -> Union[T, type[NotSet]]
```

Replaces placeholders in a template with values from a supplied dictionary.

Will recursively replace placeholders in dictionaries and lists.

If a value has no placeholders, it will be returned unchanged.

If a template contains only a single placeholder, the placeholder will be
fully replaced with the value.

If a template contains text before or after a placeholder or there are
multiple placeholders, the placeholders will be replaced with the
corresponding variable values.

If a template contains a placeholder that is not in `values`, NotSet will
be returned to signify that no placeholder replacement occurred. If
`template` is a dictionary that contains a key with a value of NotSet,
the key will be removed in the return value unless `remove_notset` is set to False.

**Args:**

* `template`: template to discover and replace values in
* `values`: The values to apply to placeholders in the template
* `remove_notset`: If True, remove keys with an unset value
* `warn_on_notset`: If True, warn when a placeholder is not found in `values`

**Returns:**

* The template with the values applied

### `resolve_block_document_references` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/templating.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_block_document_references(template: T, client: Optional['PrefectClient'] = None, value_transformer: Optional[Callable[[str, Any], Any]] = None) -> Union[T, dict[str, Any]]
```

Resolve block document references in a template by replacing each reference with
its value or the return value of the transformer function if provided.

Recursively searches for block document references in dictionaries and lists.

Identifies block document references by the as dictionary with the following
structure:

```
{
    "$ref": {
        "block_document_id": <block_document_id>
    }
}
```

where `<block_document_id>` is the ID of the block document to resolve.

Once the block document is retrieved from the API, the data of the block document
is used to replace the reference.

## Accessing Values:

To access different values in a block document, use dot notation combined with the block document's prefix, slug, and block name.

For a block document with the structure:

```json
{
    "value": {
        "key": {
            "nested-key": "nested-value"
        },
        "list": [
            {"list-key": "list-value"},
            1,
            2
        ]
    }
}
```

examples of value resolution are as follows:

1. Accessing a nested dictionary:
   Format: `prefect.blocks.<block_type_slug>.<block_document_name>.value.key`
   Example: Returns `{"nested-key": "nested-value"}`

2. Accessing a specific nested value:
   Format: `prefect.blocks.<block_type_slug>.<block_document_name>.value.key.nested-key`
   Example: Returns `"nested-value"`

3. Accessing a list element's key-value:
   Format: `prefect.blocks.<block_type_slug>.<block_document_name>.value.list[0].list-key`
   Example: Returns `"list-value"`

## Default Resolution for System Blocks:

For system blocks, which only contain a `value` attribute, this attribute is resolved by default.

**Args:**

* `template`: The template to resolve block documents in
* `value_transformer`: A function that takes the block placeholder and the block value and returns replacement text for the template

**Returns:**

* The template with block documents resolved

### `resolve_variables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/templating.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_variables(template: T, client: Optional['PrefectClient'] = None) -> T
```

Resolve variables in a template by replacing each variable placeholder with the
value of the variable.

Recursively searches for variable placeholders in dictionaries and lists.

Strips variable placeholders if the variable is not found.

**Args:**

* `template`: The template to resolve variables in

**Returns:**

* The template with variables resolved

## Classes

### `PlaceholderType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/templating.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `Placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/templating.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


# text
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-text



# `prefect.utilities.text`

## Functions

### `truncated_to` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/text.py#L6" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
truncated_to(length: int, value: Optional[str]) -> str
```

### `fuzzy_match_string` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/text.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fuzzy_match_string(word: str, possibilities: Iterable[str]) -> Optional[str]
```


# timeout
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-timeout



# `prefect.utilities.timeout`

## Functions

### `fail_if_not_timeout_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/timeout.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
fail_if_not_timeout_error(timeout_exc_type: type[Exception]) -> None
```

### `timeout_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/timeout.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
timeout_async(seconds: Optional[float] = None, timeout_exc_type: type[TimeoutError] = TimeoutError)
```

### `timeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/timeout.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
timeout(seconds: Optional[float] = None, timeout_exc_type: type[TimeoutError] = TimeoutError)
```


# urls
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-urls



# `prefect.utilities.urls`

## Functions

### `validate_restricted_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/urls.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_restricted_url(url: str) -> None
```

Validate that the provided URL is safe for outbound requests.  This prevents
attacks like SSRF (Server Side Request Forgery), where an attacker can make
requests to internal services (like the GCP metadata service, localhost addresses,
or in-cluster Kubernetes services)

**Args:**

* `url`: The URL to validate.

**Raises:**

* `ValueError`: If the URL is a restricted URL.

### `convert_class_to_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/urls.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
convert_class_to_name(obj: Any) -> str
```

Convert CamelCase class name to dash-separated lowercase name

### `url_for` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/urls.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
url_for(obj: Union['PrefectFuture[Any]', 'Block', 'Variable', 'Automation', 'Resource', 'ReceivedEvent', BaseModel, str], obj_id: Optional[Union[str, UUID]] = None, url_type: URLType = 'ui', default_base_url: Optional[str] = None, **additional_format_kwargs: Any) -> Optional[str]
```

Returns the URL for a Prefect object.

Pass in a supported object directly or provide an object name and ID.

**Args:**

* `obj`:
  A Prefect object to get the URL for, or its URL name and ID.
* `obj_id`:
  The UUID of the object.
* `url_type`:
  Whether to return the URL for the UI (default) or API.
* `default_base_url`:
  The default base URL to use if no URL is configured.
* `additional_format_kwargs`:
  Additional keyword arguments to pass to the URL format.

**Returns:**

* Optional\[str]: The URL for the given object or None if the object is not supported.

**Examples:**

url\_for(my\_flow\_run)
url\_for(obj=my\_flow\_run)
url\_for("flow-run", obj\_id="123e4567-e89b-12d3-a456-426614174000")


# visualization
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-utilities-visualization



# `prefect.utilities.visualization`

Utilities for working with Flow\.visualize()

## Functions

### `get_task_viz_tracker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_viz_tracker() -> Optional['TaskVizTracker']
```

### `track_viz_task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
track_viz_task(is_async: bool, task_name: str, parameters: dict[str, Any], viz_return_value: Optional[Any] = None) -> Union[Coroutine[Any, Any, Any], Any]
```

Return a result if sync otherwise return a coroutine that returns the result

### `build_task_dependencies` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_task_dependencies(task_run_tracker: TaskVizTracker) -> graphviz.Digraph
```

Constructs a Graphviz directed graph object that represents the dependencies
between tasks in the given TaskVizTracker.

* task\_run\_tracker (TaskVizTracker): An object containing tasks and their
  dependencies.

* graphviz.Digraph: A directed graph object depicting the relationships and
  dependencies between tasks.

Raises:

* GraphvizImportError: If there's an ImportError related to graphviz.
* FlowVisualizationError: If there's any other error during the visualization
  process or if return values of tasks are directly accessed without
  specifying a `viz_return_value`.

### `visualize_task_dependencies` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
visualize_task_dependencies(graph: graphviz.Digraph, flow_run_name: str) -> None
```

Renders and displays a Graphviz directed graph representing task dependencies.

The graph is rendered in PNG format and saved with the name specified by
flow\_run\_name. After rendering, the visualization is opened and displayed.

Parameters:

* graph (graphviz.Digraph): The directed graph object to visualize.
* flow\_run\_name (str): The name to use when saving the rendered graph image.

Raises:

* GraphvizExecutableNotFoundError: If Graphviz isn't found on the system.
* FlowVisualizationError: If there's any other error during the visualization
  process or if return values of tasks are directly accessed without
  specifying a `viz_return_value`.

## Classes

### `FlowVisualizationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `VisualizationUnsupportedError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `TaskVizTrackerState` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `GraphvizImportError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `GraphvizExecutableNotFoundError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `VizTask` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `TaskVizTracker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `add_task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_task(self, task: VizTask) -> None
```

#### `link_viz_return_value_to_viz_task` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/utilities/visualization.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
link_viz_return_value_to_viz_task(self, viz_return_value: Any, viz_task: VizTask) -> None
```

We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256
because they are singletons.


# variables
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-variables



# `prefect.variables`

## Classes

### `Variable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/variables.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Variables are named, mutable JSON values that can be shared across tasks and flows.

**Args:**

* `name`: A string identifying the variable.
* `value`: A string that is the value of the variable.
* `tags`: An optional list of strings to associate with the variable.

**Methods:**

#### `aget` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/variables.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aget(cls, name: str, default: StrictVariableValue = None) -> StrictVariableValue
```

Asynchronously get a variable's value by name.

If the variable does not exist, return the default value.

**Args:**

* `- name`: The name of the variable value to get.
* `- default`: The default value to return if the variable does not exist.

#### `aset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/variables.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aset(cls, name: str, value: StrictVariableValue, tags: Optional[list[str]] = None, overwrite: bool = False) -> 'Variable'
```

Asynchronously sets a new variable. If one exists with the same name, must pass `overwrite=True`

Returns the newly set variable object.

**Args:**

* `- name`: The name of the variable to set.
* `- value`: The value of the variable to set.
* `- tags`: An optional list of strings to associate with the variable.
* `- overwrite`: Whether to overwrite the variable if it already exists.

#### `aunset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/variables.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aunset(cls, name: str) -> bool
```

Asynchronously unset a variable by name.

**Args:**

* `- name`: The name of the variable to unset.

Returns `True` if the variable was deleted, `False` if the variable did not exist.

#### `get` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/variables.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(cls, name: str, default: StrictVariableValue = None) -> StrictVariableValue
```

Get a variable's value by name.

If the variable does not exist, return the default value.

**Args:**

* `- name`: The name of the variable value to get.
* `- default`: The default value to return if the variable does not exist.

#### `set` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/variables.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(cls, name: str, value: StrictVariableValue, tags: Optional[list[str]] = None, overwrite: bool = False) -> 'Variable'
```

Sets a new variable. If one exists with the same name, must pass `overwrite=True`

Returns the newly set variable object.

**Args:**

* `- name`: The name of the variable to set.
* `- value`: The value of the variable to set.
* `- tags`: An optional list of strings to associate with the variable.
* `- overwrite`: Whether to overwrite the variable if it already exists.

#### `unset` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/variables.py#L231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unset(cls, name: str) -> bool
```

Unset a variable by name.

**Args:**

* `- name`: The name of the variable to unset.

Returns `True` if the variable was deleted, `False` if the variable did not exist.


# __init__
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-workers-__init__



# `prefect.workers`

*This module is empty or contains only private/internal implementations.*


# base
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-workers-base



# `prefect.workers.base`

## Classes

### `BaseJobConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `from_template_and_values` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_template_and_values(cls, base_job_template: dict[str, Any], values: dict[str, Any], client: 'PrefectClient | None' = None)
```

Creates a valid worker configuration object from the provided base
configuration and overrides.

Important: this method expects that the base\_job\_template was already
validated server-side.

#### `is_using_a_runner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_using_a_runner(self) -> bool
```

#### `json_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_template(cls) -> dict[str, Any]
```

Returns a dict with job configuration as keys and the corresponding templates as values

Defaults to using the job configuration parameter name as the template variable name.

e.g.

```python
{
    key1: '{{ key1 }}',     # default variable template
    key2: '{{ template2 }}', # `template2` specifically provide as template
}
```

#### `prepare_for_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_for_flow_run(self, flow_run: 'FlowRun', deployment: 'DeploymentResponse | None' = None, flow: 'APIFlow | None' = None, work_pool: 'WorkPool | None' = None, worker_name: str | None = None) -> None
```

Prepare the job configuration for a flow run.

This method is called by the worker before starting a flow run. It
should be used to set any configuration values that are dependent on
the flow run.

**Args:**

* `flow_run`: The flow run to be executed.
* `deployment`: The deployment that the flow run is associated with.
* `flow`: The flow that the flow run is associated with.
* `work_pool`: The work pool that the flow run is running in.
* `worker_name`: The name of the worker that is submitting the flow run.

### `BaseVariables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: Type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

### `BaseWorkerResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

### `BaseWorker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `client` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L515" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client(self) -> PrefectClient
```

#### `get_all_available_worker_types` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L582" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_all_available_worker_types() -> list[str]
```

Returns all worker types available in the local registry.

#### `get_and_submit_flow_runs` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L980" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_and_submit_flow_runs(self) -> list['FlowRun']
```

#### `get_default_base_job_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L551" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_default_base_job_template(cls) -> dict[str, Any]
```

#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> str
```

#### `get_documentation_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_documentation_url(cls) -> str
```

#### `get_flow_run_logger` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L595" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_flow_run_logger(self, flow_run: 'FlowRun') -> PrefectLogAdapter
```

#### `get_logo_url` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L543" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_logo_url(cls) -> str
```

#### `get_name_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L592" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_name_slug(self) -> str
```

#### `get_status` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L1342" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_status(self) -> dict[str, Any]
```

Retrieves the status of the current worker including its name, current worker
pool, the work pool queues it is polling, and its local settings.

#### `get_worker_class_from_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_worker_class_from_type(type: str) -> Optional[Type['BaseWorker[Any, Any, Any]']]
```

Returns the worker class for a given worker type. If the worker type
is not recognized, returns None.

#### `is_worker_still_polling` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L951" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_worker_still_polling(self, query_interval_seconds: float) -> bool
```

This method is invoked by a webserver healthcheck handler
and returns a boolean indicating if the worker has recorded a
scheduled flow run poll within a variable amount of time.

The `query_interval_seconds` is the same value that is used by
the loop services - we will evaluate if the \_last\_polled\_time
was within that interval x 30 (so 10s -> 5m)

The instance property `self._last_polled_time`
is currently set/updated in `get_and_submit_flow_runs()`

#### `limiter` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L531" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
limiter(self) -> anyio.CapacityLimiter
```

#### `run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L704" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run(self, flow_run: 'FlowRun', configuration: C, task_status: Optional[anyio.abc.TaskStatus[int]] = None) -> R
```

Runs a given flow run on the current worker.

#### `setup` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L913" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup(self) -> None
```

Prepares the worker to run.

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L611" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, run_once: bool = False, with_healthcheck: bool = False, printer: Callable[..., None] = print) -> None
```

Starts the worker and runs the main worker loops.

By default, the worker will run loops to poll for scheduled/cancelled flow
runs and sync with the Prefect API server.

If `run_once` is set, the worker will only run each loop once and then return.

If `with_healthcheck` is set, the worker will start a healthcheck server which
can be used to determine if the worker is still polling for flow runs and restart
the worker if necessary.

**Args:**

* `run_once`: If set, the worker will only run each loop once then return.
* `with_healthcheck`: If set, the worker will start a healthcheck server.
* `printer`: A `print`-like function where logs will be reported.

#### `submit` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L736" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
submit(self, flow: 'Flow[..., FR]', parameters: dict[str, Any] | None = None, job_variables: dict[str, Any] | None = None) -> 'PrefectFlowRunFuture[FR]'
```

EXPERIMENTAL: The interface for this method is subject to change.

Submits a flow to run via the worker.

**Args:**

* `flow`: The flow to submit
* `parameters`: The parameters to pass to the flow

**Returns:**

* A flow run object

#### `sync_with_backend` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L1102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
sync_with_backend(self) -> None
```

Updates the worker's local information about it's current work pool and
queues. Sends a worker heartbeat to the API.

#### `teardown` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L933" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
teardown(self, *exc_info: Any) -> None
```

Cleans up resources after the worker is stopped.

#### `work_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L523" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
work_pool(self) -> WorkPool
```


# block
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-workers-block



# `prefect.workers.block`

2024-06-27: This surfaces an actionable error message for moved or removed objects in Prefect 3.0 upgrade.


# cloud
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-workers-cloud



# `prefect.workers.cloud`

2024-06-27: This surfaces an actionable error message for moved or removed objects in Prefect 3.0 upgrade.


# process
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-workers-process



# `prefect.workers.process`

Module containing the Process worker used for executing flow runs as subprocesses.

To start a Process worker, run the following command:

```bash
prefect worker start --pool 'my-work-pool' --type process
```

Replace `my-work-pool` with the name of the work pool you want the worker
to poll for flow runs.

For more information about work pools and workers,
checkout out the [Prefect docs](https://docs.prefect.io/v3/concepts/work-pools/).

## Classes

### `ProcessJobConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `from_template_and_values` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_template_and_values(cls, base_job_template: dict[str, Any], values: dict[str, Any], client: 'PrefectClient | None' = None)
```

Creates a valid worker configuration object from the provided base
configuration and overrides.

Important: this method expects that the base\_job\_template was already
validated server-side.

#### `is_using_a_runner` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_using_a_runner(self) -> bool
```

#### `json_template` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
json_template(cls) -> dict[str, Any]
```

Returns a dict with job configuration as keys and the corresponding templates as values

Defaults to using the job configuration parameter name as the template variable name.

e.g.

```python
{
    key1: '{{ key1 }}',     # default variable template
    key2: '{{ template2 }}', # `template2` specifically provide as template
}
```

#### `prepare_for_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_for_flow_run(self, flow_run: 'FlowRun', deployment: 'DeploymentResponse | None' = None, flow: 'APIFlow | None' = None, work_pool: 'WorkPool | None' = None, worker_name: str | None = None) -> None
```

#### `prepare_for_flow_run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_for_flow_run(self, flow_run: 'FlowRun', deployment: 'DeploymentResponse | None' = None, flow: 'APIFlow | None' = None, work_pool: 'WorkPool | None' = None, worker_name: str | None = None) -> None
```

Prepare the job configuration for a flow run.

This method is called by the worker before starting a flow run. It
should be used to set any configuration values that are dependent on
the flow run.

**Args:**

* `flow_run`: The flow run to be executed.
* `deployment`: The deployment that the flow run is associated with.
* `flow`: The flow that the flow run is associated with.
* `work_pool`: The work pool that the flow run is running in.
* `worker_name`: The name of the worker that is submitting the flow run.

#### `validate_working_dir` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_working_dir(cls, v: Path | str | None) -> Path | None
```

### `ProcessVariables` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/base.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: Type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?

### `ProcessWorkerResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Contains information about the final state of a completed process

### `ProcessWorker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `run` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run(self, flow_run: 'FlowRun', configuration: ProcessJobConfiguration, task_status: Optional[anyio.abc.TaskStatus[int]] = None) -> ProcessWorkerResult
```

#### `start` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/process.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start(self, run_once: bool = False, with_healthcheck: bool = False, printer: Callable[..., None] = print) -> None
```

Starts the worker and runs the main worker loops.

By default, the worker will run loops to poll for scheduled/cancelled flow
runs and sync with the Prefect API server.

If `run_once` is set, the worker will only run each loop once and then return.

If `with_healthcheck` is set, the worker will start a healthcheck server which
can be used to determine if the worker is still polling for flow runs and restart
the worker if necessary.

**Args:**

* `run_once`: If set, the worker will only run each loop once then return.
* `with_healthcheck`: If set, the worker will start a healthcheck server.
* `printer`: A `print`-like function where logs will be reported.


# server
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-workers-server



# `prefect.workers.server`

## Functions

### `build_healthcheck_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/server.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_healthcheck_server(worker: BaseWorker[Any, Any, Any], query_interval_seconds: float, log_level: str = 'error') -> uvicorn.Server
```

Build a healthcheck FastAPI server for a worker.

**Args:**

* `worker`: the worker whose health we will check
* `log_level`: the log

### `start_healthcheck_server` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/server.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
start_healthcheck_server(worker: BaseWorker[Any, Any, Any], query_interval_seconds: float, log_level: str = 'error') -> None
```

Run a healthcheck FastAPI server for a worker.

**Args:**

* `worker`: the worker whose health we will check
* `log_level`: the log level to use for the server


# utilities
Source: https://docs-3.prefect.io/v3/api-ref/python/prefect-workers-utilities



# `prefect.workers.utilities`

## Functions

### `get_available_work_pool_types` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/utilities.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_available_work_pool_types() -> List[str]
```

### `get_default_base_job_template_for_infrastructure_type` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/workers/utilities.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_default_base_job_template_for_infrastructure_type(infra_type: str) -> Optional[Dict[str, Any]]
```


# Cloud API Overview
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/cloud/index

The Prefect Cloud API enables you to interact programmatically with Prefect Cloud.

The Prefect Cloud API is organized around REST.

Explore the interactive [Prefect Cloud REST API reference](https://app.prefect.cloud/api/docs).


# REST API overview
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/index

Prefect REST API for interacting with Prefect Cloud & self-hosted Prefect server.

The Prefect API is organized around REST. It is used for communicating data from clients to a self-hosted Prefect server instance so that orchestration can be performed. This API is consumed by clients such as the Prefect Python SDK or the server dashboard.

Prefect Cloud and self-hosted Prefect server each provide a REST API.

* Prefect Cloud:
  * [Interactive Prefect Cloud REST API documentation](https://app.prefect.cloud/api/docs)
  * [Finding your Prefect Cloud details](#finding-your-prefect-cloud-details)
* Self-hosted Prefect server:
  * Interactive REST API documentation for self-hosted Prefect server is available under **Server API** on the sidebar navigation or at `http://localhost:4200/docs` or the `/docs` endpoint of the [PREFECT\_API\_URL](/v3/develop/settings-and-profiles/) you have configured to access the server. You must have the server running with `prefect server start` to access the interactive documentation.

## Interact with the REST API

You can interact with the Prefect REST API in several ways:

* Create an instance of [`PrefectClient`](https://reference.prefect.io/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient), which is part of the [Prefect Python SDK](/v3/api-ref/python/).
* Use your favorite Python HTTP library such as [Requests](https://requests.readthedocs.io/en/latest/) or [HTTPX](https://www.python-httpx.org/)
* Use an HTTP library in your language of choice
* Use [curl](https://curl.se/) from the command line

### PrefectClient with self-hosted Prefect server

This example uses `PrefectClient` with self-hosted Prefect server:

```python
import asyncio
from prefect.client.orchestration import get_client


async def get_flows():
    client = get_client()
    r = await client.read_flows(limit=5)
    return r


r = asyncio.run(get_flows())

for flow in r:
    print(flow.name, flow.id)


if __name__ == "__main__":
    asyncio.run(get_flows())
```

Output:

```bash
cat-facts 58ed68b1-0201-4f37-adef-0ea24bd2a022
dog-facts e7c0403d-44e7-45cf-a6c8-79117b7f3766
sloth-facts 771c0574-f5bf-4f59-a69d-3be3e061a62d
capybara-facts fbadaf8b-584f-48b9-b092-07d351edd424
lemur-facts 53f710e7-3b0f-4b2f-ab6b-44934111818c
```

### Requests with Prefect

This example uses the Requests library with Prefect Cloud to return the five newest artifacts.

{/* pmd-metadata: fixture:mock_post_200 */}

```python
import requests


PREFECT_API_URL="https://api.prefect.cloud/api/accounts/abc-my-cloud-account-id-is-here/workspaces/123-my-workspace-id-is-here"
PREFECT_API_KEY="123abc_my_api_key_goes_here"
data = {
    "sort": "CREATED_DESC",
    "limit": 5,
    "artifacts": {
        "key": {
            "exists_": True
        }
    }
}

headers = {"Authorization": f"Bearer {PREFECT_API_KEY}"}
endpoint = f"{PREFECT_API_URL}/artifacts/filter"

response = requests.post(endpoint, headers=headers, json=data)
assert response.status_code == 200
for artifact in response.json():
    print(artifact)
```

### curl with Prefect Cloud

This example uses curl with Prefect Cloud to create a flow run:

```bash
ACCOUNT_ID="abc-my-cloud-account-id-goes-here"
WORKSPACE_ID="123-my-workspace-id-goes-here"
PREFECT_API_URL="https://api.prefect.cloud/api/accounts/$ACCOUNT_ID/workspaces/$WORKSPACE_ID"
PREFECT_API_KEY="123abc_my_api_key_goes_here"
DEPLOYMENT_ID="my_deployment_id"

curl --location --request POST "$PREFECT_API_URL/deployments/$DEPLOYMENT_ID/create_flow_run" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $PREFECT_API_KEY" \
  --header "X-PREFECT-API-VERSION: 0.8.4" \
  --data-raw "{}"
```

Note that in this example `--data-raw "{}"` is required and is where you can specify other aspects of the flow run such as the state. Windows users substitute `^` for `\` for line multi-line commands.

## Finding your Prefect Cloud details

When working with the Prefect Cloud REST API you will need your Account ID and often the Workspace ID for the [workspace](/v3/manage/cloud/workspaces/) you want to interact with. You can find both IDs for a [Prefect profile](/v3/develop/settings-and-profiles/) in the CLI with `prefect profile inspect my_profile`. This command will also display your [Prefect API key](/v3/how-to-guides/cloud/manage-users/api-keys), as shown below:

```bash
PREFECT_API_URL='https://api.prefect.cloud/api/accounts/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here'
PREFECT_API_KEY='123abc_my_api_key_is_here'
```

Alternatively, view your Account ID and Workspace ID in your browser URL. For example: `https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here`.

## REST guidelines

The REST APIs adhere to the following guidelines:

* Collection names are pluralized (for example, `/flows` or `/runs`).
* We indicate variable placeholders with colons: `GET /flows/:id`.
* We use snake case for route names: `GET /task_runs`.
* We avoid nested resources unless there is no possibility of accessing the child resource outside the parent context. For example, we query `/task_runs` with a flow run filter instead of accessing `/flow_runs/:id/task_runs`.
* The API is hosted with an `/api/:version` prefix that (optionally) allows versioning in the future. By convention, we treat that as part of the base URL and do not include that in API examples.
* Filtering, sorting, and pagination parameters are provided in the request body of `POST` requests where applicable.
  * Pagination parameters are `limit` and `offset`.
  * Sorting is specified with a single `sort` parameter.
  * See more information on [filtering](#filtering) below.

### HTTP verbs

* `GET`, `PUT` and `DELETE` requests are always idempotent. `POST` and `PATCH` are not guaranteed to be idempotent.
* `GET` requests cannot receive information from the request body.
* `POST` requests can receive information from the request body.
* `POST /collection` creates a new member of the collection.
* `GET /collection` lists all members of the collection.
* `GET /collection/:id` gets a specific member of the collection by ID.
* `DELETE /collection/:id` deletes a specific member of the collection.
* `PUT /collection/:id` creates or replaces a specific member of the collection.
* `PATCH /collection/:id` partially updates a specific member of the collection.
* `POST /collection/action` is how we implement non-CRUD actions. For example, to set a flow run's state, we use `POST /flow_runs/:id/set_state`.
* `POST /collection/action` may also be used for read-only queries. This is to allow us to send complex arguments as body arguments (which often cannot be done via `GET`). Examples include `POST /flow_runs/filter`, `POST /flow_runs/count`, and `POST /flow_runs/history`.

## Filter results

Objects can be filtered by providing filter criteria in the body of a `POST` request. When multiple criteria are specified, logical AND will be applied to the criteria.

Filter criteria are structured as follows:

```json
{
    "objects": {
        "object_field": {
            "field_operator_": <field_value>
        }
    }
}
```

In this example, `objects` is the name of the collection to filter over (for example, `flows`). The collection can be either the object being queried for (`flows` for `POST /flows/filter`) or a related object (`flow_runs` for `POST /flows/filter`).

`object_field` is the name of the field over which to filter (`name` for `flows`). Note that some objects may have nested object fields, such as `{flow_run: {state: {type: {any_: []}}}}`.

`field_operator_` is the operator to apply to a field when filtering. Common examples include:

* `any_`: return objects where this field matches any of the following values.
* `is_null_`: return objects where this field is or is not null.
* `eq_`: return objects where this field is equal to the following value.
* `all_`: return objects where this field matches all of the following values.
* `before_`: return objects where this datetime field is less than or equal to the following value.
* `after_`: return objects where this datetime field is greater than or equal to the following value.

For example, to query for flows with the tag `"database"` and failed flow runs, `POST /flows/filter` with the following request body:

```json
{
    "flows": {
        "tags": {
            "all_": ["database"]
        }
    },
    "flow_runs": {
        "state": {
            "type": {
              "any_": ["FAILED"]
            }
        }
    }
}
```

## OpenAPI

The Prefect REST API can be fully described with an OpenAPI 3.0 compliant document. [OpenAPI](https://swagger.io/docs/specification/about/) is a standard specification for describing REST APIs.

To generate self-hosted Prefect server's complete OpenAPI document, run the following commands in an interactive Python session:

```python
from prefect.server.api.server import create_app


app = create_app()
openapi_doc = app.openapi()
```

This document allows you to generate your own API client, explore the API using an API inspection tool, or write tests to ensure API compliance.


# Clear Database
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/admin/clear-database

post /api/admin/database/clear
Clear all database tables without dropping them.



# Create Database
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/admin/create-database

post /api/admin/database/create
Create all database objects.



# Drop Database
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/admin/drop-database

post /api/admin/database/drop
Drop all database objects.



# Read Settings
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/admin/read-settings

get /api/admin/settings
Get the current Prefect REST API settings.

Secret setting values will be obfuscated.



# Read Version
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/admin/read-version

get /api/admin/version
Returns the Prefect version number



# Count Artifacts
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/count-artifacts

post /api/artifacts/count
Count artifacts from the database.



# Count Latest Artifacts
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/count-latest-artifacts

post /api/artifacts/latest/count
Count artifacts from the database.



# Create Artifact
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/create-artifact

post /api/artifacts/
Create an artifact.

For more information, see https://docs.prefect.io/v3/develop/artifacts.



# Delete Artifact
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/delete-artifact

delete /api/artifacts/{id}
Delete an artifact from the database.



# Read Artifact
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/read-artifact

get /api/artifacts/{id}
Retrieve an artifact from the database.



# Read Artifacts
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/read-artifacts

post /api/artifacts/filter
Retrieve artifacts from the database.



# Read Latest Artifact
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/read-latest-artifact

get /api/artifacts/{key}/latest
Retrieve the latest artifact from the artifact table.



# Read Latest Artifacts
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/read-latest-artifacts

post /api/artifacts/latest/filter
Retrieve artifacts from the database.



# Update Artifact
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/artifacts/update-artifact

patch /api/artifacts/{id}
Update an artifact in the database.



# Count Automations
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/count-automations

post /api/automations/count



# Create Automation
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/create-automation

post /api/automations/
Create an automation.

For more information, see https://docs.prefect.io/v3/automate.



# Delete Automation
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/delete-automation

delete /api/automations/{id}



# Delete Automations Owned By Resource
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/delete-automations-owned-by-resource

delete /api/automations/owned-by/{resource_id}



# Patch Automation
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/patch-automation

patch /api/automations/{id}



# Read Automation
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/read-automation

get /api/automations/{id}



# Read Automations
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/read-automations

post /api/automations/filter



# Read Automations Related To Resource
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/read-automations-related-to-resource

get /api/automations/related-to/{resource_id}



# Update Automation
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/update-automation

put /api/automations/{id}



# Validate Template
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/validate-template

post /api/templates/validate



# Validate Template
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/automations/validate-template-1

post /api/automations/templates/validate



# Read Available Block Capabilities
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-capabilities/read-available-block-capabilities

get /api/block_capabilities/
Get available block capabilities.

For more information, see https://docs.prefect.io/v3/develop/blocks.



# Count Block Documents
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-documents/count-block-documents

post /api/block_documents/count
Count block documents.



# Create Block Document
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-documents/create-block-document

post /api/block_documents/
Create a new block document.

For more information, see https://docs.prefect.io/v3/develop/blocks.



# Delete Block Document
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-documents/delete-block-document

delete /api/block_documents/{id}



# Read Block Document By Id
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-documents/read-block-document-by-id

get /api/block_documents/{id}



# Read Block Documents
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-documents/read-block-documents

post /api/block_documents/filter
Query for block documents.



# Update Block Document Data
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-documents/update-block-document-data

patch /api/block_documents/{id}



# Create Block Schema
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-schemas/create-block-schema

post /api/block_schemas/
Create a block schema.

For more information, see https://docs.prefect.io/v3/develop/blocks.



# Delete Block Schema
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-schemas/delete-block-schema

delete /api/block_schemas/{id}
Delete a block schema by id.



# Read Block Schema By Checksum
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-schemas/read-block-schema-by-checksum

get /api/block_schemas/checksum/{checksum}



# Read Block Schema By Id
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-schemas/read-block-schema-by-id

get /api/block_schemas/{id}
Get a block schema by id.



# Read Block Schemas
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-schemas/read-block-schemas

post /api/block_schemas/filter
Read all block schemas, optionally filtered by type



# Create Block Type
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/create-block-type

post /api/block_types/
Create a new block type.

For more information, see https://docs.prefect.io/v3/develop/blocks.



# Delete Block Type
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/delete-block-type

delete /api/block_types/{id}



# Install System Block Types
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/install-system-block-types

post /api/block_types/install_system_block_types



# Read Block Document By Name For Block Type
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/read-block-document-by-name-for-block-type

get /api/block_types/slug/{slug}/block_documents/name/{block_document_name}



# Read Block Documents For Block Type
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/read-block-documents-for-block-type

get /api/block_types/slug/{slug}/block_documents



# Read Block Type By Id
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/read-block-type-by-id

get /api/block_types/{id}
Get a block type by ID.



# Read Block Type By Slug
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/read-block-type-by-slug

get /api/block_types/slug/{slug}
Get a block type by name.



# Read Block Types
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/read-block-types

post /api/block_types/filter
Gets all block types. Optionally limit return with limit and offset.



# Update Block Type
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/block-types/update-block-type

patch /api/block_types/{id}
Update a block type.



# Read View Content
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/collections/read-view-content

get /api/collections/views/{view}
Reads the content of a view from the prefect-collection-registry.



# Bulk Decrement Active Slots
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/bulk-decrement-active-slots

post /api/v2/concurrency_limits/decrement



# Bulk Decrement Active Slots With Lease
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/bulk-decrement-active-slots-with-lease

post /api/v2/concurrency_limits/decrement-with-lease



# Bulk Increment Active Slots
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/bulk-increment-active-slots

post /api/v2/concurrency_limits/increment



# Bulk Increment Active Slots With Lease
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/bulk-increment-active-slots-with-lease

post /api/v2/concurrency_limits/increment-with-lease



# Create Concurrency Limit V2
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/create-concurrency-limit-v2

post /api/v2/concurrency_limits/
Create a task run concurrency limit.

For more information, see https://docs.prefect.io/v3/develop/global-concurrency-limits.



# Delete Concurrency Limit V2
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/delete-concurrency-limit-v2

delete /api/v2/concurrency_limits/{id_or_name}



# Read All Concurrency Limits V2
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/read-all-concurrency-limits-v2

post /api/v2/concurrency_limits/filter



# Read Concurrency Limit V2
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/read-concurrency-limit-v2

get /api/v2/concurrency_limits/{id_or_name}



# Renew Concurrency Lease
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/renew-concurrency-lease

post /api/v2/concurrency_limits/leases/{lease_id}/renew



# Update Concurrency Limit V2
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits-v2/update-concurrency-limit-v2

patch /api/v2/concurrency_limits/{id_or_name}



# Create Concurrency Limit
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/create-concurrency-limit

post /api/concurrency_limits/
Create a task run concurrency limit.

For more information, see https://docs.prefect.io/v3/develop/task-run-limits.



# Decrement Concurrency Limits V1
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/decrement-concurrency-limits-v1

post /api/concurrency_limits/decrement
Decrement concurrency limits for the given tags.

Finds and revokes the lease for V2 limits or decrements V1 active slots.
Returns the list of limits that were decremented.



# Delete Concurrency Limit
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/delete-concurrency-limit

delete /api/concurrency_limits/{id}



# Delete Concurrency Limit By Tag
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/delete-concurrency-limit-by-tag

delete /api/concurrency_limits/tag/{tag}



# Increment Concurrency Limits V1
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/increment-concurrency-limits-v1

post /api/concurrency_limits/increment
Increment concurrency limits for the given tags.

During migration, this handles both V1 and V2 limits to support mixed states.
Post-migration, it only uses V2 with lease-based concurrency.



# Read Concurrency Limit
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/read-concurrency-limit

get /api/concurrency_limits/{id}
Get a concurrency limit by id.

The `active slots` field contains a list of TaskRun IDs currently using a
concurrency slot for the specified tag.



# Read Concurrency Limit By Tag
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/read-concurrency-limit-by-tag

get /api/concurrency_limits/tag/{tag}
Get a concurrency limit by tag.

The `active slots` field contains a list of TaskRun IDs currently using a
concurrency slot for the specified tag.



# Read Concurrency Limits
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/read-concurrency-limits

post /api/concurrency_limits/filter
Query for concurrency limits.

For each concurrency limit the `active slots` field contains a list of TaskRun IDs
currently using a concurrency slot for the specified tag.



# Reset Concurrency Limit By Tag
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/concurrency-limits/reset-concurrency-limit-by-tag

post /api/concurrency_limits/tag/{tag}/reset



# Create Csrf Token
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/create-csrf-token

get /api/csrf-token
Create or update a CSRF token for a client



# Count Deployments
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/count-deployments

post /api/deployments/count
Count deployments.



# Create Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/create-deployment

post /api/deployments/
Gracefully creates a new deployment from the provided schema. If a deployment with
the same name and flow_id already exists, the deployment is updated.

If the deployment has an active schedule, flow runs will be scheduled.
When upserting, any scheduled runs from the existing deployment will be deleted.

For more information, see https://docs.prefect.io/v3/deploy.



# Create Deployment Schedules
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/create-deployment-schedules

post /api/deployments/{id}/schedules



# Create Flow Run From Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/create-flow-run-from-deployment

post /api/deployments/{id}/create_flow_run
Create a flow run from a deployment.

Any parameters not provided will be inferred from the deployment's parameters.
If tags are not provided, the deployment's tags will be used.

If no state is provided, the flow run will be created in a SCHEDULED state.



# Delete Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/delete-deployment

delete /api/deployments/{id}
Delete a deployment by id.



# Delete Deployment Schedule
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/delete-deployment-schedule

delete /api/deployments/{id}/schedules/{schedule_id}



# Get Scheduled Flow Runs For Deployments
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/get-scheduled-flow-runs-for-deployments

post /api/deployments/get_scheduled_flow_runs
Get scheduled runs for a set of deployments. Used by a runner to poll for work.



# Paginate Deployments
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/paginate-deployments

post /api/deployments/paginate
Pagination query for flow runs.



# Pause Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/pause-deployment

post /api/deployments/{id}/pause_deployment
Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled
state will be deleted.



# Read Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/read-deployment

get /api/deployments/{id}
Get a deployment by id.



# Read Deployment By Name
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/read-deployment-by-name

get /api/deployments/name/{flow_name}/{deployment_name}
Get a deployment using the name of the flow and the deployment.



# Read Deployment Schedules
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/read-deployment-schedules

get /api/deployments/{id}/schedules



# Read Deployments
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/read-deployments

post /api/deployments/filter
Query for deployments.



# Resume Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/resume-deployment

post /api/deployments/{id}/resume_deployment
Set a deployment schedule to active. Runs will be scheduled immediately.



# Schedule Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/schedule-deployment

post /api/deployments/{id}/schedule
Schedule runs for a deployment. For backfills, provide start/end times in the past.

This function will generate the minimum number of runs that satisfy the min
and max times, and the min and max counts. Specifically, the following order
will be respected.

    - Runs will be generated starting on or after the `start_time`
    - No more than `max_runs` runs will be generated
    - No runs will be generated after `end_time` is reached
    - At least `min_runs` runs will be generated
    - Runs will be generated until at least `start_time + min_time` is reached



# Update Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/update-deployment

patch /api/deployments/{id}



# Update Deployment Schedule
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/update-deployment-schedule

patch /api/deployments/{id}/schedules/{schedule_id}



# Work Queue Check For Deployment
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/deployments/work-queue-check-for-deployment

get /api/deployments/{id}/work_queue_check
Get list of work-queues that are able to pick up the specified deployment.

This endpoint is intended to be used by the UI to provide users warnings
about deployments that are unable to be executed because there are no work
queues that will pick up their runs, based on existing filter criteria. It
may be deprecated in the future because there is not a strict relationship
between work queues and deployments.



# Count Account Events
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/events/count-account-events

post /api/events/count-by/{countable}
Returns distinct objects and the count of events associated with them.  Objects
that can be counted include the day the event occurred, the type of event, or
the IDs of the resources associated with the event.



# Create Events
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/events/create-events

post /api/events
Record a batch of Events.

For more information, see https://docs.prefect.io/v3/concepts/events.



# Read Account Events Page
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/events/read-account-events-page

get /api/events/filter/next
Returns the next page of Events for a previous query against the given Account, and
the URL to request the next page (if there are more results).



# Read Events
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/events/read-events

post /api/events/filter
Queries for Events matching the given filter criteria in the given Account.  Returns
the first page of results, and the URL to request the next page (if there are more
results).



# Read Flow Run State
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-run-states/read-flow-run-state

get /api/flow_run_states/{id}
Get a flow run state by id.

For more information, see https://docs.prefect.io/v3/develop/write-flows#final-state-determination.



# Read Flow Run States
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-run-states/read-flow-run-states

get /api/flow_run_states/
Get states associated with a flow run.



# Average Flow Run Lateness
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/average-flow-run-lateness

post /api/flow_runs/lateness
Query for average flow-run lateness in seconds.



# Count Flow Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/count-flow-runs

post /api/flow_runs/count
Query for flow runs.



# Create Flow Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/create-flow-run

post /api/flow_runs/
Create a flow run. If a flow run with the same flow_id and
idempotency key already exists, the existing flow run will be returned.

If no state is provided, the flow run will be created in a PENDING state.

For more information, see https://docs.prefect.io/v3/develop/write-flows.



# Create Flow Run Input
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/create-flow-run-input

post /api/flow_runs/{id}/input
Create a key/value input for a flow run.



# Delete Flow Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/delete-flow-run

delete /api/flow_runs/{id}
Delete a flow run by id.



# Delete Flow Run Input
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/delete-flow-run-input

delete /api/flow_runs/{id}/input/{key}
Delete a flow run input



# Download Logs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/download-logs

get /api/flow_runs/{id}/logs/download
Download all flow run logs as a CSV file, collecting all logs until there are no more logs to retrieve.



# Filter Flow Run Input
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/filter-flow-run-input

post /api/flow_runs/{id}/input/filter
Filter flow run inputs by key prefix



# Flow Run History
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/flow-run-history

post /api/flow_runs/history
Query for flow run history data across a given range and interval.



# Read Flow Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/paginate-flow-runs

post /api/flow_runs/filter
Query for flow runs.



# Read Flow Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/read-flow-run

get /api/flow_runs/{id}
Get a flow run by id.



# Read Flow Run Graph V1
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/read-flow-run-graph-v1

get /api/flow_runs/{id}/graph
Get a task run dependency map for a given flow run.



# Read Flow Run Graph V2
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/read-flow-run-graph-v2

get /api/flow_runs/{id}/graph-v2
Get a graph of the tasks and subflow runs for the given flow run



# Read Flow Run Input
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/read-flow-run-input

get /api/flow_runs/{id}/input/{key}
Create a value from a flow run input



# Read Flow Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/read-flow-runs

post /api/flow_runs/filter
Query for flow runs.



# Resume Flow Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/resume-flow-run

post /api/flow_runs/{id}/resume
Resume a paused flow run.



# Set Flow Run State
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/set-flow-run-state

post /api/flow_runs/{id}/set_state
Set a flow run state, invoking any orchestration rules.



# Update Flow Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/update-flow-run

patch /api/flow_runs/{id}
Updates a flow run.



# Update Flow Run Labels
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flow-runs/update-flow-run-labels

patch /api/flow_runs/{id}/labels
Update the labels of a flow run.



# Count Flows
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/count-flows

post /api/flows/count
Count flows.



# Create Flow
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/create-flow

post /api/flows/
Gracefully creates a new flow from the provided schema. If a flow with the
same name already exists, the existing flow is returned.

For more information, see https://docs.prefect.io/v3/develop/write-flows.



# Delete Flow
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/delete-flow

delete /api/flows/{id}
Delete a flow by id.



# Paginate Flows
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/paginate-flows

post /api/flows/paginate
Pagination query for flows.



# Read Flow
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/read-flow

get /api/flows/{id}
Get a flow by id.



# Read Flow By Name
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/read-flow-by-name

get /api/flows/name/{name}
Get a flow by name.



# Read Flows
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/read-flows

post /api/flows/filter
Query for flows.



# Update Flow
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/flows/update-flow

patch /api/flows/{id}
Updates a flow.



# Server API Overview
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/index

The Prefect server API enables you to interact programmatically with self-hosted Prefect server.

The self-hosted Prefect server API is organized around REST.
Select links in the left navigation menu to explore.

Learn about [self-hosting Prefect server](/v3/how-to-guides/self-hosted/server-cli).


# Create Logs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/logs/create-logs

post /api/logs/
Create new logs from the provided schema.

For more information, see https://docs.prefect.io/v3/develop/logging.



# Read Logs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/logs/read-logs

post /api/logs/filter
Query for logs.



# Health Check
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/root/health-check

get /api/health



# Hello
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/root/hello

get /api/hello
Say hello!



# Perform Readiness Check
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/root/perform-readiness-check

get /api/ready



# Server Version
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/root/server-version

get /api/version



# Create Saved Search
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/savedsearches/create-saved-search

put /api/saved_searches/
Gracefully creates a new saved search from the provided schema.

If a saved search with the same name already exists, the saved search's fields are
replaced.



# Delete Saved Search
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/savedsearches/delete-saved-search

delete /api/saved_searches/{id}
Delete a saved search by id.



# Read Saved Search
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/savedsearches/read-saved-search

get /api/saved_searches/{id}
Get a saved search by id.



# Read Saved Searches
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/savedsearches/read-saved-searches

post /api/saved_searches/filter
Query for saved searches.



# Read Task Run State
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-run-states/read-task-run-state

get /api/task_run_states/{id}
Get a task run state by id.

For more information, see https://docs.prefect.io/v3/develop/write-tasks.



# Read Task Run States
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-run-states/read-task-run-states

get /api/task_run_states/
Get states associated with a task run.



# Count Task Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/count-task-runs

post /api/task_runs/count
Count task runs.



# Create Task Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/create-task-run

post /api/task_runs/
Create a task run. If a task run with the same flow_run_id,
task_key, and dynamic_key already exists, the existing task
run will be returned.

If no state is provided, the task run will be created in a PENDING state.

For more information, see https://docs.prefect.io/v3/develop/write-tasks.



# Delete Task Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/delete-task-run

delete /api/task_runs/{id}
Delete a task run by id.



# Paginate Task Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/paginate-task-runs

post /api/task_runs/paginate
Pagination query for task runs.



# Read Task Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/read-task-run

get /api/task_runs/{id}
Get a task run by id.



# Read Task Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/read-task-runs

post /api/task_runs/filter
Query for task runs.



# Set Task Run State
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/set-task-run-state

post /api/task_runs/{id}/set_state
Set a task run state, invoking any orchestration rules.



# Task Run History
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/task-run-history

post /api/task_runs/history
Query for task run history data across a given range and interval.



# Update Task Run
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-runs/update-task-run

patch /api/task_runs/{id}
Updates a task run.



# Read Task Workers
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/task-workers/read-task-workers

post /api/task_workers/filter
Read active task workers. Optionally filter by task keys.

For more information, see https://docs.prefect.io/v3/concepts/flows-and-tasks#background-tasks.



# Count Variables
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/count-variables

post /api/variables/count



# Create Variable
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/create-variable

post /api/variables/
Create a variable.

For more information, see https://docs.prefect.io/v3/develop/variables.



# Delete Variable
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/delete-variable

delete /api/variables/{id}



# Delete Variable By Name
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/delete-variable-by-name

delete /api/variables/name/{name}



# Read Variable
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/read-variable

get /api/variables/{id}



# Read Variable By Name
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/read-variable-by-name

get /api/variables/name/{name}



# Read Variables
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/read-variables

post /api/variables/filter



# Update Variable
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/update-variable

patch /api/variables/{id}



# Update Variable By Name
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/variables/update-variable-by-name

patch /api/variables/name/{name}



# Count Work Pools
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/count-work-pools

post /api/work_pools/count
Count work pools



# Create Work Pool
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/create-work-pool

post /api/work_pools/
Creates a new work pool. If a work pool with the same
name already exists, an error will be raised.

For more information, see https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools.



# Create Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/create-work-queue

post /api/work_pools/{work_pool_name}/queues
Creates a new work pool queue. If a work pool queue with the same
name already exists, an error will be raised.

For more information, see https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues.



# Delete Work Pool
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/delete-work-pool

delete /api/work_pools/{name}
Delete a work pool



# Delete Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/delete-work-queue

delete /api/work_pools/{work_pool_name}/queues/{name}
Delete a work pool queue



# Delete Worker
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/delete-worker

delete /api/work_pools/{work_pool_name}/workers/{name}
Delete a work pool's worker



# Get Scheduled Flow Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/get-scheduled-flow-runs

post /api/work_pools/{name}/get_scheduled_flow_runs
Load scheduled runs for a worker



# Read Work Pool
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/read-work-pool

get /api/work_pools/{name}
Read a work pool by name



# Read Work Pools
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/read-work-pools

post /api/work_pools/filter
Read multiple work pools



# Read Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/read-work-queue

get /api/work_pools/{work_pool_name}/queues/{name}
Read a work pool queue



# Read Work Queues
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/read-work-queues

post /api/work_pools/{work_pool_name}/queues/filter
Read all work pool queues



# Read Workers
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/read-workers

post /api/work_pools/{work_pool_name}/workers/filter
Read all worker processes



# Update Work Pool
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/update-work-pool

patch /api/work_pools/{name}
Update a work pool



# Update Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/update-work-queue

patch /api/work_pools/{work_pool_name}/queues/{name}
Update a work pool queue



# Worker Heartbeat
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-pools/worker-heartbeat

post /api/work_pools/{work_pool_name}/workers/heartbeat



# Create Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/create-work-queue

post /api/work_queues/
Creates a new work queue.

If a work queue with the same name already exists, an error
will be raised.

For more information, see https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues.



# Delete Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/delete-work-queue

delete /api/work_queues/{id}
Delete a work queue by id.



# Read Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/read-work-queue

get /api/work_queues/{id}
Get a work queue by id.



# Read Work Queue By Name
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/read-work-queue-by-name

get /api/work_queues/name/{name}
Get a work queue by id.



# Read Work Queue Runs
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/read-work-queue-runs

post /api/work_queues/{id}/get_runs
Get flow runs from the work queue.



# Read Work Queue Status
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/read-work-queue-status

get /api/work_queues/{id}/status
Get the status of a work queue.



# Read Work Queues
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/read-work-queues

post /api/work_queues/filter
Query for work queues.



# Update Work Queue
Source: https://docs-3.prefect.io/v3/api-ref/rest-api/server/work-queues/update-work-queue

patch /api/work_queues/{id}
Updates an existing work queue.



# Settings reference
Source: https://docs-3.prefect.io/v3/api-ref/settings-ref

Reference for all available settings for Prefect.

{/* This page is generated by `scripts/generate_settings_ref.py`. Update the generation script to update this page. */}

<Note>To use `prefect.toml` or `pyproject.toml` for configuration, `prefect>=3.1` must be installed.</Note>

## Root Settings

### `home`

The path to the Prefect home directory. Defaults to \~/.prefect

**Type**: `string`

**Default**: `~/.prefect`

**TOML dotted key path**: `home`

**Supported environment variables**:
`PREFECT_HOME`

### `profiles_path`

The path to a profiles configuration file. Supports \$PREFECT\_HOME templating. Defaults to \$PREFECT\_HOME/profiles.toml.

**Type**: `string`

**TOML dotted key path**: `profiles_path`

**Supported environment variables**:
`PREFECT_PROFILES_PATH`

### `debug_mode`

If True, enables debug mode which may provide additional logging and debugging features.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `debug_mode`

**Supported environment variables**:
`PREFECT_DEBUG_MODE`

### `api`

**Type**: [APISettings](#apisettings)

**TOML dotted key path**: `api`

### `cli`

**Type**: [CLISettings](#clisettings)

**TOML dotted key path**: `cli`

### `client`

**Type**: [ClientSettings](#clientsettings)

**TOML dotted key path**: `client`

### `cloud`

**Type**: [CloudSettings](#cloudsettings)

**TOML dotted key path**: `cloud`

### `deployments`

**Type**: [DeploymentsSettings](#deploymentssettings)

**TOML dotted key path**: `deployments`

### `experiments`

Settings for controlling experimental features

**Type**: [ExperimentsSettings](#experimentssettings)

**TOML dotted key path**: `experiments`

### `flows`

**Type**: [FlowsSettings](#flowssettings)

**TOML dotted key path**: `flows`

### `internal`

Settings for internal Prefect machinery

**Type**: [InternalSettings](#internalsettings)

**TOML dotted key path**: `internal`

### `logging`

**Type**: [LoggingSettings](#loggingsettings)

**TOML dotted key path**: `logging`

### `results`

**Type**: [ResultsSettings](#resultssettings)

**TOML dotted key path**: `results`

### `runner`

**Type**: [RunnerSettings](#runnersettings)

**TOML dotted key path**: `runner`

### `server`

**Type**: [ServerSettings](#serversettings)

**TOML dotted key path**: `server`

### `tasks`

Settings for controlling task behavior

**Type**: [TasksSettings](#taskssettings)

**TOML dotted key path**: `tasks`

### `testing`

Settings used during testing

**Type**: [TestingSettings](#testingsettings)

**TOML dotted key path**: `testing`

### `worker`

Settings for controlling worker behavior

**Type**: [WorkerSettings](#workersettings)

**TOML dotted key path**: `worker`

### `ui_url`

The URL of the Prefect UI. If not set, the client will attempt to infer it.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `ui_url`

**Supported environment variables**:
`PREFECT_UI_URL`

### `silence_api_url_misconfiguration`

If `True`, disable the warning when a user accidentally misconfigure its `PREFECT_API_URL`
Sometimes when a user manually set `PREFECT_API_URL` to a custom url,reverse-proxy for example,
we would like to silence this warning so we will set it to `FALSE`.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `silence_api_url_misconfiguration`

**Supported environment variables**:
`PREFECT_SILENCE_API_URL_MISCONFIGURATION`

***

## APISettings

Settings for interacting with the Prefect API

### `url`

The URL of the Prefect API. If not set, the client will attempt to infer it.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `api.url`

**Supported environment variables**:
`PREFECT_API_URL`

### `auth_string`

The auth string used for basic authentication with a self-hosted Prefect API. Should be kept secret.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `api.auth_string`

**Supported environment variables**:
`PREFECT_API_AUTH_STRING`

### `key`

The API key used for authentication with the Prefect API. Should be kept secret.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `api.key`

**Supported environment variables**:
`PREFECT_API_KEY`

### `tls_insecure_skip_verify`

If `True`, disables SSL checking to allow insecure requests. Setting to False is recommended only during development. For example, when using self-signed certificates.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `api.tls_insecure_skip_verify`

**Supported environment variables**:
`PREFECT_API_TLS_INSECURE_SKIP_VERIFY`

### `ssl_cert_file`

This configuration settings option specifies the path to an SSL certificate file.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `api.ssl_cert_file`

**Supported environment variables**:
`PREFECT_API_SSL_CERT_FILE`

### `enable_http2`

If true, enable support for HTTP/2 for communicating with an API. If the API does not support HTTP/2, this will have no effect and connections will be made via HTTP/1.1.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `api.enable_http2`

**Supported environment variables**:
`PREFECT_API_ENABLE_HTTP2`

### `request_timeout`

The default timeout for requests to the API

**Type**: `number`

**Default**: `60.0`

**TOML dotted key path**: `api.request_timeout`

**Supported environment variables**:
`PREFECT_API_REQUEST_TIMEOUT`

***

## CLISettings

Settings for controlling CLI behavior

### `colors`

If True, use colors in CLI output. If `False`, output will not include colors codes.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `cli.colors`

**Supported environment variables**:
`PREFECT_CLI_COLORS`

### `prompt`

If `True`, use interactive prompts in CLI commands. If `False`, no interactive prompts will be used. If `None`, the value will be dynamically determined based on the presence of an interactive-enabled terminal.

**Type**: `boolean | None`

**Default**: `None`

**TOML dotted key path**: `cli.prompt`

**Supported environment variables**:
`PREFECT_CLI_PROMPT`

### `wrap_lines`

If `True`, wrap text by inserting new lines in long lines in CLI output. If `False`, output will not be wrapped.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `cli.wrap_lines`

**Supported environment variables**:
`PREFECT_CLI_WRAP_LINES`

***

## ClientMetricsSettings

Settings for controlling metrics reporting from the client

### `enabled`

Whether or not to enable Prometheus metrics in the client.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `client.metrics.enabled`

**Supported environment variables**:
`PREFECT_CLIENT_METRICS_ENABLED`, `PREFECT_CLIENT_ENABLE_METRICS`

### `port`

The port to expose the client Prometheus metrics on.

**Type**: `integer`

**Default**: `4201`

**TOML dotted key path**: `client.metrics.port`

**Supported environment variables**:
`PREFECT_CLIENT_METRICS_PORT`

***

## ClientSettings

Settings for controlling API client behavior

### `max_retries`

The maximum number of retries to perform on failed HTTP requests.
Defaults to 5. Set to 0 to disable retries.
See `PREFECT_CLIENT_RETRY_EXTRA_CODES` for details on which HTTP status codes are
retried.

**Type**: `integer`

**Default**: `5`

**Constraints**:

* Minimum: 0

**TOML dotted key path**: `client.max_retries`

**Supported environment variables**:
`PREFECT_CLIENT_MAX_RETRIES`

### `retry_jitter_factor`

A value greater than or equal to zero to control the amount of jitter added to retried
client requests. Higher values introduce larger amounts of jitter.
Set to 0 to disable jitter. See `clamped_poisson_interval` for details on the how jitter
can affect retry lengths.

**Type**: `number`

**Default**: `0.2`

**Constraints**:

* Minimum: 0.0

**TOML dotted key path**: `client.retry_jitter_factor`

**Supported environment variables**:
`PREFECT_CLIENT_RETRY_JITTER_FACTOR`

### `retry_extra_codes`

A list of extra HTTP status codes to retry on. Defaults to an empty list.
429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying
may result in unexpected behavior.

**Type**: `string | integer | array | None`

**Examples**:

* `"404,429,503"`
* `"429"`
* `[404, 429, 503]`

**TOML dotted key path**: `client.retry_extra_codes`

**Supported environment variables**:
`PREFECT_CLIENT_RETRY_EXTRA_CODES`

### `csrf_support_enabled`

Determines if CSRF token handling is active in the Prefect client for API
requests.

When enabled (`True`), the client automatically manages CSRF tokens by
retrieving, storing, and including them in applicable state-changing requests

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `client.csrf_support_enabled`

**Supported environment variables**:
`PREFECT_CLIENT_CSRF_SUPPORT_ENABLED`

### `custom_headers`

Custom HTTP headers to include with every API request to the Prefect server.
Headers are specified as key-value pairs. Note that headers like 'User-Agent'
and CSRF-related headers are managed by Prefect and cannot be overridden.

**Type**: `object`

**Examples**:

* `{'X-Custom-Header': 'value'}`
* `{'Authorization': 'Bearer token'}`

**TOML dotted key path**: `client.custom_headers`

**Supported environment variables**:
`PREFECT_CLIENT_CUSTOM_HEADERS`

### `metrics`

**Type**: [ClientMetricsSettings](#clientmetricssettings)

**TOML dotted key path**: `client.metrics`

***

## CloudSettings

Settings for interacting with Prefect Cloud

### `api_url`

API URL for Prefect Cloud. Used for authentication with Prefect Cloud.

**Type**: `string`

**Default**: `https://api.prefect.cloud/api`

**TOML dotted key path**: `cloud.api_url`

**Supported environment variables**:
`PREFECT_CLOUD_API_URL`

### `enable_orchestration_telemetry`

Whether or not to enable orchestration telemetry.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `cloud.enable_orchestration_telemetry`

**Supported environment variables**:
`PREFECT_CLOUD_ENABLE_ORCHESTRATION_TELEMETRY`

### `ui_url`

The URL of the Prefect Cloud UI. If not set, the client will attempt to infer it.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `cloud.ui_url`

**Supported environment variables**:
`PREFECT_CLOUD_UI_URL`

***

## DeploymentsSettings

Settings for configuring deployments defaults

### `default_work_pool_name`

The default work pool to use when creating deployments.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `deployments.default_work_pool_name`

**Supported environment variables**:
`PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME`, `PREFECT_DEFAULT_WORK_POOL_NAME`

### `default_docker_build_namespace`

The default Docker namespace to use when building images.

**Type**: `string | None`

**Default**: `None`

**Examples**:

* `"my-dockerhub-registry"`
* `"4999999999999.dkr.ecr.us-east-2.amazonaws.com/my-ecr-repo"`

**TOML dotted key path**: `deployments.default_docker_build_namespace`

**Supported environment variables**:
`PREFECT_DEPLOYMENTS_DEFAULT_DOCKER_BUILD_NAMESPACE`, `PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE`

***

## ExperimentsSettings

Settings for configuring experimental features

### `warn`

If `True`, warn on usage of experimental features.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `experiments.warn`

**Supported environment variables**:
`PREFECT_EXPERIMENTS_WARN`, `PREFECT_EXPERIMENTAL_WARN`

### `lineage_events_enabled`

If `True`, enables emitting lineage events. Set to `False` to disable lineage event emission.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `experiments.lineage_events_enabled`

**Supported environment variables**:
`PREFECT_EXPERIMENTS_LINEAGE_EVENTS_ENABLED`

***

## FlowsSettings

Settings for controlling flow behavior

### `default_retries`

This value sets the default number of retries for all flows.

**Type**: `integer`

**Default**: `0`

**Constraints**:

* Minimum: 0

**TOML dotted key path**: `flows.default_retries`

**Supported environment variables**:
`PREFECT_FLOWS_DEFAULT_RETRIES`, `PREFECT_FLOW_DEFAULT_RETRIES`

### `default_retry_delay_seconds`

This value sets the default retry delay seconds for all flows.

**Type**: `integer | number | array`

**Default**: `0`

**TOML dotted key path**: `flows.default_retry_delay_seconds`

**Supported environment variables**:
`PREFECT_FLOWS_DEFAULT_RETRY_DELAY_SECONDS`, `PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS`

***

## InternalSettings

### `logging_level`

The default logging level for Prefect's internal machinery loggers.

**Type**: `string`

**Default**: `ERROR`

**Constraints**:

* Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

**TOML dotted key path**: `internal.logging_level`

**Supported environment variables**:
`PREFECT_INTERNAL_LOGGING_LEVEL`, `PREFECT_LOGGING_INTERNAL_LEVEL`

***

## LoggingSettings

Settings for controlling logging behavior

### `level`

The default logging level for Prefect loggers.

**Type**: `string`

**Default**: `INFO`

**Constraints**:

* Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

**TOML dotted key path**: `logging.level`

**Supported environment variables**:
`PREFECT_LOGGING_LEVEL`

### `config_path`

A path to a logging configuration file. Defaults to \$PREFECT\_HOME/logging.yml

**Type**: `string`

**TOML dotted key path**: `logging.config_path`

**Supported environment variables**:
`PREFECT_LOGGING_CONFIG_PATH`, `PREFECT_LOGGING_SETTINGS_PATH`

### `extra_loggers`

Additional loggers to attach to Prefect logging at runtime.

**Type**: `string | array | None`

**Default**: `None`

**TOML dotted key path**: `logging.extra_loggers`

**Supported environment variables**:
`PREFECT_LOGGING_EXTRA_LOGGERS`

### `log_prints`

If `True`, `print` statements in flows and tasks will be redirected to the Prefect logger for the given run.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `logging.log_prints`

**Supported environment variables**:
`PREFECT_LOGGING_LOG_PRINTS`

### `colors`

If `True`, use colors in CLI output. If `False`, output will not include colors codes.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `logging.colors`

**Supported environment variables**:
`PREFECT_LOGGING_COLORS`

### `markup`

Whether to interpret strings wrapped in square brackets as a style.
This allows styles to be conveniently added to log messages, e.g.
`[red]This is a red message.[/red]`. However, the downside is, if enabled,
strings that contain square brackets may be inaccurately interpreted and
lead to incomplete output, e.g.
`[red]This is a red message.[/red]` may be interpreted as
`[red]This is a red message.[/red]`.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `logging.markup`

**Supported environment variables**:
`PREFECT_LOGGING_MARKUP`

### `to_api`

**Type**: [LoggingToAPISettings](#loggingtoapisettings)

**TOML dotted key path**: `logging.to_api`

***

## LoggingToAPISettings

Settings for controlling logging to the API

### `enabled`

If `True`, logs will be sent to the API.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `logging.to_api.enabled`

**Supported environment variables**:
`PREFECT_LOGGING_TO_API_ENABLED`

### `batch_interval`

The number of seconds between batched writes of logs to the API.

**Type**: `number`

**Default**: `2.0`

**TOML dotted key path**: `logging.to_api.batch_interval`

**Supported environment variables**:
`PREFECT_LOGGING_TO_API_BATCH_INTERVAL`

### `batch_size`

The number of logs to batch before sending to the API.

**Type**: `integer`

**Default**: `4000000`

**TOML dotted key path**: `logging.to_api.batch_size`

**Supported environment variables**:
`PREFECT_LOGGING_TO_API_BATCH_SIZE`

### `max_log_size`

The maximum size in bytes for a single log.

**Type**: `integer`

**Default**: `1000000`

**TOML dotted key path**: `logging.to_api.max_log_size`

**Supported environment variables**:
`PREFECT_LOGGING_TO_API_MAX_LOG_SIZE`

### `when_missing_flow`

Controls the behavior when loggers attempt to send logs to the API handler from outside of a flow.

All logs sent to the API must be associated with a flow run. The API log handler can
only be used outside of a flow by manually providing a flow run identifier. Logs
that are not associated with a flow run will not be sent to the API. This setting can
be used to determine if a warning or error is displayed when the identifier is missing.

The following options are available:

* "warn": Log a warning message.
* "error": Raise an error.
* "ignore": Do not log a warning message or raise an error.

**Type**: `string`

**Default**: `warn`

**Constraints**:

* Allowed values: 'warn', 'error', 'ignore'

**TOML dotted key path**: `logging.to_api.when_missing_flow`

**Supported environment variables**:
`PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW`

***

## ResultsSettings

Settings for controlling result storage behavior

### `default_serializer`

The default serializer to use when not otherwise specified.

**Type**: `string`

**Default**: `pickle`

**TOML dotted key path**: `results.default_serializer`

**Supported environment variables**:
`PREFECT_RESULTS_DEFAULT_SERIALIZER`

### `persist_by_default`

The default setting for persisting results when not otherwise specified.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `results.persist_by_default`

**Supported environment variables**:
`PREFECT_RESULTS_PERSIST_BY_DEFAULT`

### `default_storage_block`

The `block-type/block-document` slug of a block to use as the default result storage.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `results.default_storage_block`

**Supported environment variables**:
`PREFECT_RESULTS_DEFAULT_STORAGE_BLOCK`, `PREFECT_DEFAULT_RESULT_STORAGE_BLOCK`

### `local_storage_path`

The default location for locally persisted results. Defaults to \$PREFECT\_HOME/storage.

**Type**: `string`

**TOML dotted key path**: `results.local_storage_path`

**Supported environment variables**:
`PREFECT_RESULTS_LOCAL_STORAGE_PATH`, `PREFECT_LOCAL_STORAGE_PATH`

***

## RunnerServerSettings

Settings for controlling runner server behavior

### `enable`

Whether or not to enable the runner's webserver.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `runner.server.enable`

**Supported environment variables**:
`PREFECT_RUNNER_SERVER_ENABLE`

### `host`

The host address the runner's webserver should bind to.

**Type**: `string`

**Default**: `localhost`

**TOML dotted key path**: `runner.server.host`

**Supported environment variables**:
`PREFECT_RUNNER_SERVER_HOST`

### `port`

The port the runner's webserver should bind to.

**Type**: `integer`

**Default**: `8080`

**TOML dotted key path**: `runner.server.port`

**Supported environment variables**:
`PREFECT_RUNNER_SERVER_PORT`

### `log_level`

The log level of the runner's webserver.

**Type**: `string`

**Default**: `ERROR`

**Constraints**:

* Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

**TOML dotted key path**: `runner.server.log_level`

**Supported environment variables**:
`PREFECT_RUNNER_SERVER_LOG_LEVEL`

### `missed_polls_tolerance`

Number of missed polls before a runner is considered unhealthy by its webserver.

**Type**: `integer`

**Default**: `2`

**TOML dotted key path**: `runner.server.missed_polls_tolerance`

**Supported environment variables**:
`PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE`

***

## RunnerSettings

Settings for controlling runner behavior

### `process_limit`

Maximum number of processes a runner will execute in parallel.

**Type**: `integer`

**Default**: `5`

**TOML dotted key path**: `runner.process_limit`

**Supported environment variables**:
`PREFECT_RUNNER_PROCESS_LIMIT`

### `poll_frequency`

Number of seconds a runner should wait between queries for scheduled work.

**Type**: `integer`

**Default**: `10`

**TOML dotted key path**: `runner.poll_frequency`

**Supported environment variables**:
`PREFECT_RUNNER_POLL_FREQUENCY`

### `heartbeat_frequency`

Number of seconds a runner should wait between heartbeats for flow runs.

**Type**: `integer | None`

**Default**: `None`

**TOML dotted key path**: `runner.heartbeat_frequency`

**Supported environment variables**:
`PREFECT_RUNNER_HEARTBEAT_FREQUENCY`

### `server`

**Type**: [RunnerServerSettings](#runnerserversettings)

**TOML dotted key path**: `runner.server`

***

## SQLAlchemyConnectArgsSettings

Settings for controlling SQLAlchemy connection behavior; note that these settings only take effect when
using a PostgreSQL database.

### `application_name`

Controls the application\_name field for connections opened from the connection pool when using a PostgreSQL database with the Prefect backend.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.application_name`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_APPLICATION_NAME`

### `statement_cache_size`

Controls statement cache size for PostgreSQL connections. Setting this to 0 is required when using PgBouncer in transaction mode. Defaults to None.

**Type**: `integer | None`

**Default**: `None`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.statement_cache_size`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_STATEMENT_CACHE_SIZE`

### `prepared_statement_cache_size`

Controls the size of the statement cache for PostgreSQL connections. When set to 0, statement caching is disabled. Defaults to None to use SQLAlchemy's default behavior.

**Type**: `integer | None`

**Default**: `None`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.prepared_statement_cache_size`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_PREPARED_STATEMENT_CACHE_SIZE`

### `tls`

Settings for controlling SQLAlchemy mTLS behavior

**Type**: [SQLAlchemyTLSSettings](#sqlalchemytlssettings)

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.tls`

***

## SQLAlchemySettings

Settings for controlling SQLAlchemy behavior; note that these settings only take effect when
using a PostgreSQL database.

### `connect_args`

Settings for controlling SQLAlchemy connection behavior

**Type**: [SQLAlchemyConnectArgsSettings](#sqlalchemyconnectargssettings)

**TOML dotted key path**: `server.database.sqlalchemy.connect_args`

### `pool_size`

Controls connection pool size of database connection pools from the Prefect backend.

**Type**: `integer`

**Default**: `5`

**TOML dotted key path**: `server.database.sqlalchemy.pool_size`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_SIZE`, `PREFECT_SQLALCHEMY_POOL_SIZE`

### `pool_recycle`

This setting causes the pool to recycle connections after the given number of seconds has passed; set it to -1 to avoid recycling entirely.

**Type**: `integer`

**Default**: `3600`

**TOML dotted key path**: `server.database.sqlalchemy.pool_recycle`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_RECYCLE`

### `pool_timeout`

Number of seconds to wait before giving up on getting a connection from the pool. Defaults to 30 seconds.

**Type**: `number | None`

**Default**: `30.0`

**TOML dotted key path**: `server.database.sqlalchemy.pool_timeout`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_TIMEOUT`

### `max_overflow`

Controls maximum overflow of the connection pool. To prevent overflow, set to -1.

**Type**: `integer`

**Default**: `10`

**TOML dotted key path**: `server.database.sqlalchemy.max_overflow`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_MAX_OVERFLOW`, `PREFECT_SQLALCHEMY_MAX_OVERFLOW`

***

## SQLAlchemyTLSSettings

Settings for controlling SQLAlchemy mTLS context when
using a PostgreSQL database.

### `enabled`

Controls whether connected to mTLS enabled PostgreSQL when using a PostgreSQL database with the Prefect backend.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.tls.enabled`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_ENABLED`

### `ca_file`

This configuration settings option specifies the path to PostgreSQL client certificate authority file.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.tls.ca_file`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CA_FILE`

### `cert_file`

This configuration settings option specifies the path to PostgreSQL client certificate file.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.tls.cert_file`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CERT_FILE`

### `key_file`

This configuration settings option specifies the path to PostgreSQL client key file.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.tls.key_file`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_KEY_FILE`

### `check_hostname`

This configuration settings option specifies whether to verify PostgreSQL server hostname.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.database.sqlalchemy.connect_args.tls.check_hostname`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CHECK_HOSTNAME`

***

## ServerAPISettings

Settings for controlling API server behavior

### `auth_string`

A string to use for basic authentication with the API in the form 'user:password'.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.api.auth_string`

**Supported environment variables**:
`PREFECT_SERVER_API_AUTH_STRING`

### `host`

The API's host address (defaults to `127.0.0.1`).

**Type**: `string`

**Default**: `127.0.0.1`

**TOML dotted key path**: `server.api.host`

**Supported environment variables**:
`PREFECT_SERVER_API_HOST`

### `port`

The API's port address (defaults to `4200`).

**Type**: `integer`

**Default**: `4200`

**TOML dotted key path**: `server.api.port`

**Supported environment variables**:
`PREFECT_SERVER_API_PORT`

### `base_path`

The base URL path to serve the API under.

**Type**: `string | None`

**Default**: `None`

**Examples**:

* `"/v2/api"`

**TOML dotted key path**: `server.api.base_path`

**Supported environment variables**:
`PREFECT_SERVER_API_BASE_PATH`

### `default_limit`

The default limit applied to queries that can return multiple objects, such as `POST /flow_runs/filter`.

**Type**: `integer`

**Default**: `200`

**TOML dotted key path**: `server.api.default_limit`

**Supported environment variables**:
`PREFECT_SERVER_API_DEFAULT_LIMIT`, `PREFECT_API_DEFAULT_LIMIT`

### `keepalive_timeout`

The API's keep alive timeout (defaults to `5`).
Refer to [https://www.uvicorn.org/settings/#timeouts](https://www.uvicorn.org/settings/#timeouts) for details.

When the API is hosted behind a load balancer, you may want to set this to a value
greater than the load balancer's idle timeout.

Note this setting only applies when calling `prefect server start`; if hosting the
API with another tool you will need to configure this there instead.

**Type**: `integer`

**Default**: `5`

**TOML dotted key path**: `server.api.keepalive_timeout`

**Supported environment variables**:
`PREFECT_SERVER_API_KEEPALIVE_TIMEOUT`

### `csrf_protection_enabled`

Controls the activation of CSRF protection for the Prefect server API.

When enabled (`True`), the server enforces CSRF validation checks on incoming
state-changing requests (POST, PUT, PATCH, DELETE), requiring a valid CSRF
token to be included in the request headers or body. This adds a layer of
security by preventing unauthorized or malicious sites from making requests on
behalf of authenticated users.

It is recommended to enable this setting in production environments where the
API is exposed to web clients to safeguard against CSRF attacks.

Note: Enabling this setting requires corresponding support in the client for
CSRF token management. See PREFECT\_CLIENT\_CSRF\_SUPPORT\_ENABLED for more.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.api.csrf_protection_enabled`

**Supported environment variables**:
`PREFECT_SERVER_API_CSRF_PROTECTION_ENABLED`, `PREFECT_SERVER_CSRF_PROTECTION_ENABLED`

### `csrf_token_expiration`

Specifies the duration for which a CSRF token remains valid after being issued
by the server.

The default expiration time is set to 1 hour, which offers a reasonable
compromise. Adjust this setting based on your specific security requirements
and usage patterns.

**Type**: `string`

**Default**: `PT1H`

**TOML dotted key path**: `server.api.csrf_token_expiration`

**Supported environment variables**:
`PREFECT_SERVER_API_CSRF_TOKEN_EXPIRATION`, `PREFECT_SERVER_CSRF_TOKEN_EXPIRATION`

### `cors_allowed_origins`

A comma-separated list of origins that are authorized to make cross-origin requests to the API.

By default, this is set to `*`, which allows requests from all origins.

**Type**: `string`

**Default**: `*`

**TOML dotted key path**: `server.api.cors_allowed_origins`

**Supported environment variables**:
`PREFECT_SERVER_API_CORS_ALLOWED_ORIGINS`, `PREFECT_SERVER_CORS_ALLOWED_ORIGINS`

### `cors_allowed_methods`

A comma-separated list of methods that are authorized to make cross-origin requests to the API.

By default, this is set to `*`, which allows requests from all methods.

**Type**: `string`

**Default**: `*`

**TOML dotted key path**: `server.api.cors_allowed_methods`

**Supported environment variables**:
`PREFECT_SERVER_API_CORS_ALLOWED_METHODS`, `PREFECT_SERVER_CORS_ALLOWED_METHODS`

### `cors_allowed_headers`

A comma-separated list of headers that are authorized to make cross-origin requests to the API.

By default, this is set to `*`, which allows requests from all headers.

**Type**: `string`

**Default**: `*`

**TOML dotted key path**: `server.api.cors_allowed_headers`

**Supported environment variables**:
`PREFECT_SERVER_API_CORS_ALLOWED_HEADERS`, `PREFECT_SERVER_CORS_ALLOWED_HEADERS`

***

## ServerConcurrencySettings

### `lease_storage`

The module to use for storing concurrency limit leases.

**Type**: `string`

**Default**: `prefect.server.concurrency.lease_storage.memory`

**TOML dotted key path**: `server.concurrency.lease_storage`

**Supported environment variables**:
`PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE`

***

## ServerDatabaseSettings

Settings for controlling server database behavior

### `sqlalchemy`

Settings for controlling SQLAlchemy behavior

**Type**: [SQLAlchemySettings](#sqlalchemysettings)

**TOML dotted key path**: `server.database.sqlalchemy`

### `connection_url`

A database connection URL in a SQLAlchemy-compatible
format. Prefect currently supports SQLite and Postgres. Note that all
Prefect database engines must use an async driver - for SQLite, use
`sqlite+aiosqlite` and for Postgres use `postgresql+asyncpg`.

SQLite in-memory databases can be used by providing the url
`sqlite+aiosqlite:///file::memory:?cache=shared&uri=true&check_same_thread=false`,
which will allow the database to be accessed by multiple threads. Note
that in-memory databases can not be accessed from multiple processes and
should only be used for simple tests.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.connection_url`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_CONNECTION_URL`, `PREFECT_API_DATABASE_CONNECTION_URL`

### `driver`

The database driver to use when connecting to the database. If not set, the driver will be inferred from the connection URL.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.driver`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_DRIVER`, `PREFECT_API_DATABASE_DRIVER`

### `host`

The database server host.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.host`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_HOST`, `PREFECT_API_DATABASE_HOST`

### `port`

The database server port.

**Type**: `integer | None`

**Default**: `None`

**TOML dotted key path**: `server.database.port`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_PORT`, `PREFECT_API_DATABASE_PORT`

### `user`

The user to use when connecting to the database.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.user`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_USER`, `PREFECT_API_DATABASE_USER`

### `name`

The name of the Prefect database on the remote server, or the path to the database file for SQLite.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.name`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_NAME`, `PREFECT_API_DATABASE_NAME`

### `password`

The password to use when connecting to the database. Should be kept secret.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.database.password`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_PASSWORD`, `PREFECT_API_DATABASE_PASSWORD`

### `echo`

If `True`, SQLAlchemy will log all SQL issued to the database. Defaults to `False`.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.database.echo`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_ECHO`, `PREFECT_API_DATABASE_ECHO`

### `migrate_on_start`

If `True`, the database will be migrated on application startup.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.database.migrate_on_start`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_MIGRATE_ON_START`, `PREFECT_API_DATABASE_MIGRATE_ON_START`

### `timeout`

A statement timeout, in seconds, applied to all database interactions made by the Prefect backend. Defaults to 10 seconds.

**Type**: `number | None`

**Default**: `10.0`

**TOML dotted key path**: `server.database.timeout`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_TIMEOUT`, `PREFECT_API_DATABASE_TIMEOUT`

### `connection_timeout`

A connection timeout, in seconds, applied to database connections. Defaults to `5`.

**Type**: `number | None`

**Default**: `5.0`

**TOML dotted key path**: `server.database.connection_timeout`

**Supported environment variables**:
`PREFECT_SERVER_DATABASE_CONNECTION_TIMEOUT`, `PREFECT_API_DATABASE_CONNECTION_TIMEOUT`

***

## ServerDeploymentsSettings

### `concurrency_slot_wait_seconds`

The number of seconds to wait before retrying when a deployment flow run cannot secure a concurrency slot from the server.

**Type**: `number`

**Default**: `30.0`

**Constraints**:

* Minimum: 0.0

**TOML dotted key path**: `server.deployments.concurrency_slot_wait_seconds`

**Supported environment variables**:
`PREFECT_SERVER_DEPLOYMENTS_CONCURRENCY_SLOT_WAIT_SECONDS`, `PREFECT_DEPLOYMENT_CONCURRENCY_SLOT_WAIT_SECONDS`

***

## ServerEphemeralSettings

Settings for controlling ephemeral server behavior

### `enabled`

Controls whether or not a subprocess server can be started when no API URL is provided.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.ephemeral.enabled`

**Supported environment variables**:
`PREFECT_SERVER_EPHEMERAL_ENABLED`, `PREFECT_SERVER_ALLOW_EPHEMERAL_MODE`

### `startup_timeout_seconds`

The number of seconds to wait for the server to start when ephemeral mode is enabled.
Defaults to `20`.

**Type**: `integer`

**Default**: `20`

**TOML dotted key path**: `server.ephemeral.startup_timeout_seconds`

**Supported environment variables**:
`PREFECT_SERVER_EPHEMERAL_STARTUP_TIMEOUT_SECONDS`

***

## ServerEventsSettings

Settings for controlling behavior of the events subsystem

### `stream_out_enabled`

Whether or not to stream events out to the API via websockets.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.events.stream_out_enabled`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_STREAM_OUT_ENABLED`, `PREFECT_API_EVENTS_STREAM_OUT_ENABLED`

### `related_resource_cache_ttl`

The number of seconds to cache related resources for in the API.

**Type**: `string`

**Default**: `PT5M`

**TOML dotted key path**: `server.events.related_resource_cache_ttl`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_RELATED_RESOURCE_CACHE_TTL`, `PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL`

### `maximum_labels_per_resource`

The maximum number of labels a resource may have.

**Type**: `integer`

**Default**: `500`

**TOML dotted key path**: `server.events.maximum_labels_per_resource`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_MAXIMUM_LABELS_PER_RESOURCE`, `PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE`

### `maximum_related_resources`

The maximum number of related resources an Event may have.

**Type**: `integer`

**Default**: `100`

**TOML dotted key path**: `server.events.maximum_related_resources`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_MAXIMUM_RELATED_RESOURCES`, `PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES`

### `maximum_size_bytes`

The maximum size of an Event when serialized to JSON

**Type**: `integer`

**Default**: `1500000`

**TOML dotted key path**: `server.events.maximum_size_bytes`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_MAXIMUM_SIZE_BYTES`, `PREFECT_EVENTS_MAXIMUM_SIZE_BYTES`

### `expired_bucket_buffer`

The amount of time to retain expired automation buckets

**Type**: `string`

**Default**: `PT1M`

**TOML dotted key path**: `server.events.expired_bucket_buffer`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_EXPIRED_BUCKET_BUFFER`, `PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER`

### `proactive_granularity`

How frequently proactive automations are evaluated

**Type**: `string`

**Default**: `PT5S`

**TOML dotted key path**: `server.events.proactive_granularity`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_PROACTIVE_GRANULARITY`, `PREFECT_EVENTS_PROACTIVE_GRANULARITY`

### `retention_period`

The amount of time to retain events in the database.

**Type**: `string`

**Default**: `P7D`

**TOML dotted key path**: `server.events.retention_period`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_RETENTION_PERIOD`, `PREFECT_EVENTS_RETENTION_PERIOD`

### `maximum_websocket_backfill`

The maximum range to look back for backfilling events for a websocket subscriber.

**Type**: `string`

**Default**: `PT15M`

**TOML dotted key path**: `server.events.maximum_websocket_backfill`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL`, `PREFECT_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL`

### `websocket_backfill_page_size`

The page size for the queries to backfill events for websocket subscribers.

**Type**: `integer`

**Default**: `250`

**TOML dotted key path**: `server.events.websocket_backfill_page_size`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE`, `PREFECT_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE`

### `messaging_broker`

Which message broker implementation to use for the messaging system, should point to a module that exports a Publisher and Consumer class.

**Type**: `string`

**Default**: `prefect.server.utilities.messaging.memory`

**TOML dotted key path**: `server.events.messaging_broker`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_MESSAGING_BROKER`, `PREFECT_MESSAGING_BROKER`

### `messaging_cache`

Which cache implementation to use for the events system. Should point to a module that exports a Cache class.

**Type**: `string`

**Default**: `prefect.server.utilities.messaging.memory`

**TOML dotted key path**: `server.events.messaging_cache`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_MESSAGING_CACHE`, `PREFECT_MESSAGING_CACHE`

### `causal_ordering`

Which causal ordering implementation to use for the events system. Should point to a module that exports a CausalOrdering class.

**Type**: `string`

**Default**: `prefect.server.events.ordering.memory`

**TOML dotted key path**: `server.events.causal_ordering`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_CAUSAL_ORDERING`

### `maximum_event_name_length`

The maximum length of an event name.

**Type**: `integer`

**Default**: `1024`

**TOML dotted key path**: `server.events.maximum_event_name_length`

**Supported environment variables**:
`PREFECT_SERVER_EVENTS_MAXIMUM_EVENT_NAME_LENGTH`

***

## ServerFlowRunGraphSettings

Settings for controlling behavior of the flow run graph

### `max_nodes`

The maximum size of a flow run graph on the v2 API

**Type**: `integer`

**Default**: `10000`

**TOML dotted key path**: `server.flow_run_graph.max_nodes`

**Supported environment variables**:
`PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_NODES`, `PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES`

### `max_artifacts`

The maximum number of artifacts to show on a flow run graph on the v2 API

**Type**: `integer`

**Default**: `10000`

**TOML dotted key path**: `server.flow_run_graph.max_artifacts`

**Supported environment variables**:
`PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_ARTIFACTS`, `PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS`

***

## ServerLogsSettings

Settings for controlling behavior of the logs subsystem

### `stream_out_enabled`

Whether or not to stream logs out to the API via websockets.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.logs.stream_out_enabled`

**Supported environment variables**:
`PREFECT_SERVER_LOGS_STREAM_OUT_ENABLED`

### `stream_publishing_enabled`

Whether or not to publish logs to the streaming system.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.logs.stream_publishing_enabled`

**Supported environment variables**:
`PREFECT_SERVER_LOGS_STREAM_PUBLISHING_ENABLED`

***

## ServerServicesCancellationCleanupSettings

Settings for controlling the cancellation cleanup service

### `enabled`

Whether or not to start the cancellation cleanup service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.cancellation_cleanup.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_ENABLED`, `PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED`

### `loop_seconds`

The cancellation cleanup service will look for non-terminal tasks and subflows this often. Defaults to `20`.

**Type**: `number`

**Default**: `20`

**TOML dotted key path**: `server.services.cancellation_cleanup.loop_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS`, `PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS`

***

## ServerServicesEventLoggerSettings

Settings for controlling the event logger service

### `enabled`

Whether or not to start the event logger service in the server application.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.services.event_logger.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_EVENT_LOGGER_ENABLED`, `PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED`

***

## ServerServicesEventPersisterSettings

Settings for controlling the event persister service

### `enabled`

Whether or not to start the event persister service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.event_persister.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_EVENT_PERSISTER_ENABLED`, `PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED`

### `batch_size`

The number of events the event persister will attempt to insert in one batch.

**Type**: `integer`

**Default**: `20`

**TOML dotted key path**: `server.services.event_persister.batch_size`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_EVENT_PERSISTER_BATCH_SIZE`, `PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE`

### `flush_interval`

The maximum number of seconds between flushes of the event persister.

**Type**: `number`

**Default**: `5`

**TOML dotted key path**: `server.services.event_persister.flush_interval`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL`, `PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL`

### `batch_size_delete`

The number of expired events and event resources the event persister will attempt to delete in one batch.

**Type**: `integer`

**Default**: `10000`

**TOML dotted key path**: `server.services.event_persister.batch_size_delete`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_EVENT_PERSISTER_BATCH_SIZE_DELETE`

***

## ServerServicesForemanSettings

Settings for controlling the foreman service

### `enabled`

Whether or not to start the foreman service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.foreman.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_FOREMAN_ENABLED`, `PREFECT_API_SERVICES_FOREMAN_ENABLED`

### `loop_seconds`

The foreman service will check for offline workers this often. Defaults to `15`.

**Type**: `number`

**Default**: `15`

**TOML dotted key path**: `server.services.foreman.loop_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_FOREMAN_LOOP_SECONDS`, `PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS`

### `inactivity_heartbeat_multiple`

The number of heartbeats that must be missed before a worker is marked as offline. Defaults to `3`.

**Type**: `integer`

**Default**: `3`

**TOML dotted key path**: `server.services.foreman.inactivity_heartbeat_multiple`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE`, `PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE`

### `fallback_heartbeat_interval_seconds`

The number of seconds to use for online/offline evaluation if a worker's heartbeat
interval is not set. Defaults to `30`.

**Type**: `integer`

**Default**: `30`

**TOML dotted key path**: `server.services.foreman.fallback_heartbeat_interval_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS`, `PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS`

### `deployment_last_polled_timeout_seconds`

The number of seconds before a deployment is marked as not ready if it has not been
polled. Defaults to `60`.

**Type**: `integer`

**Default**: `60`

**TOML dotted key path**: `server.services.foreman.deployment_last_polled_timeout_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS`, `PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS`

### `work_queue_last_polled_timeout_seconds`

The number of seconds before a work queue is marked as not ready if it has not been
polled. Defaults to `60`.

**Type**: `integer`

**Default**: `60`

**TOML dotted key path**: `server.services.foreman.work_queue_last_polled_timeout_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS`, `PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS`

***

## ServerServicesLateRunsSettings

Settings for controlling the late runs service

### `enabled`

Whether or not to start the late runs service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.late_runs.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_LATE_RUNS_ENABLED`, `PREFECT_API_SERVICES_LATE_RUNS_ENABLED`

### `loop_seconds`

The late runs service will look for runs to mark as late this often. Defaults to `5`.

**Type**: `number`

**Default**: `5`

**TOML dotted key path**: `server.services.late_runs.loop_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_LATE_RUNS_LOOP_SECONDS`, `PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS`

### `after_seconds`

The late runs service will mark runs as late after they have exceeded their scheduled start time by this many seconds. Defaults to `5` seconds.

**Type**: `string`

**Default**: `PT15S`

**TOML dotted key path**: `server.services.late_runs.after_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_LATE_RUNS_AFTER_SECONDS`, `PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS`

***

## ServerServicesPauseExpirationsSettings

Settings for controlling the pause expiration service

### `enabled`

Whether or not to start the paused flow run expiration service in the server
application. If disabled, paused flows that have timed out will remain in a Paused state
until a resume attempt.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.pause_expirations.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_ENABLED`, `PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED`

### `loop_seconds`

The pause expiration service will look for runs to mark as failed this often. Defaults to `5`.

**Type**: `number`

**Default**: `5`

**TOML dotted key path**: `server.services.pause_expirations.loop_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS`, `PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS`

***

## ServerServicesRepossessorSettings

Settings for controlling the repossessor service

### `enabled`

Whether or not to start the repossessor service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.repossessor.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_REPOSSESSOR_ENABLED`

### `loop_seconds`

The repossessor service will look for expired leases this often. Defaults to `15`.

**Type**: `number`

**Default**: `15`

**TOML dotted key path**: `server.services.repossessor.loop_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_REPOSSESSOR_LOOP_SECONDS`

***

## ServerServicesSchedulerSettings

Settings for controlling the scheduler service

### `enabled`

Whether or not to start the scheduler service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.scheduler.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_ENABLED`, `PREFECT_API_SERVICES_SCHEDULER_ENABLED`

### `loop_seconds`

The scheduler loop interval, in seconds. This determines
how often the scheduler will attempt to schedule new flow runs, but has no
impact on how quickly either flow runs or task runs are actually executed.
Defaults to `60`.

**Type**: `number`

**Default**: `60`

**TOML dotted key path**: `server.services.scheduler.loop_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_LOOP_SECONDS`, `PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS`

### `deployment_batch_size`

The number of deployments the scheduler will attempt to
schedule in a single batch. If there are more deployments than the batch
size, the scheduler immediately attempts to schedule the next batch; it
does not sleep for `scheduler_loop_seconds` until it has visited every
deployment once. Defaults to `100`.

**Type**: `integer`

**Default**: `100`

**TOML dotted key path**: `server.services.scheduler.deployment_batch_size`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE`, `PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE`

### `max_runs`

The scheduler will attempt to schedule up to this many
auto-scheduled runs in the future. Note that runs may have fewer than
this many scheduled runs, depending on the value of
`scheduler_max_scheduled_time`.  Defaults to `100`.

**Type**: `integer`

**Default**: `100`

**TOML dotted key path**: `server.services.scheduler.max_runs`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_MAX_RUNS`, `PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS`

### `min_runs`

The scheduler will attempt to schedule at least this many
auto-scheduled runs in the future. Note that runs may have more than
this many scheduled runs, depending on the value of
`scheduler_min_scheduled_time`.  Defaults to `3`.

**Type**: `integer`

**Default**: `3`

**TOML dotted key path**: `server.services.scheduler.min_runs`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_MIN_RUNS`, `PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS`

### `max_scheduled_time`

The scheduler will create new runs up to this far in the
future. Note that this setting will take precedence over
`scheduler_max_runs`: if a flow runs once a month and
`scheduler_max_scheduled_time` is three months, then only three runs will be
scheduled. Defaults to 100 days (`8640000` seconds).

**Type**: `string`

**Default**: `P100D`

**TOML dotted key path**: `server.services.scheduler.max_scheduled_time`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME`, `PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME`

### `min_scheduled_time`

The scheduler will create new runs at least this far in the
future. Note that this setting will take precedence over `scheduler_min_runs`:
if a flow runs every hour and `scheduler_min_scheduled_time` is three hours,
then three runs will be scheduled even if `scheduler_min_runs` is 1. Defaults to

**Type**: `string`

**Default**: `PT1H`

**TOML dotted key path**: `server.services.scheduler.min_scheduled_time`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME`, `PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME`

### `insert_batch_size`

The number of runs the scheduler will attempt to insert in a single batch.
Defaults to `500`.

**Type**: `integer`

**Default**: `500`

**TOML dotted key path**: `server.services.scheduler.insert_batch_size`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_INSERT_BATCH_SIZE`, `PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE`

### `recent_deployments_loop_seconds`

The number of seconds the recent deployments scheduler will wait between checking for recently updated deployments. Defaults to `5`.

**Type**: `number`

**Default**: `5`

**TOML dotted key path**: `server.services.scheduler.recent_deployments_loop_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_SCHEDULER_RECENT_DEPLOYMENTS_LOOP_SECONDS`

***

## ServerServicesSettings

Settings for controlling server services

### `cancellation_cleanup`

**Type**: [ServerServicesCancellationCleanupSettings](#serverservicescancellationcleanupsettings)

**TOML dotted key path**: `server.services.cancellation_cleanup`

### `event_persister`

**Type**: [ServerServicesEventPersisterSettings](#serverserviceseventpersistersettings)

**TOML dotted key path**: `server.services.event_persister`

### `event_logger`

**Type**: [ServerServicesEventLoggerSettings](#serverserviceseventloggersettings)

**TOML dotted key path**: `server.services.event_logger`

### `foreman`

**Type**: [ServerServicesForemanSettings](#serverservicesforemansettings)

**TOML dotted key path**: `server.services.foreman`

### `late_runs`

**Type**: [ServerServicesLateRunsSettings](#serverserviceslaterunssettings)

**TOML dotted key path**: `server.services.late_runs`

### `scheduler`

**Type**: [ServerServicesSchedulerSettings](#serverservicesschedulersettings)

**TOML dotted key path**: `server.services.scheduler`

### `pause_expirations`

**Type**: [ServerServicesPauseExpirationsSettings](#serverservicespauseexpirationssettings)

**TOML dotted key path**: `server.services.pause_expirations`

### `repossessor`

**Type**: [ServerServicesRepossessorSettings](#serverservicesrepossessorsettings)

**TOML dotted key path**: `server.services.repossessor`

### `task_run_recorder`

**Type**: [ServerServicesTaskRunRecorderSettings](#serverservicestaskrunrecordersettings)

**TOML dotted key path**: `server.services.task_run_recorder`

### `triggers`

**Type**: [ServerServicesTriggersSettings](#serverservicestriggerssettings)

**TOML dotted key path**: `server.services.triggers`

***

## ServerServicesTaskRunRecorderSettings

Settings for controlling the task run recorder service

### `enabled`

Whether or not to start the task run recorder service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.task_run_recorder.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_TASK_RUN_RECORDER_ENABLED`, `PREFECT_API_SERVICES_TASK_RUN_RECORDER_ENABLED`

***

## ServerServicesTriggersSettings

Settings for controlling the triggers service

### `enabled`

Whether or not to start the triggers service in the server application.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.services.triggers.enabled`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_TRIGGERS_ENABLED`, `PREFECT_API_SERVICES_TRIGGERS_ENABLED`

### `pg_notify_reconnect_interval_seconds`

The number of seconds to wait before reconnecting to the PostgreSQL NOTIFY/LISTEN
connection after an error. Only used when using PostgreSQL as the database.
Defaults to `10`.

**Type**: `integer`

**Default**: `10`

**TOML dotted key path**: `server.services.triggers.pg_notify_reconnect_interval_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_TRIGGERS_PG_NOTIFY_RECONNECT_INTERVAL_SECONDS`

### `pg_notify_heartbeat_interval_seconds`

The number of seconds between heartbeat checks for the PostgreSQL NOTIFY/LISTEN
connection to ensure it's still alive. Only used when using PostgreSQL as the database.
Defaults to `5`.

**Type**: `integer`

**Default**: `5`

**TOML dotted key path**: `server.services.triggers.pg_notify_heartbeat_interval_seconds`

**Supported environment variables**:
`PREFECT_SERVER_SERVICES_TRIGGERS_PG_NOTIFY_HEARTBEAT_INTERVAL_SECONDS`

***

## ServerSettings

Settings for controlling server behavior

### `logging_level`

The default logging level for the Prefect API server.

**Type**: `string`

**Default**: `WARNING`

**Constraints**:

* Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

**TOML dotted key path**: `server.logging_level`

**Supported environment variables**:
`PREFECT_SERVER_LOGGING_LEVEL`, `PREFECT_LOGGING_SERVER_LEVEL`

### `analytics_enabled`

When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version)
on server startup to help us improve our product.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.analytics_enabled`

**Supported environment variables**:
`PREFECT_SERVER_ANALYTICS_ENABLED`

### `metrics_enabled`

Whether or not to enable Prometheus metrics in the API.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.metrics_enabled`

**Supported environment variables**:
`PREFECT_SERVER_METRICS_ENABLED`, `PREFECT_API_ENABLE_METRICS`

### `log_retryable_errors`

If `True`, log retryable errors in the API and it's services.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `server.log_retryable_errors`

**Supported environment variables**:
`PREFECT_SERVER_LOG_RETRYABLE_ERRORS`, `PREFECT_API_LOG_RETRYABLE_ERRORS`

### `register_blocks_on_start`

If set, any block types that have been imported will be registered with the backend on application startup. If not set, block types must be manually registered.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.register_blocks_on_start`

**Supported environment variables**:
`PREFECT_SERVER_REGISTER_BLOCKS_ON_START`, `PREFECT_API_BLOCKS_REGISTER_ON_START`

### `memoize_block_auto_registration`

Controls whether or not block auto-registration on start

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.memoize_block_auto_registration`

**Supported environment variables**:
`PREFECT_SERVER_MEMOIZE_BLOCK_AUTO_REGISTRATION`, `PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION`

### `memo_store_path`

Path to the memo store file. Defaults to \$PREFECT\_HOME/memo\_store.toml

**Type**: `string`

**TOML dotted key path**: `server.memo_store_path`

**Supported environment variables**:
`PREFECT_SERVER_MEMO_STORE_PATH`, `PREFECT_MEMO_STORE_PATH`

### `deployment_schedule_max_scheduled_runs`

The maximum number of scheduled runs to create for a deployment.

**Type**: `integer`

**Default**: `50`

**TOML dotted key path**: `server.deployment_schedule_max_scheduled_runs`

**Supported environment variables**:
`PREFECT_SERVER_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS`, `PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS`

### `api`

**Type**: [ServerAPISettings](#serverapisettings)

**TOML dotted key path**: `server.api`

### `concurrency`

Settings for controlling server-side concurrency limit handling

**Type**: [ServerConcurrencySettings](#serverconcurrencysettings)

**TOML dotted key path**: `server.concurrency`

### `database`

**Type**: [ServerDatabaseSettings](#serverdatabasesettings)

**TOML dotted key path**: `server.database`

### `deployments`

Settings for controlling server deployments behavior

**Type**: [ServerDeploymentsSettings](#serverdeploymentssettings)

**TOML dotted key path**: `server.deployments`

### `ephemeral`

**Type**: [ServerEphemeralSettings](#serverephemeralsettings)

**TOML dotted key path**: `server.ephemeral`

### `events`

Settings for controlling server events behavior

**Type**: [ServerEventsSettings](#servereventssettings)

**TOML dotted key path**: `server.events`

### `flow_run_graph`

Settings for controlling flow run graph behavior

**Type**: [ServerFlowRunGraphSettings](#serverflowrungraphsettings)

**TOML dotted key path**: `server.flow_run_graph`

### `logs`

Settings for controlling server logs behavior

**Type**: [ServerLogsSettings](#serverlogssettings)

**TOML dotted key path**: `server.logs`

### `services`

Settings for controlling server services behavior

**Type**: [ServerServicesSettings](#serverservicessettings)

**TOML dotted key path**: `server.services`

### `tasks`

Settings for controlling server tasks behavior

**Type**: [ServerTasksSettings](#servertaskssettings)

**TOML dotted key path**: `server.tasks`

### `ui`

Settings for controlling server UI behavior

**Type**: [ServerUISettings](#serveruisettings)

**TOML dotted key path**: `server.ui`

***

## ServerTasksSchedulingSettings

Settings for controlling server-side behavior related to task scheduling

### `max_scheduled_queue_size`

The maximum number of scheduled tasks to queue for submission.

**Type**: `integer`

**Default**: `1000`

**TOML dotted key path**: `server.tasks.scheduling.max_scheduled_queue_size`

**Supported environment variables**:
`PREFECT_SERVER_TASKS_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE`, `PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE`

### `max_retry_queue_size`

The maximum number of retries to queue for submission.

**Type**: `integer`

**Default**: `100`

**TOML dotted key path**: `server.tasks.scheduling.max_retry_queue_size`

**Supported environment variables**:
`PREFECT_SERVER_TASKS_SCHEDULING_MAX_RETRY_QUEUE_SIZE`, `PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE`

### `pending_task_timeout`

How long before a PENDING task are made available to another task worker.

**Type**: `string`

**Default**: `PT0S`

**TOML dotted key path**: `server.tasks.scheduling.pending_task_timeout`

**Supported environment variables**:
`PREFECT_SERVER_TASKS_SCHEDULING_PENDING_TASK_TIMEOUT`, `PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT`

***

## ServerTasksSettings

Settings for controlling server-side behavior related to tasks

### `tag_concurrency_slot_wait_seconds`

The number of seconds to wait before retrying when a task run cannot secure a concurrency slot from the server.

**Type**: `number`

**Default**: `30`

**Constraints**:

* Minimum: 0

**TOML dotted key path**: `server.tasks.tag_concurrency_slot_wait_seconds`

**Supported environment variables**:
`PREFECT_SERVER_TASKS_TAG_CONCURRENCY_SLOT_WAIT_SECONDS`, `PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS`

### `max_cache_key_length`

The maximum number of characters allowed for a task run cache key.

**Type**: `integer`

**Default**: `2000`

**TOML dotted key path**: `server.tasks.max_cache_key_length`

**Supported environment variables**:
`PREFECT_SERVER_TASKS_MAX_CACHE_KEY_LENGTH`, `PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH`

### `scheduling`

**Type**: [ServerTasksSchedulingSettings](#servertasksschedulingsettings)

**TOML dotted key path**: `server.tasks.scheduling`

***

## ServerUISettings

### `enabled`

Whether or not to serve the Prefect UI.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `server.ui.enabled`

**Supported environment variables**:
`PREFECT_SERVER_UI_ENABLED`, `PREFECT_UI_ENABLED`

### `api_url`

The connection url for communication from the UI to the API. Defaults to `PREFECT_API_URL` if set. Otherwise, the default URL is generated from `PREFECT_SERVER_API_HOST` and `PREFECT_SERVER_API_PORT`.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.ui.api_url`

**Supported environment variables**:
`PREFECT_SERVER_UI_API_URL`, `PREFECT_UI_API_URL`

### `serve_base`

The base URL path to serve the Prefect UI from.

**Type**: `string`

**Default**: `/`

**TOML dotted key path**: `server.ui.serve_base`

**Supported environment variables**:
`PREFECT_SERVER_UI_SERVE_BASE`, `PREFECT_UI_SERVE_BASE`

### `static_directory`

The directory to serve static files from. This should be used when running into permissions issues when attempting to serve the UI from the default directory (for example when running in a Docker container).

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `server.ui.static_directory`

**Supported environment variables**:
`PREFECT_SERVER_UI_STATIC_DIRECTORY`, `PREFECT_UI_STATIC_DIRECTORY`

***

## TasksRunnerSettings

### `thread_pool_max_workers`

The maximum number of workers for ThreadPoolTaskRunner.

**Type**: `integer | None`

**Default**: `None`

**TOML dotted key path**: `tasks.runner.thread_pool_max_workers`

**Supported environment variables**:
`PREFECT_TASKS_RUNNER_THREAD_POOL_MAX_WORKERS`, `PREFECT_TASK_RUNNER_THREAD_POOL_MAX_WORKERS`

### `process_pool_max_workers`

The maximum number of workers for ProcessPoolTaskRunner.

**Type**: `integer | None`

**Default**: `None`

**TOML dotted key path**: `tasks.runner.process_pool_max_workers`

**Supported environment variables**:
`PREFECT_TASKS_RUNNER_PROCESS_POOL_MAX_WORKERS`

***

## TasksSchedulingSettings

### `default_storage_block`

The `block-type/block-document` slug of a block to use as the default storage for autonomous tasks.

**Type**: `string | None`

**Default**: `None`

**TOML dotted key path**: `tasks.scheduling.default_storage_block`

**Supported environment variables**:
`PREFECT_TASKS_SCHEDULING_DEFAULT_STORAGE_BLOCK`, `PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK`

### `delete_failed_submissions`

Whether or not to delete failed task submissions from the database.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `tasks.scheduling.delete_failed_submissions`

**Supported environment variables**:
`PREFECT_TASKS_SCHEDULING_DELETE_FAILED_SUBMISSIONS`, `PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS`

***

## TasksSettings

### `refresh_cache`

If `True`, enables a refresh of cached results: re-executing the task will refresh the cached results.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `tasks.refresh_cache`

**Supported environment variables**:
`PREFECT_TASKS_REFRESH_CACHE`

### `default_no_cache`

If `True`, sets the default cache policy on all tasks to `NO_CACHE`.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `tasks.default_no_cache`

**Supported environment variables**:
`PREFECT_TASKS_DEFAULT_NO_CACHE`

### `disable_caching`

If `True`, disables caching on all tasks regardless of cache policy.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `tasks.disable_caching`

**Supported environment variables**:
`PREFECT_TASKS_DISABLE_CACHING`

### `default_retries`

This value sets the default number of retries for all tasks.

**Type**: `integer`

**Default**: `0`

**Constraints**:

* Minimum: 0

**TOML dotted key path**: `tasks.default_retries`

**Supported environment variables**:
`PREFECT_TASKS_DEFAULT_RETRIES`, `PREFECT_TASK_DEFAULT_RETRIES`

### `default_retry_delay_seconds`

This value sets the default retry delay seconds for all tasks.

**Type**: `string | integer | number | array | None`

**Default**: `0`

**TOML dotted key path**: `tasks.default_retry_delay_seconds`

**Supported environment variables**:
`PREFECT_TASKS_DEFAULT_RETRY_DELAY_SECONDS`, `PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS`

### `default_persist_result`

If `True`, results will be persisted by default for all tasks. Set to `False` to disable persistence by default. Note that setting to `False` will override the behavior set by a parent flow or task.

**Type**: `boolean | None`

**Default**: `None`

**TOML dotted key path**: `tasks.default_persist_result`

**Supported environment variables**:
`PREFECT_TASKS_DEFAULT_PERSIST_RESULT`

### `runner`

Settings for controlling task runner behavior

**Type**: [TasksRunnerSettings](#tasksrunnersettings)

**TOML dotted key path**: `tasks.runner`

### `scheduling`

Settings for controlling client-side task scheduling behavior

**Type**: [TasksSchedulingSettings](#tasksschedulingsettings)

**TOML dotted key path**: `tasks.scheduling`

***

## TestingSettings

### `test_mode`

If `True`, places the API in test mode. This may modify behavior to facilitate testing.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `testing.test_mode`

**Supported environment variables**:
`PREFECT_TESTING_TEST_MODE`, `PREFECT_TEST_MODE`

### `unit_test_mode`

This setting only exists to facilitate unit testing. If `True`, code is executing in a unit test context. Defaults to `False`.

**Type**: `boolean`

**Default**: `False`

**TOML dotted key path**: `testing.unit_test_mode`

**Supported environment variables**:
`PREFECT_TESTING_UNIT_TEST_MODE`, `PREFECT_UNIT_TEST_MODE`

### `unit_test_loop_debug`

If `True` turns on debug mode for the unit testing event loop.

**Type**: `boolean`

**Default**: `True`

**TOML dotted key path**: `testing.unit_test_loop_debug`

**Supported environment variables**:
`PREFECT_TESTING_UNIT_TEST_LOOP_DEBUG`, `PREFECT_UNIT_TEST_LOOP_DEBUG`

### `test_setting`

This setting only exists to facilitate unit testing. If in test mode, this setting will return its value. Otherwise, it returns `None`.

**Type**: `None`

**Default**: `FOO`

**TOML dotted key path**: `testing.test_setting`

**Supported environment variables**:
`PREFECT_TESTING_TEST_SETTING`, `PREFECT_TEST_SETTING`

***

## WorkerSettings

### `heartbeat_seconds`

Number of seconds a worker should wait between sending a heartbeat.

**Type**: `number`

**Default**: `30`

**TOML dotted key path**: `worker.heartbeat_seconds`

**Supported environment variables**:
`PREFECT_WORKER_HEARTBEAT_SECONDS`

### `query_seconds`

Number of seconds a worker should wait between queries for scheduled work.

**Type**: `number`

**Default**: `10`

**TOML dotted key path**: `worker.query_seconds`

**Supported environment variables**:
`PREFECT_WORKER_QUERY_SECONDS`

### `prefetch_seconds`

The number of seconds into the future a worker should query for scheduled work.

**Type**: `number`

**Default**: `10`

**TOML dotted key path**: `worker.prefetch_seconds`

**Supported environment variables**:
`PREFECT_WORKER_PREFETCH_SECONDS`

### `webserver`

Settings for a worker's webserver

**Type**: [WorkerWebserverSettings](#workerwebserversettings)

**TOML dotted key path**: `worker.webserver`

***

## WorkerWebserverSettings

### `host`

The host address the worker's webserver should bind to.

**Type**: `string`

**Default**: `0.0.0.0`

**TOML dotted key path**: `worker.webserver.host`

**Supported environment variables**:
`PREFECT_WORKER_WEBSERVER_HOST`

### `port`

The port the worker's webserver should bind to.

**Type**: `integer`

**Default**: `8080`

**TOML dotted key path**: `worker.webserver.port`

**Supported environment variables**:
`PREFECT_WORKER_WEBSERVER_PORT`

***


# Artifacts
Source: https://docs-3.prefect.io/v3/concepts/artifacts

Artifacts are persisted outputs designed for human consumption and available in the UI.

Prefect artifacts:

* are visually rich annotations on flow and task runs
* are human-readable visual metadata defined in code
* come in standardized formats such as tables, progress indicators, images, Markdown, and links
* are stored in Prefect Cloud or Prefect server and rendered in the Prefect UI
* make it easy to visualize outputs or side effects that your runs produce, and capture updates over time

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=0daffdebede0bcf508172cd503fbe873" alt="Markdown artifact sales report screenshot" data-og-width="1315" width="1315" data-og-height="925" height="925" data-path="v3/img/ui/md-artifact-info.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=7ffc604ae8aa3a9a66668279de4d0f68 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c70b80ab79d497c8695fd36c771eaba1 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=5a6d42ade2b53f07b526ababe155be5a 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=02adac85d69dc70712cfdf301f84e998 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=2323063e708dbc746c4cac3003a7b15d 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=52cf19724759481fca06264354276263 2500w" data-optimize="true" data-opv="2" />

Common use cases for artifacts include:

* **Progress** indicators: Publish progress indicators for long-running tasks. This helps monitor the progress of your tasks and flows and ensure they are running as expected.
* **Debugging**: Publish data that you care about in the UI to easily see when and where your results were written. If an artifact doesn't look the way you expect, you can find out which flow run last updated it, and you can click through a link in the artifact to a storage location (such as an S3 bucket).
* **Data quality checks**: Publish data quality checks from in-progress tasks to ensure that data quality is maintained throughout a pipeline. Artifacts make for great performance graphs. For example, you can visualize a long-running machine learning model training run. You can also track artifact versions, making it easier to identify changes in your data.
* **Documentation**: Publish documentation and sample data to help you keep track of your work and share information.
  For example, add a description to signify why a piece of data is important.

## Artifact types

There are five artifact types:

* links
* Markdown
* progress
* images
* tables

<Note>
  Each artifact created within a task is displayed individually in the Prefect UI.
  This means that each call to `create_link_artifact()` or `create_markdown_artifact()` generates a distinct artifact.

  Unlike the Python `print()` function (where you can concatenate multiple calls to include additional items in a report),
  these artifact creation functions must be called multiple times, if necessary.

  To create artifacts such as reports or summaries using `create_markdown_artifact()`, define your message string
  and then pass it to `create_markdown_artifact()` to create the artifact.
</Note>

For more information on how to create and use artifacts, see the [how to produce workflow artifacts](/v3/how-to-guides/workflows/artifacts/) guide.


# Assets
Source: https://docs-3.prefect.io/v3/concepts/assets

Assets represent objects your workflows produce.

<span class="badge cloud" />

Assets in Prefect represent any outcome or output of your Prefect workflows. They provide an interface to model all forms of data and model lineage, track dependencies between data transformations, and monitor the health of pipelines at the asset level rather than just the compute level.

## Core concepts

An asset is fundamentally defined by its **key**, a URI that uniquely identifies an asset, often specifying an external storage system in which that asset lives.
Asset keys serve as both identifiers and organizational structures—assets are automatically grouped by their URI scheme (e.g., `s3://`, `postgres://`, `snowflake://`) and can be hierarchically organized based on their path structure.

Assets exist in three primary states within Prefect:

* **Materialized**: The asset has been created, updated, or overwritten by a Prefect workflow
* **Referenced**: The asset is consumed as input by a workflow but not produced by it
* **External**: The asset exists outside the Prefect ecosystem but is referenced as a dependency

## Asset lifecycle

### Materializations

A **materialization** occurs when a workflow mutates an asset through creation, updating, or overwriting. Materializations are declared using the `@materialize` decorator, which functions as a specialized task decorator that tracks asset creation intent.

The materialization process operates on an "intent to materialize" model: when a function decorated with `@materialize` executes, Prefect records the materialization attempt. Success or failure of the materialization is determined by the underlying task's execution state.

```python
from prefect.assets import materialize

@materialize("s3://data-lake/processed/customer-data.csv")
def process_customer_data():
    # Asset materialization logic
    pass
```

### References

A **reference** occurs when an asset appears as an upstream dependency in another asset's materialization. References are automatically inferred from the task execution graph—when the output of one materialization flows as input to another, the dependency relationship is captured.

References can also be explicitly declared through the `asset_deps` parameter, which is particularly useful for modeling dependencies on external systems or when the task graph alone doesn't fully capture the data dependencies.

### Metadata

Asset definitions include optional metadata about that asset. These asset properties should have one source of truth to avoid conflicts. When you materialize an asset with properties, those properties perform a complete overwrite of all metadata fields for that asset.

Updates to asset metadata occur at runtime from any workflow that specifies metadata fields.

## Dependency modeling

Asset dependencies are determined through two complementary mechanisms:

**Task graph inference**: When materialized assets flow through task parameters, Prefect automatically constructs the dependency graph. Each materialization acts as a dependency accumulation point, gathering all upstream assets and serving as the foundation for downstream materializations.

**Explicit declaration**: The `asset_deps` parameter allows direct specification of asset dependencies, enabling modeling of relationships that aren't captured in the task execution flow.

```python
from prefect.assets import materialize


@materialize(
    "s3://warehouse/enriched-data.csv",
    asset_deps=["postgres://db/reference-tables", "s3://external/vendor-data.csv"]
)
def enrich_data():
    # Explicitly depends on external database and vendor data
    pass
```

The backend will track these dependencies *across workflow boundaries*, exposing a global view of asset dependencies within your workspace.

## Asset metadata and properties

Assets support rich metadata through the `AssetProperties` class, which provides organizational context and improves discoverability:

* **Name**: Human-readable identifier for the asset
* **Description**: Detailed documentation supporting Markdown formatting
* **Owners**: Responsible parties, with special UI treatment for Prefect users and teams
* **URL**: Web location for accessing or viewing the asset

Additionally, assets support dynamic metadata through the `add_asset_metadata()` function, allowing runtime information like row counts, processing times, and data quality metrics to be attached to materialization events.

## Asset health monitoring

Currently asset health provides a *visual* indicator of the operational status of data artifacts based on their most recent materialization attempt:

* **Green**: Last materialization succeeded
* **Red**: Last materialization failed
* **Gray**: No materialization recorded, or asset has only been referenced

This health model enables data teams to quickly identify problematic data pipelines at the artifact level, complementing traditional task-level monitoring with data-centric observability. Soon these statuses will be backed by a corresponding event.

## Event emission and integration

Assets integrate deeply with Prefect's event system, automatically emitting structured events that enable downstream automation and monitoring:

### Event types

* **Materialization events**: These events look like `prefect.asset.materialization.{succeeded|failed}` and are emitted when assets are referenced by the `@materialize` decorator, with status determined by the underlying task execution state.
* **Reference events**: These events look like `prefect.asset.referenced` and are emitted for all upstream assets when a materialization occurs, independent of success or failure.

### Event emission rules

Asset events follow specific emission patterns based on task execution state:

* **Completed states**: Emit `prefect.asset.materialization.succeeded` for downstream assets and `prefect.asset.referenced` for upstream assets
* **Failed states**: Emit `prefect.asset.materialization.failed` for downstream assets and `prefect.asset.referenced` for upstream assets
* **Cached states**: No asset events are emitted, as cached executions don't represent new asset state changes

Reference events are always emitted for upstream assets regardless of materialization success, enabling comprehensive dependency tracking even when downstream processes fail.

### Event payloads

Materialization events include any metadata added during task execution through `add_asset_metadata()`, while reference events contain basic asset identification information. This enables rich event-driven automation based on both asset state changes and associated metadata.

## Asset organization and discovery

Assets are automatically organized in the Prefect UI based on their URI structure:

* **Grouping by scheme**: Assets with the same URI scheme (e.g., `s3://`, `postgres://`) are grouped together
* **Hierarchical organization**: URI paths create nested organization structures
* **Search and filtering**: Asset metadata enables discovery through names, descriptions, and ownership information

## Further Reading

* [How to use assets to track workflow outputs](/v3/how-to-guides/workflows/assets)
* [How to customize asset metadata](/v3/advanced/assets)


# Automations
Source: https://docs-3.prefect.io/v3/concepts/automations

Learn how to automatically take action in response to events.

Automations enable you to configure [actions](#actions) that execute automatically based on [trigger](#triggers) conditions.

Potential triggers include the occurrence of events from changes in a flow run's state—or the absence of such events.
You can define your own custom trigger to fire based on a custom [event](/v3/concepts/event-triggers/) defined in Python code.

With Prefect Cloud you can even create [webhooks](/v3/automate/events/webhook-triggers/) that can receive data for use in actions.

Actions you can take upon a trigger include:

* creating flow runs from existing deployments
* pausing and resuming schedules or work pools
* sending custom notifications

### Triggers

Triggers specify the conditions under which your action should be performed. The Prefect UI includes templates for many
common conditions, such as:

* Flow run state change (Flow Run Tags are only evaluated with `OR` criteria)
* Work pool status
* Work queue status
* Deployment status
* Metric thresholds, such as average duration, lateness, or completion percentage
* Custom event triggers

Importantly, you can configure the triggers not only in reaction to events, but also proactively: in the absence of
an expected event.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-trigger.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=266fbeea3114360696a4adbc82eeac85" alt="Configuring a trigger for an automation in Prefect Cloud." data-og-width="1666" width="1666" data-og-height="940" height="940" data-path="v3/img/ui/automations-trigger.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-trigger.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c2519e723f59057d06c1435a79fb3f71 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-trigger.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=2fa993bb8bed63d95a92e3d5fb255f43 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-trigger.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=8841b66b7ea213ed5314ce7c4d5c1302 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-trigger.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=e3de933081548cb30cd12433bf75464f 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-trigger.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c497962e2a4e6b9dda2ecfc260cb382e 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-trigger.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=febf611557113851b886d74fa0e62ea5 2500w" data-optimize="true" data-opv="2" />

For example, in the case of flow run state change triggers, you might expect production flows to finish in no longer
than thirty minutes. But transient infrastructure or network issues could cause your flow to get “stuck” in a running state.
A trigger could kick off an action if the flow stays in a running state for more than 30 minutes.

This action could be taken on the flow itself, such as cancelling or restarting it. Or the action could take the form of a
notification for someone to take manual remediation steps. Or you could set both actions to take place when the trigger occurs.

### Actions

Actions specify what your automation does when its trigger criteria are met. Current action types include:

* Cancel a flow run
* Pause or resume a schedule
* Run a deployment
* Pause or resume a deployment schedule
* Pause or resume a work pool
* Pause or resume a work queue
* Pause or resume an automation
* Send a [notification](#sending-notifications-with-automations)
* Call a webhook
* Suspend a flow run
* Change the state of a flow run

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=16439f3f9b1614ab84454c79ccfda359" alt="Configuring an action for an automation in Prefect Cloud." data-og-width="2471" width="2471" data-og-height="1187" height="1187" data-path="v3/img/ui/automations-action.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=51045405c04e0ba544a415cbee5eda94 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=530c98618e692d16e8056e15f887931e 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=5c6902a7b482a803d869b788768b32ab 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=e9d2121922b0950a257f24381a1d6d78 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=91ad6e75ced9bcf1385bbde73d247def 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=66be6db8ec03fec57b38ce6844d1c947 2500w" data-optimize="true" data-opv="2" />

### Selected and inferred action targets

Some actions require you to either select the target of the action, or specify that the target of the action should be
inferred. Selected targets are simple and useful for when you know exactly what object your action should act on. For
example, the case of a cleanup flow you want to run or a specific notification you want to send.

Inferred targets are deduced from the trigger itself.

For example, if a trigger fires on a flow run that is stuck in a running state, and the action is to cancel an inferred
flow run—the flow run that caused the trigger to fire.

Similarly, if a trigger fires on a work queue event and the corresponding action is to pause an inferred work queue, the
inferred work queue is the one that emitted the event.

Prefect infers the relevant event whenever possible, but sometimes one does not exist.

Specify a name and, optionally, a description for the automation.

## Sending notifications with automations

Automations support sending notifications through any predefined block that is capable of and configured
to send a message, including:

* Slack message to a channel
* Microsoft Teams message to a channel
* Email to an email address

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-notifications.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=43a44548667b7a594fff369d8040f54a" alt="Configuring notifications for an automation in Prefect Cloud." data-og-width="2476" width="2476" data-og-height="1337" height="1337" data-path="v3/img/ui/automations-notifications.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-notifications.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=869c66eb06cb0e1eaaaa46776ce07e3f 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-notifications.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=daa37777a7d2d5c106f04646948f11c1 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-notifications.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=4209224885ed178823e926601d15156e 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-notifications.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=9ef49c2864e36c1edae2f2d84972fc53 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-notifications.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=fbaf721f8c4de1887486bf8975524521 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-notifications.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=44104bfd1b6f0fb707f35e7f307d56dd 2500w" data-optimize="true" data-opv="2" />

## Templating with Jinja

You can access templated variables with automation actions through [Jinja](https://palletsprojects.com/p/jinja/) syntax.
Templated variables enable you to dynamically include details from an automation trigger, such as a flow or pool name.

Jinja templated variable syntax wraps the variable name in double curly brackets, like this: `{{ variable }}`.

You can access properties of the underlying flow run objects including:

* [flow\_run](https://reference.prefect.io/prefect/server/schemas/core/#prefect.server.schemas.core.FlowRun)
* [flow](https://reference.prefect.io/prefect/server/schemas/core/#prefect.server.schemas.core.Flow)
* [deployment](https://reference.prefect.io/prefect/server/schemas/core/#prefect.server.schemas.core.Deployment)
* [work\_queue](https://reference.prefect.io/prefect/server/schemas/core/#prefect.server.schemas.core.WorkQueue)
* [work\_pool](https://reference.prefect.io/prefect/server/schemas/core/#prefect.server.schemas.core.WorkPool)

In addition to its native properties, each object includes an `id` along with `created` and `updated` timestamps.

The `flow_run|ui_url` token returns the URL to view the flow run in the UI.

Here's an example relevant to a flow run state-based notification:

```
Flow run {{ flow_run.name }} entered state {{ flow_run.state.name }}.

    Timestamp: {{ flow_run.state.timestamp }}
    Flow ID: {{ flow_run.flow_id }}
    Flow Run ID: {{ flow_run.id }}
    State message: {{ flow_run.state.message }}
```

The resulting Slack webhook notification looks something like this:

<img src="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/templated-notification.png?fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=d2072752b2ef7111879fd64ffd46c841" alt="Configuring notifications for an automation in Prefect Cloud." data-og-width="723" width="723" data-og-height="211" height="211" data-path="v3/img/ui/templated-notification.png" srcset="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/templated-notification.png?w=280&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=a422ce5bc65b952437ea454101061447 280w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/templated-notification.png?w=560&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=dcc5e01c2f57795ee9f9c94944bb1d31 560w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/templated-notification.png?w=840&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=8dcc506be325b204d8cf9ca18b92abf5 840w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/templated-notification.png?w=1100&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=2fb47409956cca8270df3555aa7bfe2c 1100w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/templated-notification.png?w=1650&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=baba7f5c1fe883f747a21d44fa540d4f 1650w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/templated-notification.png?w=2500&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=2571b9e878befb8c157ac32fa6a9598d 2500w" data-optimize="true" data-opv="2" />

You could include `flow` and `deployment` properties:

```
Flow run {{ flow_run.name }} for flow {{ flow.name }}
entered state {{ flow_run.state.name }}
with message {{ flow_run.state.message }}

Flow tags: {{ flow_run.tags }}
Deployment name: {{ deployment.name }}
Deployment version: {{ deployment.version }}
Deployment parameters: {{ deployment.parameters }}
```

An automation that reports on work pool status might include notifications using `work_pool` properties:

```
Work pool status alert!

Name: {{ work_pool.name }}
Last polled: {{ work_pool.last_polled }}
```

In addition to those shortcuts for flows, deployments, and work pools, you have access to the automation and the
event that triggered the automation. See the [Automations API](https://app.prefect.cloud/api/docs#tag/Automations)
for additional details.

```
Automation: {{ automation.name }}
Description: {{ automation.description }}

Event: {{ event.id }}
Resource:
{% for label, value in event.resource %}
{{ label }}: {{ value }}
{% endfor %}
Related Resources:
{% for related in event.related %}
    Role: {{ related.role }}
    {% for label, value in related %}
    {{ label }}: {{ value }}
    {% endfor %}
{% endfor %}
```

Note that this example also illustrates the ability to use Jinja features such as iterator and for loop
[control structures](https://jinja.palletsprojects.com/en/3.1.x/templates/#list-of-control-structures) when
templating notifications.

For more on the common use case of passing an upstream flow run's parameters to the flow run invoked by the automation, see the [Passing parameters to a flow run](/v3/how-to-guides/automations/access-parameters-in-templates/) guide.

## Further reading

* To learn more about Prefect events, which can trigger automations, see the [events docs](/v3/concepts/events/).
* See the [webhooks guide](/v3/how-to-guides/cloud/create-a-webhook/)
  to learn how to create webhooks and receive external events.


# Blocks
Source: https://docs-3.prefect.io/v3/concepts/blocks

Prefect blocks allow you to manage configuration schemas, infrastructure, and secrets for use with deployments or flow scripts.

export const blocks = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/block",
  api: "https://app.prefect.cloud/api/docs#tag/Blocks",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/block"
};

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

export const CLI = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect CLI</a>.</p>;

Prefect blocks store typed configuration that can be used across workflows and deployments.
The most common use case for blocks is storing credentials used to access external systems such as AWS or GCP.
Prefect supports [a large number of common blocks](#pre-registered-blocks) and provides a Python SDK for creating your own.

<Tip>
  **Blocks and parameters**

  Blocks are useful for sharing configuration across flow runs and between flows.

  For configuration that will change between flow runs, we recommend using [parameters](/v3/develop/write-flows/#parameters).
</Tip>

## How blocks work

There are three layers to a block: its *type*, a *document*, and a Python *class*.

### Block type

A block *type* is essentially a schema registered with the Prefect API. This schema can be inspected and discovered in the UI on the **Blocks** page.

To see block types available for configuration, use `prefect block type ls`
from the CLI or navigate to the **Blocks** page in the UI and click **+**.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/block-library.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=42e22060633cf3dd2dd8a0f37d0317ef" alt="The block catalogue in the UI" data-og-width="2528" width="2528" data-og-height="1544" height="1544" data-path="v3/img/ui/block-library.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/block-library.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=0b0b1738210d33e8b24e8150ab28cc81 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/block-library.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=4f2dca354e90203c5f043accb7281e0c 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/block-library.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=65577240db473e0b36127f4979076b3b 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/block-library.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=01fea4ef2f8bc896b7102b169c86d1c1 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/block-library.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=dc26d4e7e1667a3eebaa5c4fa16bee57 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/block-library.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=cf456a8a843c67fae1632379bb4be265 2500w" data-optimize="true" data-opv="2" />

These types separate blocks from [Prefect variables](/v3/develop/variables/), which are unstructured JSON documents.
In addition, block schemas allow for fields of `SecretStr` type which are stored with additional encryption and not displayed by default in the UI.

Block types are identified by a *slug* that is not configurable.

{/* pmd-metadata: notest */}

```python
from prefect.blocks.core import Block


class Cube(Block):
    edge_length_inches: float


# register the block type under the slug 'cube'
Cube.register_type_and_schema()
```

<Note>
  Users should rarely need to register types in this way - saving a block document will also automatically register its type.
</Note>

### Block document

A block *document* is an instantiation of the schema, or block type. A document contains *specific* values for each field defined in the schema.

All block types allow for the creation of as many documents as you wish. Building on our example above:

{/* pmd-metadata: notest */}

```python
from prefect.blocks.core import Block


class Cube(Block):
    edge_length_inches: float


# instantiate the type with specific values
rubiks_cube = Cube(edge_length_inches=2.25)

# store those values in a block document 
# on the server for future use
rubiks_cube.save("rubiks-cube")


# instantiate and save another block document
tiny_cube = Cube(edge_length_inches=0.001)
tiny_cube.save("tiny")
```

Block documents can also be created and updated in the UI or API for easy change management.
This allows you to work with slowly changing configuration without having to redeploy all workflows that rely on it; for example, you may use this to rotate credentials on a regular basis without touching your deployments.

### Block class

A block *class* is the primary user-facing object; it is a Python class whose attributes are loaded from a block document. Most Prefect blocks encapsulate additional functionality built on top of the block document.

For example, an `S3Bucket` block contains methods for downloading data from, or upload data to, an S3 bucket; a `SnowflakeConnector` block contains methods for querying Snowflake databases.

Returning to our `Cube` example from above:

{/* pmd-metadata: notest */}

```python
from prefect.blocks.core import Block

class Cube(Block):
    edge_length_inches: float

    def get_volume(self):
        return self.edge_length_inches ** 3

    def get_surface_area(self):
        return 6 * self.edge_length_inches ** 2


rubiks_cube = Cube.load("rubiks-cube")
rubiks_cube.get_volume() # 11.390625
```

<Warning>
  The class itself is *not* stored server-side when registering block types and block documents.
  For this reason, we highly recommend loading block documents by first importing the block class and then calling its `load` method with the relevant document name.
</Warning>

## Pre-registered blocks

### Built-in blocks

Commonly used block types come built-in with Prefect.
You can create and use these block types through the UI without installing any additional packages.

| Block                   | Slug                 | Description                                                                                      |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
| Custom Webhook          | `custom-webhook`     | Call custom webhooks.                                                                            |
| Discord Webhook         | `discord-webhook`    | Call Discord webhooks.                                                                           |
| Local File System       | `local-file-system`  | Store data as a file on a local file system.                                                     |
| Mattermost Webhook      | `mattermost-webhook` | Send notifications through a provided Mattermost webhook.                                        |
| Microsoft Teams Webhook | `ms-teams-webhook`   | Send notifications through a provided Microsoft Teams webhook.                                   |
| Opsgenie Webhook        | `opsgenie-webhook`   | Send notifications through a provided Opsgenie webhook.                                          |
| Pager Duty Webhook      | `pager-duty-webhook` | Send notifications through a provided PagerDuty webhook.                                         |
| Remote File System      | `remote-file-system` | Access files on a remote file system.                                                            |
| Secret                  | `secret`             | Store a secret value. The value will be obfuscated when this block is logged or shown in the UI. |
| Sendgrid Email          | `sendgrid-email`     | Send notifications through Sendgrid email.                                                       |
| Slack Webhook           | `slack-webhook`      | Send notifications through a provided Slack webhook.                                             |
| SMB                     | `smb`                | Store data as a file on a SMB share.                                                             |
| Twilio SMS              | `twilio-sms`         | Send notifications through Twilio SMS.                                                           |

<Note>
  Built-in blocks should be registered the first time you start a Prefect server. If the auto-registration fails, you can manually register the blocks using `prefect blocks register`.

  For example, to register all built-in notification blocks, run `prefect block register -m prefect.blocks.notifications`.
</Note>

### Blocks in Prefect integration libraries

Some block types that appear in the UI can be created immediately, with the corresponding integration library installed for use.
For example, an AWS Secret block can be created, but not used until the [`prefect-aws` library](/integrations/prefect-aws/) is installed.

Find available block types in many of the published [Prefect integrations libraries](/integrations/).
If a block type is not available in the UI, you can [register it](#register-blocks) through the CLI.

| Block                                | Slug                                   | Integration                                             |
| ------------------------------------ | -------------------------------------- | ------------------------------------------------------- |
| ECS Task                             | `ecs-task`                             | [prefect-aws](/integrations/prefect-aws/)               |
| MinIO Credentials                    | `minio-credentials`                    | [prefect-aws](/integrations/prefect-aws/)               |
| S3 Bucket                            | `s3-bucket`                            | [prefect-aws](/integrations/prefect-aws/)               |
| Azure Blob Storage Credentials       | `azure-blob-storage-credentials`       | [prefect-azure](/integrations/prefect-azure/)           |
| Azure Container Instance Credentials | `azure-container-instance-credentials` | [prefect-azure](/integrations/prefect-azure/)           |
| Azure Container Instance Job         | `azure-container-instance-job`         | [prefect-azure](/integrations/prefect-azure/)           |
| Azure Cosmos DB Credentials          | `azure-cosmos-db-credentials`          | [prefect-azure](/integrations/prefect-azure/)           |
| AzureML Credentials                  | `azureml-credentials`                  | [prefect-azure](/integrations/prefect-azure/)           |
| BitBucket Credentials                | `bitbucket-credentials`                | [prefect-bitbucket](/integrations/prefect-bitbucket/)   |
| BitBucket Repository                 | `bitbucket-repository`                 | [prefect-bitbucket](/integrations/prefect-bitbucket/)   |
| Databricks Credentials               | `databricks-credentials`               | [prefect-databricks](/integrations/prefect-databricks/) |
| dbt CLI BigQuery Target Configs      | `dbt-cli-bigquery-target-configs`      | [prefect-dbt](/integrations/prefect-dbt/)               |
| dbt CLI Profile                      | `dbt-cli-profile`                      | [prefect-dbt](/integrations/prefect-dbt/)               |
| dbt Cloud Credentials                | `dbt-cloud-credentials`                | [prefect-dbt](/integrations/prefect-dbt/)               |
| dbt CLI Global Configs               | `dbt-cli-global-configs`               | [prefect-dbt](/integrations/prefect-dbt/)               |
| dbt CLI Postgres Target Configs      | `dbt-cli-postgres-target-configs`      | [prefect-dbt](/integrations/prefect-dbt/)               |
| dbt CLI Snowflake Target Configs     | `dbt-cli-snowflake-target-configs`     | [prefect-dbt](/integrations/prefect-dbt/)               |
| dbt CLI Target Configs               | `dbt-cli-target-configs`               | [prefect-dbt](/integrations/prefect-dbt/)               |
| Docker Container                     | `docker-container`                     | [prefect-docker](/integrations/prefect-docker/)         |
| Docker Host                          | `docker-host`                          | [prefect-docker](/integrations/prefect-docker/)         |
| Docker Registry Credentials          | `docker-registry-credentials`          | [prefect-docker](/integrations/prefect-docker/)         |
| Email Server Credentials             | `email-server-credentials`             | [prefect-email](/integrations/prefect-email/)           |
| BigQuery Warehouse                   | `bigquery-warehouse`                   | [prefect-gcp](/integrations/prefect-gcp/)               |
| GCP Cloud Run Job                    | `cloud-run-job`                        | [prefect-gcp](/integrations/prefect-gcp/)               |
| GCP Credentials                      | `gcp-credentials`                      | [prefect-gcp](/integrations/prefect-gcp/)               |
| GcpSecret                            | `gcpsecret`                            | [prefect-gcp](/integrations/prefect-gcp/)               |
| GCS Bucket                           | `gcs-bucket`                           | [prefect-gcp](/integrations/prefect-gcp/)               |
| Vertex AI Custom Training Job        | `vertex-ai-custom-training-job`        | [prefect-gcp](/integrations/prefect-gcp/)               |
| GitHub Credentials                   | `github-credentials`                   | [prefect-github](/integrations/prefect-github/)         |
| GitHub Repository                    | `github-repository`                    | [prefect-github](/integrations/prefect-github/)         |
| GitLab Credentials                   | `gitlab-credentials`                   | [prefect-gitlab](/integrations/prefect-gitlab/)         |
| GitLab Repository                    | `gitlab-repository`                    | [prefect-gitlab](/integrations/prefect-gitlab/)         |
| Kubernetes Cluster Config            | `kubernetes-cluster-config`            | [prefect-kubernetes](/integrations/prefect-kubernetes/) |
| Kubernetes Credentials               | `kubernetes-credentials`               | [prefect-kubernetes](/integrations/prefect-kubernetes/) |
| Kubernetes Job                       | `kubernetes-job`                       | [prefect-kubernetes](/integrations/prefect-kubernetes/) |
| Shell Operation                      | `shell-operation`                      | [prefect-shell](/integrations/prefect-shell/)           |
| Slack Credentials                    | `slack-credentials`                    | [prefect-slack](/integrations/prefect-slack/)           |
| Slack Incoming Webhook               | `slack-incoming-webhook`               | [prefect-slack](/integrations/prefect-slack/)           |
| Snowflake Connector                  | `snowflake-connector`                  | [prefect-snowflake](/integrations/prefect-snowflake/)   |
| Snowflake Credentials                | `snowflake-credentials`                | [prefect-snowflake](/integrations/prefect-snowflake/)   |
| Database Credentials                 | `database-credentials`                 | [prefect-sqlalchemy](/integrations/prefect-sqlalchemy/) |
| SQLAlchemy Connector                 | `sqlalchemy-connector`                 | [prefect-sqlalchemy](/integrations/prefect-sqlalchemy/) |

Anyone can create a custom block type and, optionally, share it with the community.

## Additional resources

<CLI name="blocks" href={blocks.cli} />

<TF name="blocks" href={blocks.tf} />


# Caching
Source: https://docs-3.prefect.io/v3/concepts/caching



Caching refers to the ability of a task run to enter a `Completed` state and return a predetermined
value without actually running the code that defines the task.
Caching allows you to efficiently reuse [results of tasks](/v3/develop/results/) that may be expensive to compute
and ensure that your pipelines are idempotent when retrying them due to unexpected failure.

By default Prefect's caching logic is based on the following attributes of a task invocation:

* the inputs provided to the task
* the code definition of the task
* the prevailing flow run ID, or if executed autonomously, the prevailing task run ID

These values are hashed to compute the task's *cache key*.
This implies that, by default, calling the same task with the same inputs more than once within a flow
will result in cached behavior for all calls after the first.
This behavior can be configured - see [customizing the cache](/v3/develop/write-tasks#customizing-the-cache) below.

<Warning>
  **Caching requires result persistence**

  Caching requires result persistence, which is off by default.
  To turn on result persistence for all of your tasks use the `PREFECT_RESULTS_PERSIST_BY_DEFAULT` setting:

  ```
  prefect config set PREFECT_RESULTS_PERSIST_BY_DEFAULT=true
  ```

  See [managing results](/v3/develop/results/) for more details on managing your result configuration, and
  [settings](/v3/develop/settings-and-profiles) for more details on managing Prefect settings.
</Warning>

## Cache keys

To determine whether a task run should retrieve a cached state, Prefect uses the concept of a "cache key".
A cache key is a computed string value that determines where the task's return value will be persisted within
its configured result storage.
When a task run begins, Prefect first computes its cache key and uses this key to lookup a record in the task's result
storage.
If an unexpired record is found, this result is returned and the task does not run, but instead, enters a
`Cached` state with the corresponding result value.

Cache keys can be shared by the same task across different flows, and even among different tasks,
so long as they all share a common result storage location.

By default Prefect stores results locally in `~/.prefect/storage/`.
The filenames in this directory will correspond exactly to computed cache keys from your task runs.

<Warning>
  **Relationship with result persistence**

  Task caching and result persistence are intimately related. Because task caching relies on loading a
  known result, task caching will only work when your task can persist its output
  to a fixed and known location.

  Therefore any configuration which explicitly avoids result persistence will result in your task never
  using a cache, for example setting `persist_result=False`.
</Warning>

## Cache policies

Cache key computation can be configured through the use of *cache policies*.
A cache policy is a recipe for computing cache keys for a given task.

Prefect comes prepackaged with a few common cache policies:

* `DEFAULT`: this cache policy uses the task's inputs, its code definition, as well as the prevailing flow run ID
  to compute the task's cache key.
* `INPUTS`: this cache policy uses *only* the task's inputs to compute the cache key.
* `TASK_SOURCE`: this cache policy only considers raw lines of code in the task (and not the source code of nested tasks) to compute the cache key.
* `FLOW_PARAMETERS`: this cache policy uses *only* the parameter values provided to the parent flow run
  to compute the cache key.
* `NO_CACHE`: this cache policy always returns `None` and therefore avoids caching and result persistence altogether.

These policies can be set using the `cache_policy` keyword on the [task decorator](https://reference.prefect.io/prefect/tasks/#prefect.tasks.task).

## Customizing the cache

Prefect allows you to configure task caching behavior in numerous ways.

### Cache expiration

All cache keys can optionally be given an *expiration* through the `cache_expiration` keyword on
the [task decorator](https://reference.prefect.io/prefect/tasks/#prefect.tasks.task).
This keyword accepts a `datetime.timedelta` specifying a duration for which the cached value should be
considered valid.

Providing an expiration value results in Prefect persisting an expiration timestamp alongside the result
record for the task.
This expiration is then applied to *all* other tasks that may share this cache key.

### Cache policies

Cache policies can be composed and altered using basic Python syntax to form more complex policies.
For example, all task policies except for `NO_CACHE` can be *added* together to form new policies that combine
the individual policies' logic into a larger cache key computation.
Combining policies in this way results in caches that are *easier* to invalidate.

For example:

```python
from prefect import task
from prefect.cache_policies import TASK_SOURCE, INPUTS
@task(cache_policy=TASK_SOURCE + INPUTS)
def my_cached_task(x: int):
    return x + 42
```

This task will rerun anytime you provide new values for `x`, *or* anytime you change the underlying code.

The `INPUTS` policy is a special policy that allows you to *subtract* string values to ignore
certain task inputs:

```python
from prefect import task
from prefect.cache_policies import INPUTS


my_custom_policy = INPUTS - 'debug'

@task(cache_policy=my_custom_policy)
def my_cached_task(x: int, debug: bool = False):
    print('running...')
    return x + 42


my_cached_task(1)
my_cached_task(1, debug=True) # still uses the cache
```

### Cache key functions

You can configure custom cache policy logic through the use of cache key functions.
A cache key function is a function that accepts two positional arguments:

* The first argument corresponds to the `TaskRunContext`, which stores task run metadata. For example,
  this object has attributes `task_run_id`, `flow_run_id`, and `task`, all of which can be used in your
  custom logic.
* The second argument corresponds to a dictionary of input values to the task. For example,
  if your task has the signature `fn(x, y, z)` then the dictionary will have keys "x", "y", and "z" with corresponding values that can be used to compute your cache key.

This function can then be specified using the `cache_key_fn` argument on
the [task decorator](https://reference.prefect.io/prefect/tasks/#prefect.tasks.task).

For example:

```python
from prefect import task


def static_cache_key(context, parameters):
    # return a constant
    return "static cache key"


@task(cache_key_fn=static_cache_key)
def my_cached_task(x: int):
    return x + 1
```

### Cache storage

By default, cache records are collocated with task results and files containing task results will include metadata used for caching.
Configuring a cache policy with a `key_storage` argument allows cache records to be stored separately from task results.

When cache key storage is configured, persisted task results will only include the return value of your task and cache records can be deleted or modified
without effecting your task results.

You can configure where cache records are stored by using the `.configure` method with a `key_storage` argument on a cache policy.
The `key_storage` argument accepts either a path to a local directory or a storage block.

### Cache isolation

Cache isolation controls how concurrent task runs interact with cache records. Prefect supports two isolation levels: `READ_COMMITTED` and `SERIALIZABLE`.

By default, cache records operate with a `READ_COMMITTED` isolation level. This guarantees that reading a cache record will see the latest committed cache value,
but allows multiple executions of the same task to occur simultaneously.

For stricter isolation, you can use the `SERIALIZABLE` isolation level. This ensures that only one execution of a task occurs at a time for a given cache
record via a locking mechanism.

To configure the isolation level, use the `.configure` method with an `isolation_level` argument on a cache policy. When using `SERIALIZABLE`, you must
also provide a `lock_manager` that implements locking logic for your system.

#### Recommended Lock Managers by Execution Context

We recommend using a locking implementation that matches how you are running your work concurrently.

| Execution Context  | Recommended Lock Manager | Notes                                                        |
| ------------------ | ------------------------ | ------------------------------------------------------------ |
| Threads/Coroutines | `MemoryLockManager`      | In-memory locking suitable for single-process execution      |
| Processes          | `FileSystemLockManager`  | File-based locking for multiple processes on same machine    |
| Multiple Machines  | `RedisLockManager`       | Distributed locking via Redis for cross-machine coordination |

## Multi-task caching

There are some situations in which multiple tasks need to always run together or not at all.
This can be achieved in Prefect by configuring these tasks to always write to their caches within
a single [*transaction*](/v3/develop/transactions).


# Deployments
Source: https://docs-3.prefect.io/v3/concepts/deployments

Learn how to use deployments to trigger flow runs remotely.

Deployments allow you to run flows on a [schedule](/v3/concepts/schedules) and trigger runs based on [events](/v3/how-to-guides/automations/creating-deployment-triggers/).

Deployments are server-side representations of flows.
They store the crucial metadata for remote orchestration including when, where, and how a workflow should run.

In addition to manually triggering and managing flow runs, deploying a flow exposes an API and UI that allow you to:

* trigger new runs, [cancel active runs](/v3/how-to-guides/workflows/write-and-run#cancel-a-flow-run), pause scheduled runs, [customize parameters](/v3/concepts/flows#specify-flow-parameters), and more
* remotely configure [schedules](/v3/concepts/schedules) and [automation rules](/v3/how-to-guides/automations/creating-deployment-triggers)
* dynamically provision infrastructure with [work pools](/v3/deploy/infrastructure-concepts/work-pools) - optionally with templated guardrails for other users

In Prefect Cloud, deployment configuration is versioned, and a new [deployment version](/v3/how-to-guides/deployments/versioning) is created each time a deployment is updated.

### Work pools

[Work pools](/v3/concepts/work-pools) allow you to switch between different types of infrastructure and to create a template for deployments.
Data platform teams find work pools especially useful for managing infrastructure configuration across teams of data professionals.

Common work pool types include [Docker](/v3/how-to-guides/deployment_infra/docker), [Kubernetes](/v3/how-to-guides/deployment_infra/kubernetes), and serverless options such as [AWS ECS](/integrations/prefect-aws/ecs_guide#ecs-worker-guide), [Azure ACI](/integrations/prefect-azure/aci_worker), [GCP Vertex AI](/integrations/prefect-gcp/index#run-flows-on-google-cloud-run-or-vertex-ai), or [GCP Google Cloud Run](/integrations/prefect-gcp/gcp-worker-guide).

### Work pool-based deployment requirements

Deployments created through the Python SDK that use a work pool require a `name`.
This value becomes the deployment name.
A `work_pool_name` is also required.

Your flow code location can be specified in a few ways:

1. Bake it into your Docker image (for work-pools that use Docker images).
   As shown in the example above,Prefect facilitates this as the default method for deployments created with the Python SDK.
   This method requires that you specify the `image` argument in the `deploy` method.
2. Call `from_source` on a flow and specify one of the following:
   1. the git-based cloud provider location (for example, GitHub)
   2. the cloud provider storage location (for example, AWS S3)
   3. the local path (an option for Process work pools)

See the [Retrieve code from storage docs](/v3/how-to-guides/deployments/store-flow-code) for more information about flow code storage.

## Run a deployment

You can set a deployment to run manually, on a [schedule](/v3/how-to-guides/deployments/create-schedules), or [in response to an event](/v3/how-to-guides/automations/creating-deployment-triggers).

The deployment inherits the infrastructure configuration from the work pool, and can be overridden at deployment creation time or at runtime.

### Work pools that require a worker

To run a deployment with a hybrid work pool type, such as Docker or Kubernetes, you must start a [worker](/v3/concepts/workers/).

A [Prefect worker](/v3/concepts/workers) is a client-side process that checks for scheduled flow runs in the work pool that it matches.
When a scheduled run is found, the worker kicks off a flow run on the specified infrastructure and monitors the flow run until completion.

### Work pools that don't require a worker

Prefect Cloud offers [push work pools](/v3/how-to-guides/deployment_infra/serverless#automatically-create-a-new-push-work-pool-and-provision-infrastructure) that run flows on Cloud provider serverless infrastructure without a worker and that can be set up quickly.

Prefect Cloud also provides the option to run work flows on Prefect's infrastructure through a [Prefect Managed work pool](/v3/how-to-guides/deployment_infra/managed).

These work pool types do not require a worker to run flows.
However, they do require sharing a bit more information with Prefect, which can be a challenge depending upon the security posture of your organization.

## Static vs. dynamic infrastructure

You can deploy your flows on long-lived static infrastructure or on dynamic infrastructure that is able to scale horizontally.
The best choice depends on your use case.

### Static infrastructure

When you have several flows running regularly, [the `serve` method](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes#serve-a-flow)
of the `Flow` object or [the `serve` utility](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes#serve-multiple-flows-at-once)
is a great option for managing multiple flows simultaneously.

Once you have authored your flow and decided on its deployment settings, run this long-running
process in a location of your choosing.
The process stays in communication with the Prefect API, monitoring for work and submitting each run
within an individual subprocess.
Because runs are submitted to subprocesses, any external infrastructure configuration
must be set up beforehand and kept associated with this process.

Benefits to this approach include:

* Users are in complete control of their infrastructure, and anywhere the "serve" Python process can
  run is a suitable deployment environment.
* It is simple to reason about.
* Creating deployments requires a minimal set of decisions.
* Iteration speed is fast.

### Dynamic infrastructure

Consider running flows on dynamically provisioned infrastructure with work pools when you have any of the following:

* Flows that require expensive infrastructure due to the long-running process.
* Flows with heterogeneous infrastructure needs across runs.
* Large volumes of deployments.
* An internal organizational structure in which deployment authors or runners are not members of
  the team that manages the infrastructure.

[Work pools](/v3/concepts/work-pools/) allow Prefect to exercise greater control
of the infrastructure on which flows run.
Options for [serverless work pools](/v3/how-to-guides/deployment_infra/serverless/) allow you to
scale to zero when workflows aren't running.
Prefect even provides you with the ability to
[provision cloud infrastructure via a single CLI command](/v3/how-to-guides/deployment_infra/serverless/#automatically-create-a-new-push-work-pool-and-provision-infrastructure),
if you use a Prefect Cloud push work pool option.

With work pools:

* You can configure and monitor infrastructure configuration within the Prefect UI.
* Infrastructure is ephemeral and dynamically provisioned.
* Prefect is more infrastructure-aware and collects more event data from your infrastructure by default.
* Highly decoupled setups are possible.

<Note>
  **You don't have to commit to one approach**

  You can mix and match approaches based on the needs of each flow. You can also change the
  deployment approach for a particular flow as its needs evolve.
  For example, you might use workers for your expensive machine learning pipelines,
  but use the serve mechanics for smaller, more frequent file-processing pipelines.
</Note>

## Deployment schema

{/* pmd-metadata: notest */}

```python
class Deployment:
    """
    Structure of the schema defining a deployment
    """

    # required defining data
    name: str
    flow_id: UUID
    entrypoint: str
    path: str | None = None

    # workflow scheduling and parametrization
    parameters: dict[str, Any] | None = None
    parameter_openapi_schema: dict[str, Any] | None = None
    schedules: list[Schedule] | None = None
    paused: bool = False
    trigger: Trigger | None = None

    # concurrency limiting
    concurrency_limit: int | None = None
    concurrency_options: ConcurrencyOptions(collision_strategy=Literal['ENQUEUE', 'CANCEL_NEW']) | None = None

    # metadata for bookkeeping
    version: str | None = None
    version_type: VersionType | None = None
    description: str | None = None
    tags: list | None = None

    # worker-specific fields
    work_pool_name: str | None = None
    work_queue_name: str | None = None
    job_variables: dict[str, Any] | None = None
    pull_steps: dict[str, Any] | None = None
```

All methods for creating Prefect deployments are interfaces for populating this schema.

### Required defining data

Deployments require a `name` and a reference to an underlying `Flow`.

The deployment name is not required to be unique across all deployments, but is required to be unique
for a given flow ID. This means you will often see references to the deployment's unique identifying name
`{FLOW_NAME}/{DEPLOYMENT_NAME}`.

You can trigger deployment runs in multiple ways. For a complete guide, see [Run deployments](/v3/how-to-guides/deployments/run-deployments).

Quick examples:

From the CLI:

```bash
prefect deployment run my-first-flow/my-first-deployment
```

From Python:

```python
from prefect.deployments import run_deployment

run_deployment(name="my-first-flow/my-first-deployment")
```

The other two fields are:

* **`path`**: think of the path as the runtime working directory for the flow.
  For example, if a deployment references a workflow defined within a Docker image, the `path` is the
  absolute path to the parent directory where that workflow will run anytime the deployment is triggered.
  This interpretation is more subtle in the case of flows defined in remote filesystems.
* **`entrypoint`**: the entrypoint of a deployment is a relative reference to a function decorated as a
  flow that exists on some filesystem. It is always specified relative to the `path`.
  Entrypoints use Python's standard path-to-object syntax
  (for example, `path/to/file.py:function_name` or simply `path:object`).

The entrypoint must reference the same flow as the flow ID.

Prefect requires that deployments reference flows defined *within Python files*.
Flows defined within interactive REPLs or notebooks cannot currently be deployed as such.
They are still valid flows that will be monitored by the API and observable in the UI whenever they are run,
but Prefect cannot trigger them.

<Note>
  **Deployments do not contain code definitions**

  Deployment metadata references code that exists in potentially diverse locations within your environment.
  This separation means that your flow code stays within your storage and execution
  infrastructure.

  This is key to the Prefect hybrid model: there's a boundary between your proprietary assets,
  such as your flow code, and the Prefect backend (including [Prefect Cloud](/v3/how-to-guides/cloud/connect-to-cloud)).
</Note>

### Workflow scheduling and parametrization

One of the primary motivations for creating deployments of flows is to remotely *schedule* and *trigger* them.
Just as you can call flows as functions with different input values, deployments can be triggered or
scheduled with different values through parameters.

These are the fields to capture the required metadata for those actions:

* **`schedules`**: a list of [schedule objects](/v3/concepts/schedules).
  Most of the convenient interfaces for creating deployments allow users to avoid creating this object themselves.
  For example, when [updating a deployment schedule in the UI](/v3/concepts/schedules)
  basic information such as a cron string or interval is all that's required.
* **`parameter_openapi_schema`**: an [OpenAPI compatible schema](https://swagger.io/specification/) that defines
  the types and defaults for the flow's parameters.
  This is used by the UI and the backend to expose options for creating manual runs as well as type validation.
* **`parameters`**: default values of flow parameters that this deployment will pass on each run.
  These can be overwritten through a trigger or when manually creating a custom run.
* **`enforce_parameter_schema`**: a boolean flag that determines whether the API should validate the parameters
  passed to a flow run against the schema defined by `parameter_openapi_schema`.

<Tip>
  **Scheduling is asynchronous and decoupled**

  Pausing a schedule, updating your deployment, and other actions reset your auto-scheduled runs.
</Tip>

### Concurrency limiting

Prefect supports managing concurrency at the deployment level to enable limiting how many runs of a
deployment can be active at once. To enable this behavior, deployments have the following fields:

* **`concurrency_limit`**: an integer that sets the maximum number of concurrent flow runs for the deployment.
* **`collision_strategy`**: configure the behavior for runs once the concurrency limit is reached.
  Falls back to `ENQUEUE` if unset.
  * `ENQUEUE`: new runs transition to `AwaitingConcurrencySlot` and execute as slots become available.
  * `CANCEL_NEW`: new runs are canceled until a slot becomes available.

<CodeGroup>
  ```sh prefect deploy
  prefect deploy ... --concurrency-limit 3 --collision-strategy ENQUEUE
  ```

  ```python flow.deploy()
  from prefect.client.schemas.objects import (
      ConcurrencyLimitConfig,
      ConcurrencyLimitStrategy
  )

  my_flow.deploy(..., concurrency_limit=3)

  my_flow.deploy(
      ...,
      concurrency_limit=ConcurrencyLimitConfig(
          limit=3, collision_strategy=ConcurrencyLimitStrategy.CANCEL_NEW
      ),
  )
  ```

  ```python flow.serve()
  from prefect.client.schemas.objects import (
      ConcurrencyLimitConfig,
      ConcurrencyLimitStrategy
  )

  my_flow.serve(..., global_limit=3)

  my_flow.serve(
      ...,
      global_limit=ConcurrencyLimitConfig(
          limit=3, collision_strategy=ConcurrencyLimitStrategy.CANCEL_NEW
      ),
  )
  ```
</CodeGroup>

### Metadata for bookkeeping

Important information for the versions, descriptions, and tags fields:

* **`version`**: versions are always set by the client and can be any arbitrary string.
  We recommend tightly coupling this field on your deployments to your software development lifecycle and choosing human-readable version strings.
  If left unset, the version field will be automatically populated in one of two ways:
  * If deploying from a directory inside a Git repository or from a CI environment on a supported version control provider, `version` will be the first eight characters of your commit hash.
  * In all other circumstances, `version` will be your flow's version, which if not assigned in the flow decorator (`@flow(version="my-version")`) will be a hash of the file the flow is defined in.
* **`version_type`**: When a deployment is created or updated, Prefect will attempt to infer version information from your environment.
  Providing a `version_type` instructs Prefect to only attempt version information collection from an environment of that type.
  The following version types are available: `vcs:github`, `vcs:gitlab`, `vcs:bitbucket`, `vcs:azuredevops`, `vcs:git`, or `prefect:simple`.
  `vcs:git` offers similar versioning detail to officially supported version control platforms, but does not support direct linking to commits from the Prefect Cloud UI.
  It is meant as a fallback option in case your version control platform is not supported.
  `prefect:simple` is for any deployment version created where no Git context is available.
  If left unset, Prefect will automatically select the appropriate `version_type` based on the detected environment.
* **`description`**: provide reference material such as intended use and parameter documentation.
  Markdown is accepted. The docstring of your flow function is the default value.
* **`tags`**: group related work together across a diverse set of objects.
  Tags set on a deployment are inherited by that deployment's flow runs. Filter, customize views, and
  searching by tag.

<Tip>
  **Everything has a version**

  Deployments have a version attached; and flows and tasks also have
  versions set through their respective decorators. These versions are sent to the API
  anytime the flow or task runs, allowing you to audit changes.
</Tip>

### Worker-specific fields

[Work pools](/v3/concepts/work-pools/) and [workers](/v3/concepts/workers/) are an advanced deployment pattern that
allow you to dynamically provision infrastructure for each flow run.
The work pool job template interface allows users to create and govern opinionated interfaces
to their workflow infrastructure.
To do this, a deployment using workers needs the following fields:

* **`work_pool_name`**: the name of the work pool this deployment is associated with.
  Work pool types mirror infrastructure types, which means this field impacts the options available
  for the other fields.
* **`work_queue_name`**: if you are using work queues to either manage priority or concurrency, you can
  associate a deployment with a specific queue within a work pool using this field.
* **`job_variables`**: this field allows deployment authors to customize whatever infrastructure
  options have been exposed on this work pool.
  This field is often used for Docker image names, Kubernetes annotations and limits,
  and environment variables.
* **`pull_steps`**: a JSON description of steps that retrieves flow code or
  configuration, and prepares the runtime environment for workflow execution.

Pull steps allow users to highly decouple their workflow architecture.
For example, a common use of pull steps is to dynamically pull code from remote filesystems such as
GitHub with each run of their deployment.


# Define event triggers
Source: https://docs-3.prefect.io/v3/concepts/event-triggers

Define a custom trigger to react to many kinds of events and metrics.

export const events = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/event",
  api: "https://app.prefect.cloud/api/docs#tag/Events",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/automation"
};

export const API = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect API</a>.</p>;

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

When you need a trigger beyond what the templates in the UI trigger builder provide, you can define a custom trigger in JSON. With custom triggers, you have access to the full capabilities of Prefect's automation system—allowing you to react to many kinds of events and metrics in your workspace.

Each automation has a single trigger that, when fired, causes all of its associated actions to run. That single
trigger may be a reactive or proactive event trigger, a trigger monitoring the value of a metric, or a composite trigger
that combines several underlying triggers.

<TF name="events" href={events.tf} />

<API name="events" href={events.api} />

### Event triggers

Event triggers are the most common type of trigger. They are intended to react to the presence or absence of an event.
Event triggers are indicated with `{"type": "event"}`.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-custom.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=3730bde404e00cd0da5c0d1f8f1875a4" alt="Viewing a custom trigger for automations in the UI" data-og-width="1648" width="1648" data-og-height="1143" height="1143" data-path="v3/img/ui/automations-custom.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-custom.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=8f6603cf67b3b07db9495a6fb47b241c 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-custom.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=4734d725c76dec1ce0f8d6b1b0d3a558 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-custom.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=7db2330793b58f257a110b5e9b611353 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-custom.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=b02dd01235fe3fbaf8d05b498715621a 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-custom.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=2a2dea32f6c8298222cc19b1d0e978f3 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/automations-custom.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=db25362597a3ae23ae0ece28d4417c14 2500w" data-optimize="true" data-opv="2" />

This is the schema that defines an event trigger:

| Name               | Type                      | Supports trailing wildcards | Description                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | ------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **match**          | object                    | ✅                           | Labels for resources which this Automation will match.                                                                                                                                                                                                                                                                                               |
| **match\_related** | object OR array of object | ✅                           | Labels for related resources which this Automation will match.                                                                                                                                                                                                                                                                                       |
| **posture**        | string enum               | N/A                         | The posture of this Automation, either Reactive or Proactive. Reactive automations respond to the presence of the expected events, while Proactive automations respond to the absence of those expected events.                                                                                                                                      |
| **after**          | array of strings          | ✅                           | Event(s), one of which must have first been seen to start this automation.                                                                                                                                                                                                                                                                           |
| **expect**         | array of strings          | ✅                           | The event(s) this automation expects to see. If empty, this automation will evaluate any matched event.                                                                                                                                                                                                                                              |
| **for\_each**      | array of strings          | ❌                           | Evaluate the Automation separately for each distinct value of these labels on the resource. By default, labels refer to the primary resource of the triggering event. You may also refer to labels from related resources by specifying `related:<role>:<label>`. This will use the value of that label for the first related resource in that role. |
| **threshold**      | integer                   | N/A                         | The number of events required for this Automation to trigger (for Reactive automations), or the number of events expected (for Proactive automations)                                                                                                                                                                                                |
| **within**         | number                    | N/A                         | The time period over which the events must occur. For Reactive triggers, this may be as low as 0 seconds, but must be at least 10 seconds for Proactive triggers.                                                                                                                                                                                    |

### Resource matching

Both the `event` and `metric` triggers support matching events for specific resources in your workspace, including most
Prefect objects (like flows, deployment, blocks, work pools, tags) as well as resources you have defined in any
events you emit yourself.

The `match` and `match_related` fields control which events a trigger considers for evaluation
by filtering on the contents of their `resource` and `related` fields, respectively. Each label added to a `match` filter
is `AND`ed with the other labels, and can accept a single value or a list of multiple values that are `OR`ed together.

#### Example

See the `resource` and `related` fields on the following `prefect.flow-run.Completed` event, truncated for this example.
Its primary resource is a flow run, and since that flow run was started by a deployment, it is related to both its flow and its deployment:

```json
"resource": {
  "prefect.resource.id": "prefect.flow-run.925eacce-7fe5-4753-8f02-77f1511543db",
  "prefect.resource.name": "cute-kittiwake"
}
"related": [
  {
    "prefect.resource.id": "prefect.flow.cb6126db-d528-402f-b439-96637187a8ca",
    "prefect.resource.role": "flow",
    "prefect.resource.name": "hello"
  },
  {
    "prefect.resource.id": "prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e",
    "prefect.resource.role": "deployment",
    "prefect.resource.name": "example"
  },
  {
    "prefect.resource.id": "prefect.work-pool.a67da06b-9427-4a0f-a709-c3b37ac29cbf",
    "prefect.resource.role": "work-pool",
    "prefect.resource.name": "k8s-pool",
    "prefect.work-pool.type": "kubernetes"
  },
  {
    "prefect.resource.id": "prefect.tag.examples",
    "prefect.resource.role": "tag"
  }
]
```

There are a number of valid ways to select the above event for evaluation, and the approach depends on the purpose of
the automation.

The following configuration filters for any events whose primary resource is a flow run, *and* that flow run has a
name starting with `cute-` or `radical-`.

```json
"match": {
  "prefect.resource.id": "prefect.flow-run.*",
  "prefect.resource.name": ["cute-*", "radical-*"]
},
"match_related": {},
...
```

By comparison, this configuration filters for any events this specific deployment is a related
resource to:

```json
"match": {},
"match_related": {
  "prefect.resource.id": "prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e"
},
...
```

Both of the above approaches will select the example `prefect.flow-run.Completed` event, but will permit additional,
possibly undesired events through the filter as well. You can combine `match` and `match_related` for more restrictive
filtering:

```json
"match": {
  "prefect.resource.id": "prefect.flow-run.*",
  "prefect.resource.name": ["cute-*", "radical-*"]
},
"match_related": {
  "prefect.resource.id": "prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e"
},
...
```

Now this trigger will filter only for events whose primary resource is a flow run started by a specific deployment,
*and* that flow run has a name starting with `cute-` or `radical-`.

##### Advanced matching for related resources

`match_related` also supports an array of objects, each of which can contain multiple labels.
This allows for more complex matching on related resources, such as filtering for events that are related to a specific work pool or tag.

To match flow runs on a work pool with specific tags, you can use the following configuration:

```json
"match": {
  "prefect.resource.id": "prefect.flow-run.*",
},
"match_related": [
    {
        "prefect.resource.name": "k8s-pool",
        "prefect.resource.role": "work-pool"
    },
    {
        "prefect.resource.id": "prefect.tag.examples",
        "prefect.resource.role": "tag"
    }
]
...
```

### Expected events

Once an event has passed through the `match` filters, you must decide if this event counts toward the
trigger's `threshold`. That is determined by the event names present in `expect`.

This configuration informs the trigger to evaluate *only* `prefect.flow-run.Completed` events that have passed the
`match` filters.

```json
"expect": [
  "prefect.flow-run.Completed"
],
...
```

`threshold` decides the quantity of `expect`ed events needed to satisfy the trigger. Increasing the `threshold`
above 1 requires use of `within` to define a range of time when multiple events are seen. The following
configuration expects two occurrences of `prefect.flow-run.Completed` within 60 seconds:

```json
"expect": [
  "prefect.flow-run.Completed"
],
"threshold": 2,
"within": 60,
...
```

Use `after` to handle scenarios that require more complex event reactivity.

For example, this flow emits an event indicating the table it operates on is missing or empty:

```python
from prefect import flow
from prefect.events import emit_event
from myproject.db import Table


@flow
def transform(table_name: str):
  table = Table(table_name)

  if not table.exists():
    emit_event(
        event="table-missing",
        resource={"prefect.resource.id": "etl-events.transform"}
    )
  elif table.is_empty():
    emit_event(
        event="table-empty",
        resource={"prefect.resource.id": "etl-events.transform"}
    )
  else:
    # transform data
    ...
```

The following configuration uses `after` to prevent this automation from firing unless either a `table-missing` or a
`table-empty` event has occurred before a flow run of this deployment completes.

<Tip>
  Note how `match` and `match_related` ensure the trigger only evaluates events that are relevant to its
  purpose.
</Tip>

```json
"match": {
  "prefect.resource.id": [
    "prefect.flow-run.*",
    "etl-events.transform"
  ]
},
"match_related": {
  "prefect.resource.id": "prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e"
}
"after": [
  "table-missing",
  "table-empty"
]
"expect": [
  "prefect.flow-run.Completed"
],
...
```

### Evaluation strategy

All of the previous examples were designed around a reactive `posture`; that is, count up events toward the
`threshold` until it is met, then execute actions. To respond to the absence of events, use a proactive `posture`.
A proactive trigger fires when its `threshold` has *not* been met by the end of the window of time defined by `within`.
Proactive triggers must have a `within` value of at least 10 seconds.

The following trigger fires if a `prefect.flow-run.Completed` event is not seen within 60 seconds after a
`prefect.flow-run.Running` event is seen:

```json
{
  "match": {
    "prefect.resource.id": "prefect.flow-run.*"
  },
  "match_related": {},
  "after": [
    "prefect.flow-run.Running"
  ],
  "expect": [
    "prefect.flow-run.Completed"
  ],
  "for_each": [],
  "posture": "Proactive",
  "threshold": 1,
  "within": 60
}
```

However, without `for_each`, a `prefect.flow-run.Completed` event from a *different* flow run than the one that
started this trigger with its `prefect.flow-run.Running` event could satisfy the condition. Adding a `for_each` of
`prefect.resource.id` causes this trigger to be evaluated separately for each flow run id associated with these events.

```json
{
  "match": {
    "prefect.resource.id": "prefect.flow-run.*"
  },
  "match_related": {},
  "after": [
    "prefect.flow-run.Running"
  ],
  "expect": [
    "prefect.flow-run.Completed"
  ],
  "for_each": [
    "prefect.resource.id"
  ],
  "posture": "Proactive",
  "threshold": 1,
  "within": 60
}
```

### Metric triggers

Metric triggers (`{"type": "metric"}`) fire when the value of a metric in your workspace crosses a threshold you defined.
For example, you can trigger an automation when the success rate of flows in your workspace drops below 95% over the course
of an hour.

Prefect's metrics are all derived by examining your workspace's events, and if applicable, use the `occurred` times of
those events as the basis for their calculations.

Prefect defines three metrics:

* **Successes** (`{"name": "successes"}`), defined as the number of flow runs that went `Pending` and then the latest
  state we saw was not a failure (`Failed` or `Crashed`). This metric accounts for retries if the ultimate state was
  successful.
* **Duration** (`{"name": "duration"}`), defined as the *length of time* that a flow remains in a `Running` state before
  transitioning to a terminal state such as `Completed`, `Failed`, or `Crashed`. Because this time is derived in terms of
  flow run state change events, it may be greater than the runtime of your function.
* **Lateness** (`{"name": "lateness"}`), defined as the *length of time* that a `Scheduled` flow remains in a `Late`
  state before transitioning to a `Running` and/or `Crashed` state. Only flow runs that the system marks `Late` are included.

This is the schema of a metric trigger:

| Name               | Type                      | Supports trailing wildcards | Description                                                    |
| ------------------ | ------------------------- | --------------------------- | -------------------------------------------------------------- |
| **match**          | object                    | ✅                           | Labels for resources which this Automation will match.         |
| **match\_related** | object OR array of object | ✅                           | Labels for related resources which this Automation will match. |
| **metric**         | `MetricTriggerQuery`      | N/A                         | The definition of the metric query to run.                     |

And the `MetricTriggerQuery` query is defined as:

| Name            | Type                                  | Description                                                             |
| --------------- | ------------------------------------- | ----------------------------------------------------------------------- |
| **name**        | string                                | The name of the Prefect metric to evaluate (see above).                 |
| **threshold**   | number                                | The threshold the current metric value is compared to.                  |
| **operator**    | string (`"<"`, `"<="`, `">"`, `">="`) | The comparison operator to use to decide if the threshold value is met. |
| **range**       | duration in seconds                   | How far back to evaluate the metric.                                    |
| **firing\_for** | duration in seconds                   | How long the value must exceed the threshold before this trigger fires. |

For example, to fire when flow runs tagged `production` in your workspace are failing at a rate of 10% or worse for the last hour (in other words, your success rate is below 90%), create this trigger:

```json
{
  "type": "metric",
  "match": {
    "prefect.resource.id": "prefect.flow-run.*"
  },
  "match_related": {
    "prefect.resource.id": "prefect.tag.production",
    "prefect.resource.role": "tag"
  },
  "metric": {
    "name": "successes",
    "threshold": 0.9,
    "operator": "<",
    "range": 3600,
    "firing_for": 0
  }
}
```

To detect when the average lateness of your Kubernetes workloads (running on a work pool named `kubernetes`) in the
last day exceeds five minutes late—and that number hasn't gotten better for the last 10 minutes—use a trigger like this:

```json
{
  "type": "metric",
  "match": {
    "prefect.resource.id": "prefect.flow-run.*"
  },
  "match_related": {
    "prefect.resource.id": "prefect.work-pool.kubernetes",
    "prefect.resource.role": "work-pool"
  },
  "metric": {
    "name": "lateness",
    "threshold": 300,
    "operator": ">",
    "range": 86400,
    "firing_for": 600
  }
}
```

### Composite triggers

To create a trigger from multiple kinds of events and metrics, use a `compound` or `sequence` trigger.
These higher-order triggers are composed from a set of underlying `event` and `metric` triggers.

For example, if you want to run a deployment only after three different flows in your workspace have written their
results to a remote filesystem, combine them with a 'compound' trigger:

```json
{
  "type": "compound",
  "require": "all",
  "within": 3600,
  "triggers": [
    {
      "type": "event",
      "posture": "Reactive",
      "expect": ["prefect.block.remote-file-system.write_path.called"],
      "match_related": {
        "prefect.resource.name": "daily-customer-export",
        "prefect.resource.role": "flow"
      }
    },
    {
      "type": "event",
      "posture": "Reactive",
      "expect": ["prefect.block.remote-file-system.write_path.called"],
      "match_related": {
        "prefect.resource.name": "daily-revenue-export",
        "prefect.resource.role": "flow"
      }
    },
    {
      "type": "event",
      "posture": "Reactive",
      "expect": ["prefect.block.remote-file-system.write_path.called"],
      "match_related": {
        "prefect.resource.name": "daily-expenses-export",
        "prefect.resource.role": "flow"
      }
    }
  ]
}
```

This trigger fires once it sees at least one of each of the underlying event triggers fire within the time
frame specified. Then the trigger resets its state and fires the next time these three events all happen.
The order the events occur doesn't matter, just that all of the events occur within one hour.

If you want a flow run to complete prior to starting to watch for those three events, you can combine the entire
previous trigger as the second part of a sequence of two triggers:

```json
{
  // the outer trigger is now a "sequence" trigger
  "type": "sequence",
  "within": 7200,
  "triggers": [
    // with the first child trigger expecting a Completed event
    {
      "type": "event",
      "posture": "Reactive",
      "expect": ["prefect.flow-run.Completed"],
      "match_related": {
        "prefect.resource.name": "daily-export-initiator",
        "prefect.resource.role": "flow"
      }
    },
    // and the second child trigger being the compound trigger from the prior example
    {
      "type": "compound",
      "require": "all",
      "within": 3600,
      "triggers": [
        {
          "type": "event",
          "posture": "Reactive",
          "expect": ["prefect.block.remote-file-system.write_path.called"],
          "match_related": {
            "prefect.resource.name": "daily-customer-export",
            "prefect.resource.role": "flow"
          }
        },
        {
          "type": "event",
          "posture": "Reactive",
          "expect": ["prefect.block.remote-file-system.write_path.called"],
          "match_related": {
            "prefect.resource.name": "daily-revenue-export",
            "prefect.resource.role": "flow"
          }
        },
        {
          "type": "event",
          "posture": "Reactive",
          "expect": ["prefect.block.remote-file-system.write_path.called"],
          "match_related": {
            "prefect.resource.name": "daily-expenses-export",
            "prefect.resource.role": "flow"
          }
        }
      ]
    }
  ]
}
```

In this case, the trigger only fires if it sees the `daily-export-initiator` flow complete, and then the three
files written by the other flows.

The `within` parameter for compound and sequence triggers restricts how close in time (in seconds) the child triggers
must fire to satisfy the composite trigger. For example, if the `daily-export-initiator` flow runs, but the other three
flows don't write their result files until three hours later, this trigger won't fire. Placing these time constraints
on the triggers can prevent a misfire if you know that the events will generally happen within a specific timeframe—
and you don't want a stray older event included in the evaluation of the trigger.

If this isn't a concern for you, you may omit the `within` period, in which case there is no limit to how far apart in time the child triggers occur.

You can compose any type of trigger into higher-order composite triggers, including proactive event triggers and metric
triggers. In the following example, the compound trigger fires if any of the following events occur: a flow run
stuck in `Pending`, a work pool becoming unready, or the average amount of `Late` work in your workspace going over
10 minutes:

```json
{
  "type": "compound",
  "require": "any",
  "triggers": [
    {
      "type": "event",
      "posture": "Proactive",
      "after": ["prefect.flow-run.Pending"],
      "expect": ["prefect.flow-run.Running", "prefect.flow-run.Crashed"],
      "for_each": ["prefect.resource.id"],
      "match_related": {
        "prefect.resource.name": "daily-customer-export",
        "prefect.resource.role": "flow"
      }
    },
    {
      "type": "event",
      "posture": "Reactive",
      "expect": ["prefect.work-pool.not-ready"],
      "match": {
        "prefect.resource.name": "kubernetes-workers",
      }
    },
    {
      "type": "metric",
      "metric": {
        "name": "lateness",
        "operator": ">",
        "threshold": 600,
        "range": 3600,
        "firing_for": 300
      }
    }
  ]
}
```

For compound triggers, the `require` parameter may be `"any"`, `"all"`, or a number between 1 and the number of child
triggers. In the example above, if you feel that you are receiving too many spurious notifications for issues that
resolve on their own, you can specify `{"require": 2}` to express that any **two** of the triggers must fire in order
for the compound trigger to fire. Sequence triggers, on the other hand, always require all of their child triggers to
fire before they fire.

Compound triggers are defined as:

| Name         | Type                        | Description                                                             |
| ------------ | --------------------------- | ----------------------------------------------------------------------- |
| **require**  | number, `"any"`, or `"all"` | The number of child triggers that must fire for this trigger to fire    |
| **within**   | time, in seconds            | How close in time the child triggers must fire for this trigger to fire |
| **triggers** | array of other triggers     |                                                                         |

Sequence triggers are defined as:

| Name         | Type                    | Description                                                             |
| ------------ | ----------------------- | ----------------------------------------------------------------------- |
| **within**   | time, in seconds        | How close in time the child triggers must fire for this trigger to fire |
| **triggers** | array of other triggers |                                                                         |

### Support for event trigger types

| Feature                                  | Prefect Open Source | Prefect Cloud |
| ---------------------------------------- | ------------------- | ------------- |
| Event Triggers                           | ✅                   | ✅             |
| Composite Triggers (Compound & Sequence) | ✅                   | ✅             |
| Metric Triggers                          | ❌                   | ✅             |

### Further reading

* [How to create automations](/v3/how-to-guides/automations/creating-automations/)
* [How to create webhooks](/v3/how-to-guides/cloud/create-a-webhook/)


# Events
Source: https://docs-3.prefect.io/v3/concepts/events

An event is a notification of a change - a record of activity in your stack.

export const events = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/event",
  api: "https://app.prefect.cloud/api/docs#tag/Events",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/automation"
};

export const COMBINED = ({name, hrefTF, hrefAPI, hrefCLI}) => <p>You can manage {name} with the <a href={hrefCLI}>Prefect CLI</a>, <a href={hrefTF}>Terraform provider</a>, or <a href={hrefAPI}>Prefect API</a>.</p>;

Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.

Events power several Prefect features, including flow run logs and [automations](/v3/concepts/automations/).
In Prefect Cloud, events power [audit logs](/v3/how-to-guides/cloud/manage-users/audit-logs).

<COMBINED name="events" hrefTF={events.tf} hrefAPI={events.api} hrefCLI={events.cli} />

## Event specification

Events adhere to a structured [specification](https://app.prefect.cloud/api/docs#tag/Events).

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=7b53476f445e37f4f704a19bb5573817" alt="Prefect UI" data-og-width="2484" width="2484" data-og-height="1232" height="1232" data-path="v3/img/ui/event-spec.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=779962b57e203791db71fbd8c1ea887c 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=b049c5542033d7def58b95b16d578cbe 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=ef9e67ed81dc977935485e8e64d85c23 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=721b204f008e1317cebacceffd72d93a 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=3bc5560b4ba944a5cbe630f2169a9b43 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=3d3d7471c090f4e626725fb986bbac4c 2500w" data-optimize="true" data-opv="2" />

| Name     | Type   | Required? | Description                                                     |
| -------- | ------ | --------- | --------------------------------------------------------------- |
| occurred | String | yes       | When the event happened                                         |
| event    | String | yes       | Name of the event that happened                                 |
| resource | Object | yes       | Primary resource this event concerns                            |
| related  | Array  | no        | List of additional Resources involved in this event             |
| payload  | Object | no        | Open-ended set of data describing what happened                 |
| id       | String | yes       | Client-provided identifier of this event                        |
| follows  | String | no        | ID of an event that is known to have occurred prior to this one |

## Event grammar

Events can be named arbitrarily, but are recommended to follow a consistent and informative grammar. An event describes a resource and an action it took—
or that was taken—on that resource.

For example, events emitted automatically by Prefect objects take the following form:

```
prefect.block.write-method.called
prefect-cloud.automation.action.executed
prefect-cloud.user.logged-in
```

See how to [emit and use custom events](/v3/advanced/use-custom-event-grammar) to trigger automations.

## Resources

Every event has a primary resource, which describes the object that emitted an event.
Resources are used as quasi-stable identifiers for sources of events, and are represented as dot-delimited strings.

For example:

```
prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0
acme.user.kiki.elt_script_1
prefect.flow-run.e3755d32-cec5-42ca-9bcd-af236e308ba6
```

Resources can have additional arbitrary labels which can be used in event aggregation queries.
For example:

```json
"resource": {
    "prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3",
    "prefect-cloud.action.type": "call-webhook"
    }
```

Events may contain related resources, used to associate the event with other resources.
For example, a primary resource can act on or with another resource.
Here is an example of a related resource:

```json
"resource": {
    "prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0",
    "prefect-cloud.action.type": "call-webhook"
  },
"related": [
  {
      "prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3",
      "prefect.resource.role": "automation",
      "prefect-cloud.name": "webhook_body_demo",
      "prefect-cloud.posture": "Reactive"
  }
]
```

## Respond to events

From any event detail page, you can configure an [automation](/v3/concepts/automations/) to trigger on
the observation of matching events—or a lack of matching events—by clicking the automate button in the overflow menu:

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=968f24fb6ffab269039b09d05b3e58aa" alt="Automation from event" data-og-width="2480" width="2480" data-og-height="796" height="796" data-path="v3/img/ui/automation-from-event.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=9098f0180536062394bcba4da440cb40 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=99b3657132d09baf37ee38d9be65fd1b 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=524cf7bfd20093eff56186ab500be65b 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=bc21bb74f592d4807768e4c7381a536e 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=872e1e492a1f0dfb404e808eb4deda97 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=b00ea5a334b15565d6db771ac12f86e4 2500w" data-optimize="true" data-opv="2" />

The default trigger configuration fires every time it sees an event with a matching resource identifier.
Advanced configuration is possible through [custom event triggers](/v3/concepts/event-triggers/).

## Further reading

* [How to create automations](/v3/how-to-guides/automations/creating-automations/)
* [How to create webhooks](/v3/how-to-guides/cloud/create-a-webhook/)


# Flows
Source: https://docs-3.prefect.io/v3/concepts/flows

Flows compose work into a workflow.

```python
from prefect import flow

@flow(log_prints=True)
def explain_flows():
    print("run any python code here!")
    print("encapsulate that business logic!")

if __name__ == "__main__":
    explain_flows()
```

## What is a flow?

Flows are defined as decorated Python functions. Above, `explain_flows` is an instance of a flow.

Flows accept inputs, perform work, and potentially return a result.

Generally, flows behave like Python functions, but they have some additional capabilities:

* Metadata about their execution, like each [state](/v3/concepts/states/) the flow enters, is automatically tracked.
* Input arguments can be type validated as workflow [parameters](#specify-flow-parameters).
* [Retries](/v3/how-to-guides/workflows/retries) can be performed on failure, with configurable delay and retry limits.
* [Timeouts](/v3/how-to-guides/workflows/write-and-run#cancel-a-workflow-if-it-runs-for-too-long) can be enforced to prevent unintentional, long-running workflows.
* A flow can be [deployed](/v3/how-to-guides/deployments/create-deployments/), which exposes an API for interacting with it remotely.

<Tip>
  Flows do not need to call other Prefect tasks or flows, but they can.
</Tip>

### Running a flow

A **flow run** is a representation of a single invocation of a flow.

#### The life of a flow run

Each flow run has its own [state](/v3/concepts/states/) lifecycle that is tracked by the Prefect database.

A normal flow run lifetime looks like this:

```mermaid
flowchart TD
    A[Scheduled] -->|⏰ Time to run| B[Pending]
    B -->|🚀 Starting execution| C[Running]
    C -->|✅ Success| D[Completed]
    C -.->|❌ Error occurred| E[Failed]
    C -.->|🛑 User intervention| F[Cancelled]
    C -.->|💥 Infrastructure failure| G[Crashed]

    style A fill:#ff9,stroke:#333,stroke-width:2px,color:#000
    style B fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    style C fill:#9ff,stroke:#333,stroke-width:2px,color:#000
    style D fill:#9f9,stroke:#333,stroke-width:2px,color:#000
    style E fill:#f99,stroke:#333,stroke-width:2px,color:#000
    style F fill:#faa,stroke:#333,stroke-width:2px,color:#000
    style G fill:#f66,stroke:#333,stroke-width:2px,color:#fff

    classDef default fill-opacity:0.9
```

A flow run's lifecycle may be interrupted at any point, whether by:

* manual or accidental cancellation or deletion of the flow run
* disappearance or malfunction of the flow run's host infrastructure
* other unforeseen issues and circumstances (e.g. networking!)

From the perspective of a Prefect server and its clients, a flow run should eventually reach a terminal state. If it doesn't for one of the above reasons, it is called a ["zombie" flow run](/v3/advanced/detect-zombie-flows/).

#### Different ways to create a flow run

The simplest way to create a flow run is to call a `@flow` decorated function (i.e. `__call__`), just like a normal Python function.

```python
from prefect import flow

@flow
def beep():
    print("boop")

beep()
```

You can also create a flow run by:

* Using external schedulers (e.g. `cron` or [Modal](https://modal.com/)) to invoke flows among vanilla Python code
* Triggering an ad-hoc run of a deployment that exists in Prefect Cloud or your Prefect server
* Configuring a [schedule](/v3/how-to-guides/deployments/create-schedules) or [automation](/v3/how-to-guides/automations/creating-automations) to trigger a flow on an interval or sequence of events

[Deployments](/v3/how-to-guides/deployments/create-deployments/) exist to enable [arbitrary infrastructures](/v3/concepts/work-pools/) and schedules for your flow to run on.

However and wherever you run your flow, Prefect monitors the **flow run**, capturing its state for observability.
To customize the default instrumentation of your workflow, you may [log a variety of metadata](/v3/how-to-guides/workflows/add-logging) or [emit events](/v3/advanced/use-custom-event-grammar) about flow runs for monitoring, troubleshooting, and auditing purposes.

### Specify flow parameters

As with any Python function, you can pass arguments to a flow, including both positional and keyword arguments.
These arguments defined on your flow function are called **parameters**.
Within a flow run, you can access the values of your parameters via [runtime context](/v3/concepts/runtime-context/#access-runtime-information).

Prefect automatically performs type conversion of inputs using any provided type hints.
Type hints provide a simple way to enforce typing on your flow parameters and can be customized with [Pydantic](https://pydantic-docs.helpmanual.io/).
Prefect supports any Pydantic model as a type hint for a flow parameter.

Similarly, when invoking a flow run from a [deployment](/v3/how-to-guides/deployments/create-deployments/), Prefect will attempt to coerce provided parameters to the parameter schema implied by your flow function's type signature

<Accordion title="View the parameter schema for a flow">
  You can get a sense of the parameter schema for a flow by inspecting the type signature of the flow function.

  ```python
  import inspect
  from prefect import flow

  @flow
  def schleeb(x: int, y: str, z: bool | None = None):
      print(f"x: {x}, y: {y}, z: {z}")

  inspect.signature(schleeb)
  ```

  ```bash
  <Signature(x: int, y: str, z: bool | None = None)>
  ```

  Or retrieve the actual schema inferred from the flow function's type signature as a `BaseModel` instance.

  {/* pmd-metadata: notest */}

  ```python
  schleeb.parameters.model_json_schema()
  ```

  ```json
  {
    "description": "Simple data model corresponding to an OpenAPI `Schema`.",
    "properties": {
      "title": {
        "const": "Parameters",
        "default": "Parameters",
        "title": "Title",
        "type": "string"
      },
      "type": {
        "const": "object",
        "default": "object",
        "title": "Type",
        "type": "string"
      },
      "properties": {
        "type": "object",
        "additionalProperties": true,
        "title": "Properties"
      },
      "required": {
        "items": {
          "type": "string"
        },
        "title": "Required",
        "type": "array"
      },
      "definitions": {
        "additionalProperties": true,
        "title": "Definitions",
        "type": "object"
      }
    },
    "title": "ParameterSchema",
    "type": "object"
  }
  ```
</Accordion>

<Warning>
  **Prefect API requires keyword arguments**

  When creating flow runs from the Prefect API, you must specify parameter names when overriding defaults.
  The values passed cannot be positional.
</Warning>

Parameters are validated before a flow is run.
If a flow run for a deployment receives invalid parameters, it moves from a `Pending` state to a `Failed` state without entering a `Running` state.

<Note>
  Flow run parameters cannot exceed `512kb` in size.

  When possible, prefer passing a reference to a large object and load it during your flow run.
</Note>

For a deep dive into flow parameters, see the [form-building tutorial](/v3/advanced/form-building).

## Organize flows with subflows and tasks

A single flow function *can* contain all of your workflow's code.
However, if you put all your code in a single flow function and any line of code fails, the entire flow fails and must be retried from the beginning.
It is possible to go overboard with encapsulation, but making your workflows more granular can often help make your code easier to reason about and debug.

Flows can call [tasks](/v3/concepts/tasks) to perform concurrent and transactional work quickly.

Flows are free to call other flows (each potentially containing their flows and tasks, and so on), the resulting runs referred to as "child" flow or task runs.

### Why both flows and tasks?

Flows are convenient for composition, deployment, and server-side interaction and maintain a consistent context for task runs.

Tasks are quick, cacheable, retryable, have [transactional semantics](/v3/advanced/transactions/) and are easy to run concurrently.

### Considerations when nesting flows

In the UI, each child flow run is linked to its parent and can be individually observed.

For most purposes, nested flow runs behave just like unnested flow runs. There is a full representation of the nested flow run in the backend as if it had been called separately. Nested flow runs differ from normal flow runs in that they resolve any passed task futures into data. This allows data to be passed from the parent flow run to a nested flow run easily.

When a nested flow run starts, it creates a new [task runner](/v3/concepts/task-runners/) for any tasks it contains.
When the nested flow run completes, the task runner shuts down.
Nested flow runs block execution of the parent flow run until completion.
However, asynchronous nested flows can run concurrently with [AnyIO task groups](https://anyio.readthedocs.io/en/stable/tasks.html) or [asyncio.gather](https://docs.python.org/3/library/asyncio-task.html#id6).

The relationship between nested runs is recorded through a special task run in the parent flow run that represents the child flow run.
The `state_details` field of the task run representing the child flow run includes a `child_flow_run_id`.
The `state_details` field of the nested flow run includes a `parent_task_run_id`.

You can define multiple flows within the same file.
Whether running locally or through a [deployment](/v3/how-to-guides/deployments/create-deployments), you must indicate which flow is the entrypoint for a flow run.

<Warning>
  **Cancel nested flow runs**

  A nested flow run cannot be cancelled without cancelling its parent flow run.
  If you need to be able to cancel a nested flow run independent of its parent flow run, we recommend deploying it separately and starting it with
  the [run\_deployment](https://reference.prefect.io/prefect/deployments/flow_runs/#prefect.deployments.flow_runs.run_deployment) method.
</Warning>

Some scenarios where you might want to define a nested flow rather than call tasks individually include:

* **Observability**: Nested flows, like any other flow run, have first-class observability within the Prefect UI and Prefect Cloud. You'll
  see nested flows' status in the **Runs** dashboard rather than having to dig down into the tasks within a specific flow run.
  See [Final state determination](#final-state-determination) for examples of using task state within flows.
* **Conditional business logic**: If you have a group of tasks that run only under certain conditions, you can group them within a nested flow and
  conditionally run the nested flow rather than each task individually.
* **Parameterized workflows**: Flows have first-class support for parameterization, making it easy to run the same group of tasks in different use
  cases by simply passing different parameters to the nested flow in which they run.
* **Task runners**: Nested flows enable you to specify the task runner used for tasks within the flow. For example, to optimize
  parallel execution of certain tasks with Dask, group them in a nested flow that uses the Dask task runner. You can use a different
  task runner for each nested flow.

## Supported function types

Almost any standard Python function can be turned into a Prefect flow by adding the `@flow` decorator.

In particular, Prefect supports:

* Synchronous functions
* Asynchronous functions
* Instance methods
* Class methods
* Static methods
* Generators

<Warning>
  **Generator functions are consumed when returned from flows**

  The result of a completed flow must be serializable, but generators cannot be serialized.
  Therefore, if you return a generator from a flow, the generator will be fully consumed and its yielded values will be returned as a list.
  This can lead to unexpected behavior or blocking if the generator is infinite or very large.

  Here is an example of proactive generator consumption:

  ```python
  from prefect import flow


  def gen():
      yield from [1, 2, 3]
      print('Generator consumed!')


  @flow
  def f():
      return gen()


  f()  # prints 'Generator consumed!'
  ```

  If you need to return a generator without consuming it, you can `yield` it instead of using `return`.
  Values yielded from generator flows are not considered final results and do not face the same serialization constraints:

  ```python
  from prefect import flow


  def gen():
      yield from [1, 2, 3]
      print('Generator consumed!')


  @flow
  def f():
      yield gen()


  generator = next(f())
  list(generator) # prints 'Generator consumed!'
  ```
</Warning>

## Final state determination

A [state](/v3/concepts/states) is a record of the status of a particular task run or flow run.

The final state of a flow is determined by its ***return value***. The following rules apply:

* If an exception is raised directly in the flow function, the flow run is marked as `FAILED`.
* If a flow returns a manually created state, it is used as the state of the final flow run. This allows for manual determination of final state.
* If a flow returns an iterable of states, the presence of *any* `FAILED` state will cause the run to be marked as `FAILED`.

In *any other situation* in which the flow returns without error, it will be marked as `COMPLETED`.

<Warning>
  If you manipulate states programmatically, you can create situations in which tasks
  within a flow can fail and not cause flow run failure.
  For example:

  ```python
  from prefect import flow, task 


  @task 
  def add_one(x):
      return x + 1


  @flow 
  def my_flow():
      # avoided raising an exception via `return_state=True`
      state = add_one("1", return_state=True)
      assert state.is_failed()

      # the flow function returns successfully!
      return
  ```

  If `state` were returned from the flow function, the run would be marked as `FAILED`.
</Warning>

### Return a future

If a flow returns one or more futures, the final state is determined based on the underlying states.

```python
from prefect import flow, task


@task
def always_fails_task():
    raise ValueError("I fail successfully")


@task
def always_succeeds_task():
    print("I'm fail safe!")
    return "success"


@flow
def always_succeeds_flow():
    x = always_fails_task.submit().result(raise_on_failure=False)
    y = always_succeeds_task.submit(wait_for=[x])
    return y


if __name__ == "__main__":
    always_succeeds_flow()
```

This flow run finishes in a **Completed** final state because the flow returns the future of the task that succeeds.

### Return multiple states or futures

If a flow returns a mix of futures and states, the final state is determined by resolving all futures to states,
then determining if any of the states are not `COMPLETED`.

```python
from prefect import task, flow


@task
def always_fails_task():
    raise ValueError("I am bad task")


@task
def always_succeeds_task():
    return "foo"


@flow
def always_succeeds_flow():
    return "bar"


@flow
def always_fails_flow():
    x = always_fails_task()
    y = always_succeeds_task()
    z = always_succeeds_flow()
    return x, y, z
```

Running `always_fails_flow` fails because one of the three returned futures fails.

If multiple states are returned, they must be contained in a `set`, `list`, or `tuple`.

### Return a manual state

If a flow returns a manually created state, the final state is determined based upon the return value.

```python
from prefect import task, flow
from prefect.states import Completed, Failed


@task
def always_fails_task():
    raise ValueError("I fail successfully")


@task
def always_succeeds_task():
    print("I'm fail safe!")
    return "success"


@flow
def always_succeeds_flow():
    x = always_fails_task.submit()
    y = always_succeeds_task.submit()
    if y.result() == "success":
        return Completed(message="I am happy with this result")
    else:
        return Failed(message="How did this happen!?")


if __name__ == "__main__":
    always_succeeds_flow()
```

If a flow run returns any other object, then it is recorded as `COMPLETED`

### Custom named states

You can also create custom named states to provide more granularity in your flow run states.

For example, we could create a `Skipped` state to indicate that a flow run was skipped.

```python
from prefect import flow
from prefect.states import Completed

@flow
def my_flow(work_to_do: bool):
    if not work_to_do:
        return Completed(message="No work to do 💤", name="Skipped")
    else:
        return Completed(message="Work was done 💪")


if __name__ == "__main__":
    my_flow(work_to_do=False)
```


# Concepts
Source: https://docs-3.prefect.io/v3/concepts/index



## Sections

<CardGroup cols={3}>
  <Card title="Workflows" icon="play" href="/v3/concepts/flows">
    Learn about the core concepts for building and running workflows.
  </Card>

  <Card title="Deployments" icon="rocket" href="/v3/concepts/deployments">
    Learn about the concepts behind deploying and executing workflows.
  </Card>

  <Card title="Configuration" icon="gears" href="/v3/concepts/variables">
    Learn about configuring your Prefect environment and workflows.
  </Card>

  <Card title="Automations" icon="robot" href="/v3/concepts/events">
    Learn about events, triggers, and automations.
  </Card>

  <Card title="Prefect Cloud" icon="cloud" href="/v3/concepts/rate-limits">
    Learn about Prefect Cloud-specific concepts and features.
  </Card>
</CardGroup>


# Rate limits and data retention
Source: https://docs-3.prefect.io/v3/concepts/rate-limits



## API rate limits

<Note>
  **Rate limits are subject to change.**

  Contact Prefect support at [help@prefect.io](mailto:help@prefect.io) with questions about rate limits.
</Note>

Prefect Cloud applies rate limits to API endpoints to ensure system stability. When limits are exceeded, endpoints return a `429` response with a `Retry-After` header.

### Request limits by plan

The `flow_runs`, `task_runs`, and `flows` endpoints and their subroutes:

* **Hobby**: 250 requests per minute
* **Starter**: 500 requests per minute
* **Team**: 1,000 requests per minute
* **Pro**: 2,000 requests per minute
* **Enterprise**: Custom limits

The `logs` endpoint:

* **Hobby**: 500 logs per minute
* **Starter**: 1,600 logs per minute
* **Team**: 2,000 logs per minute
* **Pro**: 10,000 logs per minute
* **Enterprise**: Custom limits

The Prefect SDK automatically retries rate-limited requests up to 5 times, using the delay specified in the `Retry-After` header. You can customize this behavior through [client settings](/v3/develop/settings-ref#clientsettings).

## Metadata retention

Prefect Cloud retains flow run, task run, and artifact metadata for a limited time based on your plan. This applies to all workspaces in your account.

### Retention periods by plan

* **Hobby and Starter**: 7 days
* **Team**: 14 days
* **Pro**: 30 days
* **Enterprise**: Custom retention periods

Metadata is retained from creation until the specified period expires. For flow and task runs, retention is calculated from when the run reaches a [terminal state](/v3/develop/manage-states/#state-types). Subflow runs are retained independently from their parent flows.

For custom retention periods, [contact Prefect's sales team](https://www.prefect.io/pricing).


# Runtime context
Source: https://docs-3.prefect.io/v3/concepts/runtime-context

The runtime context allows global access to information about the current run.

Prefect tracks information about the current flow or task run with a run context.

The run context is like a global variable that allows the Prefect engine to determine relationships
between your runs, such as which flow your task was called from.

The run context itself contains many internal objects used by Prefect to manage execution of
your run, and is only available in specific situations. For this reason, we expose a simple interface
that only includes the items you care about and dynamically retrieves additional information when necessary.
We call this the "runtime context" as it contains information that's only accessible during a run.

<Tip>
  **Mock values through environment variable**
  You may want to mock certain values for testing purposes. For example, by manually setting an ID or
  a scheduled start time to ensure your code is functioning properly.

  Mock values in runtime through an environment variable using the schema
  `PREFECT__RUNTIME__{SUBMODULE}__{KEY_NAME}=value`:

  ```bash
  export PREFECT__RUNTIME__TASK_RUN__FAKE_KEY='foo'
  python -c 'from prefect.runtime import task_run; print(task_run.fake_key)' # "foo"
  ```

  If the environment variable mocks an existing runtime attribute, the value is cast to the same type.
  This works for runtime attributes of basic types (`bool`, `int`, `float` and `str`) and `datetime.datetime`.
  For complex types like `list` or `dict`, we suggest mocking them using
  [monkeypatch](https://docs.pytest.org/en/latest/how-to/monkeypatch.html) or a similar tool.
</Tip>

## Access runtime information

The `prefect.runtime` module is the home for all runtime context access. Each major runtime concept
has its own submodule:

* `deployment`: Access information about the deployment for the current run
* `flow_run`: Access information about the current flow run
* `task_run`: Access information about the current task run

For example:

```python my_runtime_info.py
from prefect import flow, task
from prefect import runtime

@flow(log_prints=True)
def my_flow(x):
    print("My name is", runtime.flow_run.name)
    print("I belong to deployment", runtime.deployment.name)
    my_task(2)

@task
def my_task(y):
    print("My name is", runtime.task_run.name)
    print("Flow run parameters:", runtime.flow_run.parameters)

if __name__ == "__main__":
    my_flow(1)
```

Running this file produces output similar to the following:

```bash
10:08:02.948 | INFO    | prefect.engine - Created flow run 'solid-gibbon' for flow 'my-flow'
10:08:03.555 | INFO    | Flow run 'solid-gibbon' - My name is solid-gibbon
10:08:03.558 | INFO    | Flow run 'solid-gibbon' - I belong to deployment None
10:08:03.703 | INFO    | Flow run 'solid-gibbon' - Created task run 'my_task-0' for task 'my_task'
10:08:03.704 | INFO    | Flow run 'solid-gibbon' - Executing 'my_task-0' immediately...
10:08:04.006 | INFO    | Task run 'my_task-0' - My name is my_task-0
10:08:04.007 | INFO    | Task run 'my_task-0' - Flow run parameters: {'x': 1}
10:08:04.105 | INFO    | Task run 'my_task-0' - Finished in state Completed()
10:08:04.968 | INFO    | Flow run 'solid-gibbon' - Finished in state Completed('All states completed.')
```

The above example demonstrates access to information about the current flow run, task run, and deployment.
When run without a deployment (through `python my_runtime_info.py`), you should see `"I belong to deployment None"` logged.
When information is not available, the runtime always returns an empty value.
Because this flow runs outside of a deployment, there is no deployment data.
If this flow was run as part of a deployment, we'd see the name of the deployment instead.

See the [runtime API reference](https://reference.prefect.io/prefect/runtime/flow_run/) for a full list of available attributes.

## Access the run context directly

Access the current run context with `prefect.context.get_run_context()`.
This function raises an exception if no run context is available, meaning you are not in a flow or task run.
If a task run context is available, it is returned even if a flow run context is available.

Alternatively, you can access the flow run or task run context explicitly.
For example, this allows you to access the flow run context from a task run.

Prefect does not send the flow run context to distributed task workers because the context is
costly to serialize and deserialize.

```python
from prefect.context import FlowRunContext, TaskRunContext

flow_run_ctx = FlowRunContext.get()
task_run_ctx = TaskRunContext.get()
```

Unlike `get_run_context`, these method calls do not raise an error if the context is unavailable.
Instead, they return `None`.


# Schedule flow runs
Source: https://docs-3.prefect.io/v3/concepts/schedules

Prefect can schedule when to automatically create new flow runs.

Prefect allows you to specify schedules on which your flows run.
You can add one or more schedules to any deployed flow.
Schedules tell Prefect when and how to create new flow runs.
You can add a schedule to a deployed flow in the Prefect UI, in the CLI through the `prefect deployment schedule` command, or the `prefect.yaml` configuration file.

## Schedule types

Prefect supports three types of schedules:

* [`Cron`](#cron) is most appropriate for users who are already familiar with `cron` from previous use.
* [`Interval`](#interval) is best suited for deployments that run at some consistent cadence that isn't related to absolute time.
* [`RRule`](#rrule) is best suited for deployments that rely on calendar logic for simple recurring schedules, irregular intervals, exclusions,
  or day-of-month adjustments.

<Tip>
  **Schedules can be inactive**

  When you create or edit a schedule, you can set the `active` property to `False` in Python (or `false` in a YAML file) to
  deactivate the schedule.
  This is useful to keep the schedule configuration but temporarily stop the schedule from creating new flow runs.
</Tip>

### Cron

A `Cron` schedule uses a standard [`cron`](https://en.wikipedia.org/wiki/Cron) string to define when flow runs should occur. This is ideal for schedules tied to specific clock times and dates (e.g., "every Monday at 9:00 AM"). You may also provide a timezone to enforce daylight saving time (DST) behaviors.

Prefect's cron scheduling is based on the `croniter` library, allowing it to interpret familiar cron expressions. For example, the expression `0 9 * * MON-FRI` means "at 9:00 AM on every Monday through Friday".

<Tip>
  **Supported `croniter` features**

  While Prefect supports most features of `croniter` for creating `cron`-like schedules, it does not support "R"
  random or "H" hashed keyword expressions or the schedule jittering possible with those expressions.
</Tip>

`Cron` properties include:

| Property | Description                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| cron     | A valid `cron` string. (Required)                                                                                      |
| day\_or  | Boolean indicating how `croniter` handles `day` and `day_of_week` entries. Default is `True`.                          |
| timezone | String name of a time zone. (See the [IANA Time Zone Database](https://www.iana.org/time-zones) for valid time zones.) |

#### How the `day_or` property works

The `day_or` property defaults to `True`, matching the behavior of `cron`.

In this mode, if you specify a `day` (of the month)
entry and a `day_of_week` entry, the schedule runs a flow on both the specified day of the month *and* on the specified day of the
week.

The "or" in `day_or` refers to the two entries treated like an `OR` statement. The schedule should include
both, as in the SQL statement:

```sql
SELECT * FROM employees WHERE first_name = 'Ford' OR last_name = 'Prefect';
```

For example, with `day_or` set to `True`, the cron schedule `* * 3 1 2` runs a flow every minute on the third day of the month
and on Tuesday (the second day of the week) in January (the first month of the year).

With `day_or` set to `False`, the `day` (of the month) and `day_of_week` entries are joined with the more restrictive `AND`
operation, as in the SQL statement:

```sql
SELECT * from employees WHERE first_name = 'Zaphod' AND last_name = 'Beeblebrox';
```

For example, the same schedule, when `day_or` is `False`, runs a flow on every minute on the **third Tuesday** in January.
This behavior matches `fcron` instead of `cron`.

<Note>
  **Daylight saving time considerations**

  If the `timezone` is a DST-observing one, then the schedule adjusts itself appropriately.

  The `cron` rules for DST are based on schedule times, not intervals. This means that an hourly `cron` schedule fires on
  every new schedule hour, not every elapsed hour.
  For example, when clocks are set back, this results in a two-hour pause as the schedule will fire *the first time* 1 AM is reached and *the first time* 2 AM is reached, 120 minutes later.

  Longer schedules, such as one that fires at 9 AM every morning, adjust for DST automatically.
</Note>

### Interval

As the name suggests, an `Interval` schedule is best for deployments that need to run at a consistent cadence not strictly tied to absolute clock time (e.g., "every 10 minutes" or "every 3 hours"). It creates new flow runs on a regular interval, measured in seconds, which can be anchored to a specific `anchor_date`.

```yaml
schedule:
  interval: 600
  timezone: America/Chicago
```

`Interval` properties include:

| Property     | Description                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| interval     | `datetime.timedelta` indicating the time between flow runs. (Required)                                                                                                             |
| anchor\_date | `datetime.datetime` indicating the starting or "anchor" date to begin the schedule. If no `anchor_date` is supplied, the current UTC time is used.                                 |
| timezone     | String name of a time zone, used to enforce localization behaviors like DST boundaries. (See the [IANA Time Zone Database](https://www.iana.org/time-zones) for valid time zones.) |

The `anchor_date` does not indicate a "start time" for the schedule, but a fixed point to
compute intervals.
If the anchor date is in the future, then schedule dates are computed by subtracting the `interval` from it.

<Note>
  **Daylight saving time considerations**

  If the schedule's `anchor_date` or `timezone` are provided with a DST-observing timezone, then the schedule adjusts itself
  appropriately.
  Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals.

  For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this results in two runs that *appear* to be scheduled for 1 AM local time, even though they are an hour apart in UTC time.

  For longer intervals, like a daily schedule, the interval schedule adjusts for DST boundaries so that the clock-hour remains constant.
  This means that a daily schedule that always fires at 9 AM will observe DST and continue to fire at 9 AM in the local time zone.
</Note>

### RRule

For complex scheduling needs that go beyond simple cron expressions or fixed intervals, `RRule` (Recurrence Rule) is the most powerful option. It's ideal for deployments that rely on calendar-based logic, such as "the last weekday of each month," "every other Tuesday," or schedules with specific exclusions.

`RRule` scheduling supports [iCal recurrence rules](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html), providing a rich syntax for defining a wide array of repetitive schedules, from yearly down to every minute.

RRules are appropriate for any kind of calendar-date manipulation, including simple repetition, irregular intervals, exclusions,
week day or day-of-month adjustments, and more. RRules can represent complex logic like:

* The last weekday of each month
* The fourth Thursday of November
* Every other day of the week

`RRule` properties include:

| Property | Description                                                                                                                                                   |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rrule    | String representation of an RRule schedule. See the [`rrulestr` examples](https://dateutil.readthedocs.io/en/stable/rrule.html#rrulestr-examples) for syntax. |
| timezone | String name of a time zone. See the [IANA Time Zone Database](https://www.iana.org/time-zones) for valid time zones.                                          |

You may find it useful to use an RRule string generator such as the [iCalendar.org RRule Tool](https://icalendar.org/rrule-tool.html) to help create valid RRules.

```yaml
schedule:
  rrule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR;UNTIL=20240730T040000Z'
```

<Note>
  **RRule restrictions**
  The max supported character length of an `rrulestr` is 6,500 characters

  `COUNT` is not supported. Please use `UNTIL` or the `/deployments/{id}/runs` endpoint to schedule a fixed number of
  flow runs.
</Note>

<Note>
  **Daylight saving time considerations**

  As a calendar-oriented standard, `RRules` are sensitive to the initial timezone provided.
  A 9 AM daily schedule with a DST-aware start date maintains a local 9 AM time through DST boundaries. A 9 AM daily schedule
  with a UTC start date maintains a 9 AM UTC time.
</Note>

## How scheduling works

Prefect's `Scheduler` service evaluates each deployment's schedules and creates new runs appropriately. It starts
automatically when `prefect server start` is run and it is a built-in service of Prefect Cloud.

The `Scheduler` creates the fewest runs that satisfy the following constraints, in order:

* No more than 100 runs will be scheduled.
* Runs will not be scheduled more than 100 days in the future.
* At least three runs will be scheduled.
* Runs will be scheduled until at least one hour in the future.

These behaviors are adjustable through the relevant settings with the `prefect config
view --show-defaults` command:

```bash
PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE='100'
PREFECT_API_SERVICES_SCHEDULER_ENABLED='True'
PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE='500'
PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS='60.0'
PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS='3'
PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS='100'
PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME='1:00:00'
PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME='100 days, 0:00:00'
```

See the [Settings docs](/v3/develop/settings-and-profiles/) for more information on altering your settings.

These settings mean that if a deployment has an hourly schedule, the default settings will create runs for the next four days (or 100 hours).
If it has a weekly schedule, the default settings will maintain the next 14 runs (up to 100 days in the future).

<Tip>
  **`Scheduler` does not affect execution**

  The Prefect `Scheduler` service only creates new flow runs and places them in `Scheduled` states.
  It is not involved in flow or task execution.
</Tip>

If you change a schedule, previously scheduled flow runs that have not started are removed, and new scheduled flow runs are
created to reflect the new schedule.

To remove all scheduled runs for a flow deployment, you can remove the schedule.

## Further reading

* [How to create schedules](/v3/how-to-guides/deployments/create-schedules)


# Prefect server
Source: https://docs-3.prefect.io/v3/concepts/server

Self-host your own Prefect server instance.

After installing Prefect, you have a Python SDK client that can communicate with either [Prefect Cloud](/v3/how-to-guides/cloud/connect-to-cloud) or a self-hosted Prefect server, backed by a database and a UI.

Prefect Cloud and self-hosted Prefect server share a common set of capabilities. Prefect Cloud provides the additional features required by organizations such as RBAC, Audit logs, and SSO. See the [Prefect Cloud overview](/v3/how-to-guides/cloud/connect-to-cloud) for more information.

<Warning>
  We recommend using the same version of `prefect` for the client and server.
  Old clients are compatible with new servers, but new clients can be incompatible with old servers as new fields are added to the REST API.
  The server will typically return a 422 status code if any issues occur.
</Warning>

## The Prefect database

The Prefect database persists data to track the state of your flow runs and related Prefect concepts, including:

* Flow run and task run state
* Run history
* Logs
* Deployments
* Flow and task run concurrency limits
* Storage blocks for flow and task results
* Variables
* Artifacts
* Work pool status
* Events
* Automations

Prefect supports the following databases:

* **SQLite** (default): Recommended for lightweight, single-server deployments. SQLite requires essentially no setup.
* **PostgreSQL**: Best for production use, high availability, and multi-server deployments. Requires PostgreSQL 14.9 or higher. Prefect uses the [`pg_trgm`](https://www.postgresql.org/docs/current/pgtrgm.html) extension, so it must be installed and enabled.

## Database migrations

Prefect uses [Alembic](https://alembic.sqlalchemy.org/en/latest/) to manage database migrations. Alembic is a database migration tool that provides a framework for generating and applying schema changes to a database.

When you start a Prefect server, it automatically runs any necessary migrations. You can also manage migrations manually using the CLI.

## How to guides

* [Self-host via CLI](/v3/how-to-guides/self-hosted/server-cli) - Start a local server instance
* [Self-host via Docker](/v3/how-to-guides/self-hosted/server-docker) - Run server in containers
* [Scale self-hosted Prefect](/v3/advanced/self-hosted) - Deploy multiple server instances for high availability


# Settings and profiles
Source: https://docs-3.prefect.io/v3/concepts/settings-and-profiles

Prefect settings let you customize behavior across different environments.

## Why use settings?

Settings in Prefect help you control how your workflows behave. They let you easily customize Prefect to work the way you need it to, whether you're testing locally or running in production.

Specifically, settings enable:

* **Environment-Specific Configuration**: Use different settings for development (like detailed logging), testing (like test databases), and production (like your production server) without changing your workflow code.

* **Runtime Flexibility**: Quickly adjust things like retry attempts or logging levels without having to modify and redeploy your workflows.

## Get started with settings

The simplest way declare settings is by creating a `prefect.toml` file in your project directory. For example:

```toml prefect.toml
# Set more detailed logging while developing
[logging]
level = "DEBUG"
```

<Note>
  To use `prefect.toml` or `pyproject.toml` for configuration, `prefect>=3.1` must be installed.

  To use a `.env` file for configuration, `prefect>=3.0.5` must be installed.
</Note>

Most editors have plugins for TOML that provide syntax highlighting, linting, and autocomplete for `prefect.toml` files. If you use VSCode, we recommend the [Even Better TOML extension](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml).

<Tip>
  **Writing TOML**

  TOML is a simple configuration language. If you're new to TOML, learn more about the syntax in the [official documentation](https://toml.io/en/).

  In particular, note that TOML uses square brackets to denote [tables](https://toml.io/en/v1.0.0#table), which are analogous to dictionaries in Python.
</Tip>

## Settings sources

You can configure settings via the following sources (highest to lowest precedence):

* **Environment variables**: Environment variables are useful for temporarily overriding settings or configuring the runtime environment of a single workflow run.

* **`.env` file**: `.env` files are useful for declaring local settings that you want to apply across multiple runs.

* **`prefect.toml` file**: A `prefect.toml` file is useful when you want to declare settings for an entire project. You can keep this file in your project directory and it will be automatically applied regardless of where you run your project.

* **`pyproject.toml` file**: If you already have a `pyproject.toml` file in your project or like to consolidate settings for all your tools in one place, you can declare settings in the `[tool.prefect]` table of your `pyproject.toml` file.

* **Profiles**: Prefect profiles are useful for switching between different environments. For example, you might use one profile for a local Prefect server and another for your production environment.

When multiple settings sources define the same setting, Prefect follows this precedence order (highest to lowest):

<Steps>
  <Step title="Environment variables" />

  <Step title=".env file in the current working directory" />

  <Step title="prefect.toml file in the current working directory" />

  <Step title="pyproject.toml file in the current working directory" />

  <Step title="Active profile settings" />

  <Step title="Default values" />
</Steps>

For example, if you set `PREFECT_API_URL` in both your environment and your active profile, the environment variable value will take precedence.

### Environment variables

Environment variables are useful for temporarily overriding settings or configuring the runtime environment of a workflow.

All Prefect settings can be set using environment variables prefixed with `PREFECT_`. They take precedence over all other sources, making them ideal for adjustments that should only apply to a single session or process.

For example, you can run the following command to temporarily set the logging level for a single flow run:

```bash
PREFECT_LOGGING_LEVEL="DEBUG" python my_flow.py
```

You can also export an environment variable in your shell to apply it to all flow runs in that shell session:

```bash
export PREFECT_LOGGING_LEVEL="DEBUG"
prefect run my_flow.py
```

You can see supported environment variables for each setting in the [settings reference documentation](/v3/develop/settings-ref).

<Tip>
  **Environment variables *always* take precedence**

  Environment variables always take precedence over values declared in other sources.
  This allows you to configure certain runtime behavior for your workflows by setting the appropriate
  environment variable on the job or process executing the workflow.
</Tip>

### `.env` file

`.env` files are useful for declaring local settings that you want to apply across multiple runs.

When running `prefect` in a directory that contains a `.env` file, Prefect will automatically apply the settings in the file. We recommend keeping your `.env` files local and not committing them to your code repositories.

For example, the following `.env` file declares a local setting for the logging level:

```bash .env
PREFECT_LOGGING_LEVEL="DEBUG"
```

Any flows run in the same directory as this `.env` file will use the `DEBUG` logging level, even if they are run in different shell sessions.

View supported environment variables for each setting in the [settings reference documentation](/v3/develop/settings-ref).

### `prefect.toml` file

A `prefect.toml` file is useful when you want to declare settings for an entire project.

You can keep a `prefect.toml` file in your project directory and the declared settings will be automatically applied when running `prefect` in that directory. We recommend committing this file to your code repositories to ensure consistency across environments.

For example, the following `prefect.toml` file declares a setting for the logging level:

```toml prefect.toml
[logging]
level = "DEBUG"
```

If you commit your `prefect.toml` file to a code repository, creating deployments from flows in that repository will use the settings declared in the `prefect.toml` file.

You can see the `prefect.toml` path for each setting in the [settings reference documentation](/v3/develop/settings-ref).

### `pyproject.toml` file

Declaring settings in a `pyproject.toml` file is very similar to declaring settings in a `prefect.toml` file. The main difference is that settings are declared in the `[tool.prefect]` table instead of at the root of the file.

For example, the following `pyproject.toml` file declares a setting for the logging level:

```toml pyproject.toml
[tool.prefect]
logging.level = "DEBUG"
```

The advantage of declaring settings in a `pyproject.toml` file is that it allows you to keep all your dependencies and settings for all your tools in one place. You can learn more about `pyproject.toml` files in the [Python Packaging User Guide](https://packaging.python.org/en/latest/specifications/pyproject-toml/#arbitrary-tool-configuration-the-tool-table).

### Profiles

Prefect profiles are useful for switching between different environments. By creating different profiles with different API URLs, you can easily switch between a local Prefect server and your production environment.

Profiles are stored in a [TOML](https://toml.io/en/) file located at `~/.prefect/profiles.toml` by default. This location can be configured by setting `PREFECT_PROFILES_PATH`.

One and only one profile can be active at any time.

Immediately after installation, the `ephemeral` profile will be used, which only has `PREFECT_SERVER_ALLOW_EPHEMERAL_MODE` configured:

<Tip>
  **What is `PREFECT_SERVER_ALLOW_EPHEMERAL_MODE`?**

  This setting allows a Prefect server to be run ephemerally as needed without explicitly starting a server process.
</Tip>

The `prefect profile` CLI commands enable you to create, review, and manage profiles:

| Command             | Description                                                                        |
| ------------------- | ---------------------------------------------------------------------------------- |
| `create`            | Create a new profile; use the `--from` flag to copy settings from another profile. |
| `delete`            | Delete the given profile.                                                          |
| `inspect`           | Display settings from a given profile; defaults to active.                         |
| `ls`                | List all profile names.                                                            |
| `rename`            | Change the name of a profile.                                                      |
| `use`               | Switch the active profile.                                                         |
| `populate-defaults` | Populate your `profiles.toml` file with opinionated stock profiles.                |

... or you may edit your `profiles.toml` file directly:

```bash
vim ~/.prefect/profiles.toml
```

#### Configure settings for the active profile

The `prefect config` CLI commands enable you to manage the settings within the currently active profile.

| Command | Description                              |
| ------- | ---------------------------------------- |
| set     | Change the value for a setting.          |
| unset   | Restore the default value for a setting. |
| view    | Display the current settings.            |

For example, the following CLI commands set configuration in the `ephemeral` profile and then create a new
profile with new settings:

```bash
prefect profile use ephemeral
prefect config set PREFECT_API_URL=http://127.0.0.1:4200/api

prefect profile create new-profile --from ephemeral
prefect profile use new-profile
prefect config set PREFECT_RESULTS_PERSIST_BY_DEFAULT=true PREFECT_LOGGING_LEVEL="ERROR"

prefect profile inspect
prefect config unset PREFECT_LOGGING_LEVEL -y
```

## Common client settings

* [`api.url`](/v3/develop/settings-ref/#url): this setting specifies the API endpoint of your
  Prefect Cloud workspace or a self-hosted Prefect server instance.
* [`api.key`](/v3/develop/settings-ref/#key): this setting specifies the
  [API key](/v3/how-to-guides/cloud/manage-users/api-keys) used to authenticate with Prefect Cloud.
* [`home`](/v3/develop/settings-ref/#home): the `home` value specifies the local Prefect directory for configuration files,
  profiles, and the location of the default Prefect SQLite database.

<Tip>
  **Use `prefect cloud login` to set these values for Prefect Cloud**

  To set `PREFECT_API_URL` and `PREFECT_API_KEY` for your active profile, run `prefect cloud login`.
  Read more about [managing API keys](/v3/how-to-guides/cloud/manage-users/api-keys).
</Tip>

## Common server settings

* [`server.database.connection_url`](/v3/develop/settings-ref#connection-url): the database connection URL for a self-hosted Prefect server instance.
  Must be provided in a SQLAlchemy-compatible format. Prefect currently supports SQLite and Postgres.


# Measure reliability with Service Level Agreements
Source: https://docs-3.prefect.io/v3/concepts/slas

Define the performance expectations for your flows and to enable automated alerts when those expectations are not met.

<Warning> <b>Experimental:</b> This feature is experimental and may change in the future.</Warning>

## Prerequisites

* Prefect Client Version 3.1.12 or later
* Prefect Cloud account (SLAs are only available in Prefect Cloud)
* (If using Terraform) [Prefect Terraform Provider](https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs) version 2.22.0 or later

## Service Level Agreements

<span class="badge cloud" /> Service Level Agreements (SLAs) help you set and monitor performance standards for your data stack. By establishing specific thresholds for flow runs on your Deployments, you can automatically detect when your system isn't meeting expectations.
When you set up an SLA, you define specific performance criteria - such as a maximum runtime of 10 minutes for a flow. If a flow run exceeds this threshold, the system generates an alert event. You can then use these events to trigger automated responses, whether that's sending notifications to your team or initiating other corrective actions through automations.

## Defining SLAs

To define an SLA you can add it to the deployment through a `prefect.yaml` file, a `.deploy` method, or the CLI:

<AccordionGroup>
  <Accordion title="Defining SLAs in your prefect.yaml file">
    ```yaml prefect.yaml SLA
    deployments:
      my-deployment:
        sla:
            - name: "time-to-completion"
              duration: 10
              severity: "high"
            - name: "lateness"
              within: 600
              severity: "high"
    ```
  </Accordion>

  <Accordion title="Defining SLAs using a .deploy method">
    ```python .deploy SLA
        from prefect import flow
        from prefect._experimental.sla.objects import TimeToCompletionSla, LatenessSla, FrequencySla

        @flow
        def my_flow():
            pass

        flow.from_source(
            source=source,
            entrypoint="my_file.py:my_flow",
        ).deploy(
            name="my-deployment",
            work_pool_name="my_pool",
            _sla=[
                TimeToCompletionSla(name="my-time-to-completion-sla", duration=30, severity="high"),
                LatenessSla(name="my-lateness-sla", within=timedelta(minutes=10), severity="high"),
                FrequencySla(name="my-frequency-sla", stale_after=timedelta(hours=1), severity="high"),
            ]
        )
    ```
  </Accordion>

  <Accordion title="Defining SLAs with the Prefect CLI">
    ```bash CLI SLA
    prefect deploy --sla '{"name": "my-time-to-completion-sla", "duration": 10, "severity": "high"}'
    ```
  </Accordion>

  <Accordion title="Defining SLAs with the Terraform Provider">
    ```hcl Terraform Provider
    provider "prefect" {}

    resource "prefect_flow" "my_flow" {
      name = "my-flow"
    }

    resource "prefect_deployment" "my_deployment" {
      name    = "my-deployment"
      flow_id = prefect_flow.my_flow.id
    }

    resource "prefect_resource_sla" "slas" {
      resource_id = "prefect.deployment.${prefect_deployment.my_deployment.id}"
      slas = [
        {
          name     = "my-time-to-completion-sla"
          severity = "high"
          duration = 30
        },
        {
          name     = "my-lateness-sla"
          severity = "high"
          within   = 600
        },
        {
          name        = "my-frequency-sla"
          severity    = "high"
          stale_after = 3600
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Types of SLAs

### Time to Completion SLA

A Time to Completion SLA describes how long flow runs should take and the severity of going over that duration.
The SLA is triggered when a flow run takes longer than the specified duration to complete.

The Time to Completion SLA requires one unique parameter:

* `duration`: The maximum allowed duration in seconds before the SLA is violated

This SLA is useful for monitoring long-running flows and ensuring they complete within an expected timeframe.
For example, if you set a Time to Completion SLA on your deployment with a `duration` of 600 seconds (10 minutes) the backend will emit an `prefect.sla.violation` event if a flow run does not complete within that timeframe.

### Frequency SLA

A Frequency SLA describes the interval a deployment should run at and the severity of missing that interval.

The Frequency SLA requires one unique parameter:

* `stale_after`: The maximum allowed time between flow runs (e.g. `1 hour` for hourly jobs)

For example, if you have a deployment that should run every hour, you can set up a Frequency SLA with a `stale_after` of 1 hour.
This SLA triggers when more than an hour passes between `Completed` flow runs.

### Lateness SLA

A Lateness SLA describes the severity of a flow run failing to start at its scheduled time.

The Lateness SLA requires one unique parameter:

* `within`: The amount of startup time allotted to a flow run before the SLA is violated.

For example, if a deployment is scheduled to run every day at 10am, and has a Lateness SLA of 5 minutes, the backend will emit an SLA violation event if a flow run does not start by 10:05am.

## Monitoring SLAs

You can monitor SLAs in the Prefect Cloud UI. On the runs page you can see the SLA status in the top level metrics:

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/sla-overview.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=1e48e62b8e670119d56a333ca3561e16" alt="SLA status" data-og-width="3026" width="3026" data-og-height="730" height="730" data-path="v3/img/ui/sla-overview.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/sla-overview.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=29d21b91dbdfa7d8df313b8e41a642bf 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/sla-overview.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=604fd8dd5d7e88cf70dda25108c7c578 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/sla-overview.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=56ba57b46ffb3bae7c739390911dc017 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/sla-overview.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=08d5648d7ef43f1272f6072044d6e6ac 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/sla-overview.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=44a7d01a0b995580e4516561eb308368 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/sla-overview.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=5321d664a963370144f50e247b71caaf 2500w" data-optimize="true" data-opv="2" />

## Setting up an automation

To set up an automation to notify a team or to take other actions when an SLA is triggered, you can use the [automations](/v3/automate/events/automations-triggers/) feature. To create the automation first you'll need to create a trigger.

1. Choose trigger type 'Custom'.
2. Choose any event matching: `prefect.sla.violation`
3. For "From the Following Resources" choose: `prefect.flow-run.*`

<img src="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/sla-trigger-automation.png?fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=9dca987a16c4d0c5501c7e87b9d33c04" alt="Create an automation" data-og-width="3026" width="3026" data-og-height="1788" height="1788" data-path="v3/img/ui/sla-trigger-automation.png" srcset="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/sla-trigger-automation.png?w=280&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=482a1c3ea0d408fab0bf13e3f654c227 280w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/sla-trigger-automation.png?w=560&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=a572a17d05a1b1a28d5794fd89f1b4e2 560w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/sla-trigger-automation.png?w=840&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=fec05464f868c8fc486cf377868b97cc 840w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/sla-trigger-automation.png?w=1100&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=37d8e69a1ce2df3d2646c54391640912 1100w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/sla-trigger-automation.png?w=1650&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=42fee6782e194d0e1e4ddb66040faa92 1650w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/sla-trigger-automation.png?w=2500&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=da10cb229bb58f5ca4517b3865727a6a 2500w" data-optimize="true" data-opv="2" />

After creating the trigger, you can create an automation to notify a team or to take other actions when an SLA is triggered using [automations](/v3/automate/events/automations-triggers/).


# States
Source: https://docs-3.prefect.io/v3/concepts/states

Prefect states contain information about the status of a flow or task run.

States are rich objects that contain information about the status of a particular [task](/v3/develop/write-tasks)
run or [flow](/v3/develop/write-flows/) run.

You can learn many things about a task or flow by examining its current state or the
history of its states. For example, you might observe that a given run:

* is `Scheduled` to run for the third time in an hour
* is `Late` because the associated worker process is not responding
* was `Scheduled` to run, but later `Cancelled` via button in the UI
* was `Cached` from a previous run instead of `Running` again
* has `Completed` after `Running` among its fellow task runs
* ended up `Failed` because Claude left pydantic 1.x syntax in your code
* ended up `Crashed` because you Ctrl-C'd the process

<Note>
  **Only runs have states**:
  Flows and tasks are templates that describe what a system does;
  only when we **run** the system does it also take on a state.
</Note>

## State types

Prefect states have names and types.
A state's name is often, but not always, synonymous with its type. For example, a task run
that is running for the first time has a state with the name Running and the type `RUNNING`. However, if the task retries,
that same task run will have the name Retrying and the type `RUNNING`.

State *types* drive orchestration logic, whereas state *names* provide visual bookkeeping.

The full list of states and state types includes:

| Name                                                   | Type         | Terminal? | Description                                                                                                |
| ------------------------------------------------------ | ------------ | --------- | ---------------------------------------------------------------------------------------------------------- |
| `Scheduled`                                            | `SCHEDULED`  | No        | The run will begin at a particular time in the future.                                                     |
| `Late`                                                 | `SCHEDULED`  | No        | The run's scheduled start time has passed, but it has not transitioned to PENDING (15 seconds by default). |
| <span class="no-wrap">`AwaitingRetry`</span>           | `SCHEDULED`  | No        | The run did not complete successfully because of a code issue and had remaining retry attempts.            |
| <span class="no-wrap">`AwaitingConcurrencySlot`</span> | `SCHEDULED`  | No        | The run is waiting to occupy a concurrency slot prior to submission.                                       |
| `Resuming`                                             | `SCHEDULED`  | No        | The run is scheduled to resume execution.                                                                  |
| `Pending`                                              | `PENDING`    | No        | The run has been submitted to execute, but is waiting on necessary preconditions to be satisfied.          |
| `Running`                                              | `RUNNING`    | No        | The run code is currently executing.                                                                       |
| `Retrying`                                             | `RUNNING`    | No        | The run code is currently executing after previously not completing successfully.                          |
| `Paused`                                               | `PAUSED`     | No        | The run code has stopped executing until it receives manual approval to proceed.                           |
| `Suspended`                                            | `PAUSED`     | No        | The run code has stopped executing and the process has exited.                                             |
| `Cancelling`                                           | `CANCELLING` | No        | The infrastructure on which the code was running is being cleaned up.                                      |
| `Cancelled`                                            | `CANCELLED`  | Yes       | The run did not complete because a user determined that it should not.                                     |
| `Completed`                                            | `COMPLETED`  | Yes       | The run completed successfully.                                                                            |
| `Cached`                                               | `COMPLETED`  | Yes       | The run result was loaded from a previously cached value.                                                  |
| `RolledBack`                                           | `COMPLETED`  | Yes       | The run completed successfully but the transaction rolled back and executed rollback hooks.                |
| `Failed`                                               | `FAILED`     | Yes       | The run did not complete because of a code issue and had no remaining retry attempts.                      |
| `TimedOut`                                             | `FAILED`     | Yes       | The run did not complete because it exceeded its time out.                                                 |
| `Crashed`                                              | `CRASHED`    | Yes       | The run did not complete because of an infrastructure issue.                                               |

## State transitions

When a flow run changes states, you can often tell if it is behaving normally or not.
Here are some common state transitions and what they mean:

|   | From      | To        | Triggered By                        | Explanation                                                                                                                                                                                                                                            |
| - | --------- | --------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ✅ | None      | Scheduled | Manual run, automation, or schedule | A flow run has been created and scheduled for future execution.                                                                                                                                                                                        |
| ✅ | Scheduled | Pending   | Worker                              | A worker is attempting to start the infrastructure for your flow run.                                                                                                                                                                                  |
| ⛔ | Scheduled | Late      | Cloud or self-hosted server         | Typically means that a worker did not pick up the run because 1) no workers are healthy, 2) workers are not polling the right work pool or work queue, or 3) workers are concurrency limited.                                                          |
| ✅ | Pending   | Running   | Worker                              | The infrastructure was provisioned and the flow is running                                                                                                                                                                                             |
| ⛔ | Pending   | Crashed   | Worker or runner                    | Something went wrong. Some possibilities are 1) the worker could have failed to create the infrastructure, 2) the code is not present in storage or the worker failed to authenticate, or 3) the code has missing or broken imports, or syntax errors. |
| ✅ | Running   | Completed | Flow run                            | The flow completed successfully.                                                                                                                                                                                                                       |
| ⛔ | Running   | Failed    | Flow run                            | This usually means that your code raised an exception, check the flow run logs.                                                                                                                                                                        |
| ⛔ | Running   | Crashed   | Worker or flow run                  | Probably not a raised exception in your code, but could be an infrastructure issue such as 1) an out of memory error, 2) an evicted pod, or 3) a timeout.                                                                                              |

## Final state determination

The final state of a flow or task run depends on a number of factors; generally speaking there are three categories of terminal states:

* `COMPLETED`: a run in any `COMPLETED` state did not encounter any errors or exceptions and returned successfully
* `FAILED`: a run in any `FAILED` state encountered an error during execution, such as a raised exception
* `CRASHED`: a run in any `CRASHED` state was interrupted by an OS signal such as a `KeyboardInterrupt` or `SIGTERM`

The flow of state transitions can be visualized here:

<Note>
  States are represented by their name, with boxes behind states clarifying their underlying type. Dotted lines lead to terminal states.
</Note>

```mermaid
%%{
  init: {
    'theme': 'neutral',
    'flowchart': {
      'curve' : 'linear',
      'rankSpacing': 80,
      'nodeSpacing': 70,
      'width': 5
    }
  }
}%%

flowchart TD
    %% Style definitions
    classDef scheduled fill:#fcd14edb,stroke:#fcd14edb
    classDef pending fill:#A99FADdb,stroke:#A99FAD
    classDef running fill:#1860f2db,stroke:#1860f2db
    classDef paused fill:#a99faddb,stroke:#a99faddb
    classDef completed fill:#2ac769db,stroke:#2ac769db,stroke-width:2px
    classDef failed fill:#fb4e4ef5,stroke:#fb4e4ef5,stroke-width:2px
    classDef crashed fill:#f97316db,stroke:#f97316db,stroke-width:2px
    classDef cancelled fill:#3d3d3da8,stroke:#3d3d3da8,stroke-width:2px
    classDef awaiting_concurrency_slot fill:#ede7f6,stroke:#4527a0,stroke-width:2px

    %% States
    subgraph scheduled_type[Scheduled]
    Scheduled[Scheduled]:::scheduled
    Late[Late]:::scheduled
    AwaitingConcurrencySlot[AwaitingConcurrencySlot]:::scheduled
    end

    Running[Running]:::running

    Failed[Failed]:::failed

    subgraph scheduled_type2[Scheduled]
    AwaitingRetry[Awaiting Retry]:::scheduled
    end

    subgraph running_type[Running]
    Retrying[Retrying]:::running
    end

    Pending[Pending]:::pending



    Cancelling[Cancelling]:::cancelled
    Cancelled[Cancelled]:::cancelled
    
    Cached[Cached]:::completed
    RolledBack[Rolled Back]:::completed
    Crashed[Crashed]:::crashed

    Paused[Paused]:::paused

    Completed[Completed]:::completed

    %% Connections
    Scheduled --> |Scheduled start time passes without entering Pending| Late
    Scheduled --> |Worker/Runner successfully submits run| Pending
    Scheduled --> |Worker encounters concurrency limit| AwaitingConcurrencySlot

    AwaitingConcurrencySlot --> Pending
    
    Late -->  Pending

    Pending --> |Preconditions met| Running    


    Running -.-> |Success| Completed

    %%problematic section:
    Retrying -.-> |Success| Completed
    Failed --> |Retries remaining| AwaitingRetry
    AwaitingRetry --> |Retry attempt| Retrying
    Retrying -.-> |Failure| Failed
    
    

    Running -.-> |Error| Failed

    Running -.-> |Infrastructure issue| Crashed
    Running -.-> |Cache hit| Cached
    Running -.-> |Transaction rollback| RolledBack
    Running --> |User cancels| Cancelling

    Running --> |Manual pause| Paused
    Paused --> |Resume| Running
    
    Cancelling -.-> |Cleanup complete| Cancelled



```

### Task return values

A task will be placed into a `Completed` state if it returns  *any* Python object, with one exception:
if a task explicitly returns a Prefect `Failed` state, the task will be marked `Failed`.

```python
from prefect import task, flow
from prefect.states import Completed, Failed


@task
def toggle_task(fail: bool):
    if fail:
        return Failed(message="I was instructed to fail.")
    else:
        return Completed(message="I was instructed to succeed.")


@flow
def example():
    # this run will be set to a `Failed` state
    state_one = toggle_task(fail=True)

    # this run will be set to a `Completed` state
    state_two = toggle_task(fail=False)

    # similarly, the flow run will fail because we return a `Failed` state
    return state_one, state_two
```

You can also access state objects directly within a flow through the `return_state` flag:

```python
from prefect import flow, task


@task
def add_one(x):
    return x + 1


@flow
def my_flow():
    result = add_one(1)
    assert isinstance(result, int) and result == 2

    state = add_one(1, return_state=True)
    assert state.is_completed() is True
    assert state.result() == 2
```

<Tip>
  Returning a `State` via `return_state=True` is useful when you want to conditionally respond to the terminal states of a task or flow. For example, `if state.is_failed(): ...`.
</Tip>

### Flow return values

The final state of a flow is determined by its ***return value***. The following rules apply:

* If an exception is raised directly in the flow function, the flow run is marked as `FAILED`.
* If a flow returns a manually created state, it is used as the state of the final flow run. This allows for manual determination of final state.
* If a flow returns an iterable of states, the presence of *any* `FAILED` state will cause the run to be marked as `FAILED`.

In *any other situation* in which the flow returns without error, it will be marked as `COMPLETED`.

<Warning>
  If you manipulate states programmatically, you can create situations in which tasks
  within a flow can fail and not cause flow run failure.
  For example:

  ```python
  from prefect import flow, task 


  @task 
  def add_one(x):
      return x + 1


  @flow 
  def my_flow():
      # avoided raising an exception via `return_state=True`
      state = add_one("1", return_state=True)
      assert state.is_failed()

      # the flow function returns successfully!
      return
  ```

  If `state` were returned from the flow function, the run would be marked as `FAILED`.
</Warning>

## State change hooks

State change hooks execute code in response to ***client side*** changes in flow or task run states, enabling you to define actions for
specific state transitions in a workflow.

State hooks have the following signature:

```python
from prefect import Task, Flow
from prefect.states import State
from prefect.client.schemas.objects import TaskRun, FlowRun

def my_task_state_hook(task: Task, run: TaskRun, state: State) -> None:
    ...

def my_flow_state_hook(flow: Flow, run: FlowRun, state: State) -> None:
    ...
```

State change hooks are versatile, allowing you to specify multiple state change hooks for the same state transition,
or to use the same state change hook for different transitions.

### Further reading

* See examples of [how to execute code in response to entering states](/v3/how-to-guides/workflows/state-change-hooks) in your flows and tasks.


# Tag-based concurrency limits
Source: https://docs-3.prefect.io/v3/concepts/tag-based-concurrency-limits

Understand how tag-based concurrency limits prevent too many tasks from running simultaneously.

Tag-based concurrency limits prevent too many tasks from running simultaneously by using [task tags](/v3/how-to-guides/workflows/tag-based-concurrency-limits). You can specify a maximum number of concurrent task runs in a `Running` state for tasks with a given tag.

<Note>
  As of Prefect 3.4.19, tag-based concurrency limits are backed by [global concurrency limits](/v3/how-to-guides/workflows/global-concurrency-limits). When you create a tag-based limit, Prefect automatically creates a corresponding global concurrency limit with the name `tag:{tag_name}`. This implementation detail is generally transparent to users, but you may see these global limits in your UI or API responses.
</Note>

## How tag-based limits work

If a task has multiple tags, it will run only if ***all*** tags have available concurrency.

Tags without specified concurrency limits are treated as unlimited. Setting a tag's concurrency limit to 0 causes immediate abortion of any task runs with that tag, rather than delaying them.

<Tip>
  Tag-based task concurrency is different from manually created global concurrency limits, though they can be used to achieve similar outcomes. Global concurrency limits are a more general way to control concurrency for any Python-based operation, whereas tag-based concurrency limits are specific to Prefect tasks.
</Tip>

## Execution behavior

Task tag limits are checked whenever a task run attempts to enter a `Running` state.

If there are no concurrency slots available for any one of your task's tags, it delays the transition to a `Running` state and instructs the client to try entering a `Running` state again in 30 seconds (or the value specified by the `PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS` setting).

## Use cases

Tag-based concurrency limits are useful when you have tasks that interact with shared resources. For example:

* **Database connections**: If many tasks across multiple flows interact with a database that only allows 10 connections, you can tag all database tasks with `database` and set a limit of 10.
* **API rate limiting**: Tasks that call external APIs can be tagged and limited to respect rate limits.
* **Resource contention**: Tasks that use memory-intensive operations can be limited to prevent system overload.


# Task runners
Source: https://docs-3.prefect.io/v3/concepts/task-runners

Learn about task runners for concurrent, parallel or distributed execution of tasks.

Task runners are a simple and consistent interface to concurrency primitives - they are not required for task execution.
Calling a task function directly executes the function in the main thread by default,
blocking execution of its caller until the task completes.

To enable concurrent, parallel, or distributed execution of tasks, use the `.submit()` or `.map()` methods to submit tasks to a **task runner**.

## Available task runners

The default task runner in Prefect is the [`ThreadPoolTaskRunner`](/v3/api-ref/python/prefect-task_runners#threadpooltaskrunner),
which runs tasks concurrently in independent threads.

For CPU-intensive tasks that benefit from process isolation, use the [`ProcessPoolTaskRunner`](/v3/api-ref/python/prefect-task_runners#processpooltaskrunner),
which runs tasks in separate processes using Python's `multiprocessing` module.

For distributed task execution across multiple machines, you can use one of the following task runners, which are available as extras of the `prefect` library:

* [`DaskTaskRunner`](/integrations/prefect-dask) can run tasks using [`dask.distributed`](http://distributed.dask.org/) (install `prefect[dask]`)
* [`RayTaskRunner`](/integrations/prefect-ray) can run tasks using [Ray](https://www.ray.io/) (install `prefect[ray]`)

<Note>
  **Concurrency vs. parallelism**

  * **Concurrency** refers to a system that can do more than one thing simultaneously,
    but not at the *exact* same time. Think of concurrent execution as non-blocking:
    within the restrictions of resources available in the execution environment and data dependencies between tasks,
    execution of one task does not block execution of other tasks in a flow.
  * **Parallelism** refers to a system that can do more than one thing at the *exact* same time.
    Within the restrictions of resources available, parallel execution can run tasks at the same time,
    such as for operations mapped across a dataset.
</Note>

## Configure a task runner

To configure a specific task runner, provide a `task_runner` keyword argument to the parent flow:

<CodeGroup>
  ```python {12} title="use threads to run tasks concurrently"
  from prefect import flow, task
  from prefect.futures import wait
  from prefect.task_runners import ThreadPoolTaskRunner
  import time

  @task
  def stop_at_floor(floor):
      print(f"elevator moving to floor {floor}")
      time.sleep(floor)
      print(f"elevator stops on floor {floor}")

  @flow(task_runner=ThreadPoolTaskRunner(max_workers=3))
  def elevator():
      floors = []

      for floor in range(10, 0, -1):
          floors.append(stop_at_floor.submit(floor))

      wait(floors) # wait for the sequence of futures to complete
  ```

  ```python {12} title="use isolated processes to run tasks in parallel"
  from prefect import flow, task
  from prefect.futures import wait
  from prefect.task_runners import ProcessPoolTaskRunner
  import time

  @task
  def stop_at_floor(floor):
      print(f"elevator moving to floor {floor}")
      time.sleep(floor)
      print(f"elevator stops on floor {floor}")

  @flow(task_runner=ProcessPoolTaskRunner(max_workers=3))
  def elevator():
      floors = []

      for floor in range(10, 0, -1):
          floors.append(stop_at_floor.submit(floor))

      wait(floors) # wait for the sequence of futures to complete
  ```
</CodeGroup>

The `max_workers` parameter of the `ThreadPoolTaskRunner` and `ProcessPoolTaskRunner` controls the number of threads or processes (respectively) that the task runner will use to execute tasks.

## Submit tasks to a task runner

When you use `.submit()` to submit a task to a task runner, the task runner creates a
[`PrefectFuture`](/v3/api-ref/python/prefect-futures#prefect.futures.PrefectFuture) for access to the state and
result of the task.

A `PrefectFuture` is an object that provides:

* a reference to the result returned by the task
* a [`State`](/v3/api-ref/python/prefect-server#prefect.server.schemas.states) indicating the current state of the task run

<Warning>
  `PrefectFuture` objects must be resolved explicitly before returning from a flow or task.
  Dependencies between futures will be automatically resolved whenever their dependents are resolved.
  This means that only *terminal* futures need to be resolved, either by:

  * returning the terminal futures from your flow or task
  * calling `.wait()` or `.result()` on each terminal future
  * using one of the top level `wait` or `as_completed` utilities to resolve terminal futures

  Not doing so may leave your tasks in an unfinished state.
</Warning>

When you pass a future into a task, Prefect automatically waits for the "upstream" task (the one that the future references),
to reach a final state before starting the downstream task.

This means that the downstream task won't receive the `PrefectFuture` you passed as an argument.
Instead, the downstream task receives the value that the upstream task returned.

For example:

```python
from prefect import flow, task

@task
def say_hello(name):
    return f"Hello {name}!"

@task
def print_result(result):
    print(type(result))
    print(result)

@flow(name="hello-flow")
def hello_world():
    future = say_hello.submit("Marvin")
    print_result.submit(future).wait()

hello_world()
```

If we run this, we see that we only had to wait for the final `print_result` future as Prefect automatically resolved `say_hello` to a string.

### Access results from submitted tasks

You can access the result of a future explicitly with the `.result()` method.

```python
from prefect import flow, task

@task
def my_task():
    return 42

@flow
def my_flow():
    future = my_task.submit()
    result = future.result()
    print(result)

my_flow()
```

The `.result()` method waits for the task to complete before returning the result to the caller.
If the task run fails, `.result()` will raise the task run's exception. Disable this behavior
with the `raise_on_failure` option:

```python
from prefect import flow, task

@task
def my_task():
    return "I'm a task!"


@flow
def my_flow():
    future = my_task.submit()
    result = future.result(raise_on_failure=False)
    if future.state.is_failed():
        # `result` is an exception! handle accordingly
        ...
    else:
        # `result` is the expected return value of our task
        ...
```

<Note>
  **A few notes on `.result()`**

  * `.result()` is a blocking call.
    This means that calling `.result()` will block the caller until the task run completes.
  * Only use `.result()` when you need to interact directly with the return value of your submitted task;
    for example, you **should** use `.result()` if passing the return value to a standard Python function (not a
    Prefect task) but do not need to use `.result()` if you are passing the value to another task (as these futures will be [automatically resolved](/v3/develop/task-runners/#submit-tasks-to-a-task-runner)).
</Note>

## Design considerations

When choosing how and when to achieve concurrency using task runners, consider the following:

1. **Task granularity**: The "proper" size for tasks depends on the nature and complexity of the work you're doing, e.g. too many small tasks might create overhead - see [Writing tasks](/v3/develop/write-tasks) for more.

2. **Resource constraints**: Be aware of environment limitations. Using `.map` can create many task instances very quickly, which might exceed your resource availability.

3. **Data transfer**: Large data passed between tasks can impact performance. Consider passing references to external storage when dealing with large datasets.

4. **Parallelism**: For true parallelism (rather than just concurrency), consider using a specialized task runner like the `DaskTaskRunner` or `RayTaskRunner` (or [propose a new task runner type](https://github.com/PrefectHQ/prefect/issues/new?template=2_feature_enhancement.yaml)).

5. **Beware of unsafe global state**: Use of concurrency or parallelism features like `.submit` and `.map` must respect the underlying primitives to avoid unexpected behavior. For example, the default `ThreadPoolTaskRunner` runs each task in a separate thread, which means that any global state must be threadsafe. Similarly, `DaskTaskRunner` and `RayTaskRunner` are multi-process runners that require global state to be [picklable](https://docs.python.org/3/library/pickle.html).

## Further reading

* [Run tasks concurrently](/v3/how-to-guides/workflows/run-work-concurrently)


# Tasks
Source: https://docs-3.prefect.io/v3/concepts/tasks

Tasks are atomic units of work with transactional semantics.

```python
from prefect import task

@task(log_prints=True)
def explain_tasks():
    print("run any python code here!")
    print("but maybe just a little bit")

if __name__ == "__main__":
    explain_tasks()
```

## What is a task?

Tasks are defined as decorated Python functions. Above, `explain_tasks` is an instance of a task.

Tasks are cache-able and retryable units of work that are easy to execute concurrently, in parallel, and/or with [transactional semantics](/v3/advanced/transactions).

Like flows, tasks are free to call other tasks or flows, there is no required nesting pattern.

Generally, tasks behave like normal Python functions, but they have some additional capabilities:

* Metadata about task runs, such as run time and final state, is automatically tracked
* Each [state](/v3/concepts/states/) the task enters is recorded, enabling observability and state-based logic
* [Futures](/v3/how-to-guides/workflows/run-work-concurrently#handling-futures) from upstream tasks are automatically resolved by downstream tasks
* [Retries](/v3/how-to-guides/workflows/retries) can be performed on failure, with configurable delay and retry limits
* [Caching](/v3/how-to-guides/workflows/cache-workflow-steps) enables result reuse across workflow executions
* [Concurrency](/v3/how-to-guides/workflows/run-work-concurrently) via `.submit()` and `.map()` allow concurrent execution within and across workflows
* [Timeouts](/v3/how-to-guides/workflows/write-and-run#cancel-a-workflow-if-it-runs-for-too-long) can be enforced to prevent unintentional, long-running operations

Tasks are uniquely identified by a task key, which is a hash composed of the task name and the fully qualified name of the function.

## Running a task

A **task run** is a representation of a single invocation of a task.

### The life of a task run

Like flow runs, each task run has its own state lifecycle. Task states provide observability into execution progress and enable sophisticated runtime logic based on upstream outcomes.

Like flow runs, each task run can be observed in the Prefect UI or CLI.

A normal task run lifecycle looks like this:

```mermaid
flowchart TD
    A[Pending] -->|🚀 Starting execution| B[Running]
    A -->|📦 Cached result available| C[Completed]
    B -->|✅ Success| C[Completed]
    B -.->|❌ Error occurred| D[Retrying/AwaitingRetry]
    B -.->|💥 Infrastructure failure| E[Crashed]
    D -->|🔄 Retry attempt| B
    D -.->|😵 Retries exhausted| F[Failed]

    style A fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    style B fill:#9ff,stroke:#333,stroke-width:2px,color:#000
    style C fill:#9f9,stroke:#333,stroke-width:2px,color:#000
    style D fill:#ff9,stroke:#333,stroke-width:2px,color:#000
    style E fill:#f66,stroke:#333,stroke-width:2px,color:#fff
    style F fill:#f99,stroke:#333,stroke-width:2px,color:#000

    classDef default fill-opacity:0.9
```

<Note>
  **[Background tasks](#background-tasks) have an additional state**

  When using `.delay()`, background tasks start in a `Scheduled` state before transitioning to `Pending`. This allows them to be queued and distributed to available workers.
</Note>

### Different ways to create a task run

The simplest way to create a task run is to call a `@task` decorated function (i.e. `__call__`), just like a normal Python function.

```python
from prefect import task

@task
def add_integers(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    add_integers(1, 2)
```

Tasks may be submitted to a [task runner](/v3/how-to-guides/workflows/run-work-concurrently#task-runners) for concurrent execution where the eventual result is desired.

When the result of a task is not required by the caller, it may be delayed to static infrastructure in the background for execution by an available [task worker](/v3/how-to-guides/workflows/run-background-tasks#task-workers).

## Task orchestration model

### Client-side orchestration

Prefect tasks are orchestrated client-side, which means that task runs are created and updated locally. This allows for efficient handling of large-scale workflows with many tasks and improves reliability when connectivity fails intermittently.

Task updates are logged in batch, leading to eventual consistency for task states in the UI and API queries.

### State dependencies

Tasks automatically resolve dependencies based on data flow between them. When a task receives the result or future of an upstream task as input, Prefect establishes an implicit state dependency such that a downstream task cannot begin until the upstream task has `Completed`.

Explicit state dependencies can be introduced with [the `wait_for` parameter.](/v3/how-to-guides/workflows/run-work-concurrently#creating-state-dependencies)

## Task composition within flows

Tasks are typically organized into [flows](/v3/concepts/flows#organize-flows-with-subflows-and-tasks) to create comprehensive workflows.
Each task offers isolated observability within the Prefect UI. Task-level metrics, logs, and state information help identify bottlenecks and troubleshoot issues at a granular level. Tasks can also be reused across multiple flows, promoting consistency and modularity across an organization's data ecosystem.

<Note>
  **How big should a task be?**

  Prefect encourages "small tasks." As a rule of thumb, each task should represent a logical step or significant "side effect" in your workflow.
  This allows task-level observability and orchestration to narrate your workflow out-of-the-box.

  <img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/concepts/narrative-encapsulation.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=0375ef77dac4dbf1fb99b31fb1582aab" alt="Narrative encapsulation" data-og-width="684" width="684" data-og-height="367" height="367" data-path="v3/img/concepts/narrative-encapsulation.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/concepts/narrative-encapsulation.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=fe1c8efcb393efdb8e44a1d62f03a60e 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/concepts/narrative-encapsulation.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=0a4d210602b3fb5f707e4621872845d1 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/concepts/narrative-encapsulation.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=954b944463e2214bc7ccc75548be9e25 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/concepts/narrative-encapsulation.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=f503db6fe162c6347c5161d3e86296b8 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/concepts/narrative-encapsulation.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=31745b7e6a5b5e97fb7226acf4e51b42 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/concepts/narrative-encapsulation.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=b3e3a6de701c1161071f195c7ea58eec 2500w" data-optimize="true" data-opv="2" />
</Note>

For detailed configuration options and implementation guidance, see [how to write and run workflows](/v3/how-to-guides/workflows/write-and-run).

## Background tasks

Background tasks are an alternate task execution model where tasks are submitted in a non-blocking manner by one process and executed by a pool of processes. This execution model is particularly valuable for web applications and workflows that need to dispatch heavy or long-running work without waiting for completion to dedicated, horizontally scaled infrastructure.

When a task is executed with `.delay()`, it pushes the resulting task run onto a server-side topic, which is distributed to an available [task worker](/v3/how-to-guides/workflows/run-background-tasks#task-workers) for execution.

<Note>
  Prefect background tasks can be used in place of tools like [Celery](https://docs.celeryq.dev/en/stable/getting-started/introduction.html) and [RabbitMQ](https://www.rabbitmq.com/) for task queue functionality.
</Note>

Background tasks are useful for scenarios such as:

* Web applications that need to trigger long-running processes without blocking HTTP responses
* Workflows that dispatch work to specialized infrastructure or resource pools
* Systems that need to scale task execution independently from the main application

For implementation details, see [how to run background tasks](/v3/how-to-guides/workflows/run-background-tasks).


# Variables
Source: https://docs-3.prefect.io/v3/concepts/variables

Variables are dynamically-named, mutable string values that can be used to store and reuse non-sensitive bits of data.

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

export const CLI = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect CLI</a>.</p>;

export const variables = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/variable",
  api: "https://app.prefect.cloud/api/docs#tag/Variables",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/variable"
};

export const API = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect API</a>.</p>;

Variables enable you to store and reuse non-sensitive bits of data, such as configuration information.
They are:

* named, mutable values of any JSON type
* scoped to a self-hosted Prefect server instance or a single workspace in a Prefect Cloud account
* meant for values with infrequent writes and frequent reads (but you can create or
  modify variables at any time)
* cacheable for quicker retrieval
* most commonly loaded during flow runtime (but you can load them in other contexts to pass
  configuration information to Prefect configuration files, such as deployment steps)

<Warning>
  **Variables are not Encrypted**

  We do not recommend using variables to store sensitive information. Instead, use
  [Secret blocks](https://docs.prefect.io/develop/blocks/#prefect-built-in-blocks) to store and access
  sensitive information.
</Warning>

## Manage variables

Create, read, edit, and delete variables through the Prefect UI, Python SDK, API, CLI or Terraform.
Names must adhere to these traditional variable naming conventions:

* Have no more than 255 characters
* Only contain lowercase alphanumeric characters (\[a-z], \[0-9]) or underscores (\_). Spaces are not allowed.
* Be unique

Values must have less than or equal to 5000 characters.

Optionally, you can add tags to a variable.

### Through the Prefect UI

View all the variables in your self-hosted Prefect server instance or Prefect Cloud account workspace
in the **Variables** page of the Prefect UI. Both the name and value of all variables
are visible to anyone with access to the server or workspace.

To create a new variable:

1. Select the **+** button next to the header of the **Variables** page.
2. Enter the name and value of the variable.

### Through the Python SDK

You can access variables at runtime using the `prefect.variables` module in the Python SDK.

```python
from prefect.variables import Variable

# Set a variable

Variable.set("my_variable", "my_value")

# Get a variable

my_var = Variable.get("my_variable")

# Update a variable by passing the `overwrite` parameter
# If the variable does not exist, it will be created

Variable.set("my_variable", "my_new_value", overwrite=True)

# Delete a variable
Variable.unset("my_variable")
```

### Through the REST API

<API name="variables" href={variables.api} />

### Through the CLI

<CLI name="variables" href={variables.cli} />

* `prefect variable set` creates or updates a variable.
* `prefect variable get` retrieves a variable's value.
* `prefect variable unset` deletes a variable.
* `prefect variable ls` lists all variables.
* `prefect variable inspect` shows a variable's details.

### Through Terraform

<TF name="variables" href={variables.tf} />


# Webhooks
Source: https://docs-3.prefect.io/v3/concepts/webhooks

Understand Prefect Cloud webhooks, their configuration, and how to use templates to transform incoming HTTP requests into Prefect events.

<span class="badge cloud" />

Prefect Cloud webhooks can receive, observe, and respond to events from other systems. Each webhook exposes a unique URL endpoint to receive events from other systems and transform them into Prefect [events](/v3/concepts/events) for use in [automations](/v3/automate/events/automations-triggers/).

Webhooks are defined by two essential components: a unique URL and a template that translates incoming web requests to a Prefect event.

## Webhook Endpoints

The webhook endpoints have randomly generated opaque URLs that do not divulge any information about your Prefect Cloud workspace. They are rooted at `https://api.prefect.cloud/hooks/`. For example: `https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ`.

Prefect Cloud assigns this URL when you create a webhook; it cannot be set through the API. You may rotate your webhook URL at any time without losing the associated configuration.

All webhooks may accept requests with the most common HTTP methods:

* Use `GET`, `HEAD`, and `DELETE` for webhooks that define a static event template, or a template that does not depend on the *body* of the HTTP request. The headers of the request will be available for templates.
* Use `POST`, `PUT`, and `PATCH` when the webhook request includes a body. See [How HTTP request components are handled](#how-http-request-components-are-handled) for more details on how the body is parsed.

Prefect Cloud webhooks are deliberately quiet to the outside world, and only return a `204 No Content` response when they are successful (except in certain scenarios, [see below](#webhook-authentication-and-validation)) or a `400 Bad Request` error when there is any error interpreting the request. For more visibility when your webhooks fail, see the [Troubleshooting Webhook Configuration](#troubleshooting-webhook-configuration) section below.

## Webhook Authentication and Validation

To enhance security, within a Prefect Cloud Pro or Enterprise tier account, you can assign a service account to a webhook. This feature provides an additional layer of security and is highly recommended, especially for enterprise environments.

### API key authentication

Webhooks can be associated with a service account, and the webhook endpoint will be authenticated using the service account's API key.

To use API key authentication:

1. Create a service account or use an existing one.
2. Associate the service account with your webhook from the UI.
3. Include the API key in the `Authorization` header of your webhook requests:

   ```
   Authorization: Bearer <your-api-key>
   ```

### Account-level security enforcement

An account-level setting is available to enforce authentication on all webhooks. When enabled:

* All existing webhooks without an associated service account will be automatically disabled.
* New webhooks must be created with an associated service account.
* Existing webhooks must be updated to include a service account before they can be re-enabled.

### Azure Event Grid subscriptions

Prefect Cloud webhooks support [Azure Event Grid webhook event handlers](https://learn.microsoft.com/en-us/azure/event-grid/handler-webhooks), including handling the [endpoint validation steps](https://learn.microsoft.com/en-us/azure/event-grid/receive-events?source=recommendations#endpoint-validation). When Event Grid sends a validation request to Prefect Cloud, the webhook automatically responds with the necessary validation code, confirming endpoint ownership and validity.

## Webhook Templates

The purpose of a webhook is to accept an HTTP request from another system and produce a Prefect event from it. You often have little control over the format of those requests, so Prefect's webhook system gives you full configuration on how you turn those notifications from other systems into meaningful events in your Prefect Cloud workspace. The template you define for each webhook determines how individual components of the incoming HTTP request become the event name and resource labels of the resulting Prefect event.

When creating a webhook, you write this template in [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/templates/). All of the built-in Jinja2 blocks and filters are available, as well as the filters from the [`jinja2-humanize-extensions` package](https://pypi.org/project/jinja2-humanize-extension/).

Your goal when defining an event template is to produce a valid JSON object that defines (at minimum) the `event` name and the `resource["prefect.resource.id"]`, which are required of all events. The simplest template is one in which these are statically defined.

<Warning>
  **Make sure to produce valid JSON**

  The output of your template, when rendered, should be a valid string that can be parsed, for example, with `json.loads`.
</Warning>

### Static Webhook Events

Here's a static webhook template example that notifies Prefect when your `recommendations` machine learning model has been updated. Those models are produced on a daily schedule by another team that is using `cron` for scheduling. They aren't able to use Prefect for their flows yet, but they are happy to add a `curl` to the end of their daily script to notify you. Because this webhook is only used for a single event from a single resource, your template can be entirely static:

```JSON
{
    "event": "model.refreshed",
    "resource": {
        "prefect.resource.id": "product.models.recommendations",
        "prefect.resource.name": "Recommendations [Products]",
        "producing-team": "Data Science"
    }
}
```

A webhook with this template may be invoked through *any* of the HTTP methods, including a `GET` request with no body, so the team you are integrating with can include this line at the end of their daily script:

```bash
curl https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ
```

Each time the script hits the webhook, the webhook produces a single Prefect event with that name and resource in your workspace.

### Event fields that Prefect Cloud populates for you

You only had to provide the `event` and `resource` definition, which is not a completely fleshed out event. Prefect Cloud sets default values for any missing fields, such as `occurred` and `id`, so you don't need to set them in your template. Additionally, Prefect Cloud adds the webhook itself as a related resource on all of the events it produces.

If your template does not produce a `payload` field, the `payload` defaults to a standard set of debugging information, including the HTTP method, headers, and body.

### Dynamic Webhook Events

Let's say that after a few days you and the Data Science team are getting a lot of value from the automations you have set up with the static webhook. You've agreed to upgrade this webhook to handle all of the various models that the team produces. It's time to add some dynamic information to your webhook template.

Your colleagues on the team have adjusted their daily `cron` scripts to `POST` a small body that includes the ID and name of the model that was updated:

```bash
curl \
    -d "model=recommendations" \
    -d "friendly_name=Recommendations%20[Products]" \
    -X POST https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ
```

This script sends a `POST` request and the body will include a traditional URL-encoded form with two fields describing the model that was updated: `model` and `friendly_name`. Here's the webhook code that uses Jinja to receive these values in your template and produce different events for the different models:

```jinja2
{
    "event": "model.refreshed",
    "resource": {
        "prefect.resource.id": "product.models.{{ body.model }}",
        "prefect.resource.name": "{{ body.friendly_name }}",
        "producing-team": "Data Science"
    }
}
```

All subsequent `POST` requests will produce events with those variable resource IDs and names. The other statically defined parts, such as `event` or the `producing-team` label you included earlier, will still be used.

<Tip>
  **Use Jinja2's `default` filter to handle missing values**

  Jinja2 has a helpful [`default`](https://jinja.palletsprojects.com/en/3.1.x/templates/#jinja-filters.default) filter that can compensate for missing values in the request. In this example, you may want to use the model's ID in place of the friendly name when the friendly name is not provided: `{{ body.friendly_name|default(body.model) }}`.
</Tip>

### How HTTP request components are handled

The Jinja2 template context includes the three parts of the incoming HTTP request:

* `method` is the uppercased string of the HTTP method, like `GET` or `POST`.
* `headers` is a case-insensitive dictionary of the HTTP headers included with the request. To prevent accidental disclosures, the `Authorization` header is removed.
* `body` represents the body that was posted to the webhook, with a best-effort approach to parse it into an object you can access.

HTTP headers are available without any alteration as a `dict`-like object, but you may access them with header names in any case. For example, these template expressions all return the value of the `Content-Length` header:

```jinja2
{{ headers['Content-Length'] }}

{{ headers['content-length'] }}

{{ headers['CoNtEnt-LeNgTh'] }}
```

The HTTP request body goes through some light preprocessing to make it more useful in templates. If the `Content-Type` of the request is `application/json`, the body will be parsed as a JSON object and made available to the webhook templates. If the `Content-Type` is `application/x-www-form-urlencoded` (as in our example above), the body is parsed into a flat `dict`-like object of key-value pairs. Jinja2 supports both index and attribute access to the fields of these objects, so the following two expressions are equivalent:

```jinja2
{{ body['friendly_name'] }}

{{ body.friendly_name }}
```

<Tip>
  **Only for Python identifiers**

  Jinja2's syntax only allows attribute-like access if the key is a valid Python identifier, so `body.friendly-name` will not work. Use `body['friendly-name']` in those cases.
</Tip>

Prefect Cloud will attempt to parse any other content type (such as `text/plain`) as if it were JSON first. In any case where the body cannot be transformed into JSON, it is made available to your templates as a Python `str`.

### Accept Prefect events directly

In cases where you have more control over the client, your webhook can accept Prefect events directly with a simple pass-through template:

```jinja2
{{ body|tojson }}
```

This template accepts the incoming body (assuming it was in JSON format) and passes it through unmodified. This allows a `POST` of a partial Prefect event as in this example:

```
POST /hooks/AERylZ_uewzpDx-8fcweHQ HTTP/1.1
Host: api.prefect.cloud
Content-Type: application/json
Content-Length: 228

{
    "event": "model.refreshed",
    "resource": {
        "prefect.resource.id": "product.models.recommendations",
        "prefect.resource.name": "Recommendations [Products]",
        "producing-team": "Data Science"
    }
}
```

The resulting event is filled out with the default values for `occurred`, `id`, and other fields as described [above](#event-fields-that-prefect-cloud-populates-for-you).

### Accepting CloudEvents

The [Cloud Native Computing Foundation](https://cncf.io) has standardized [CloudEvents](https://cloudevents.io) for use by systems to exchange event information in a common format. These events are supported by major cloud providers and a growing number of cloud-native systems. Prefect Cloud can interpret a webhook containing a CloudEvent natively with the following template:

```jinja2
{{ body|from_cloud_event(headers) }}
```

The resulting event uses the CloudEvent's `subject` as the resource (or the `source` if no `subject` is available). The CloudEvent's `data` attribute becomes the Prefect event's `payload['data']`, and the other CloudEvent metadata will be at `payload['cloudevents']`. To handle CloudEvents in a more specific way tailored to your use case, use a dynamic template to interpret the incoming `body`.

## Managing Webhooks Programmatically

In addition to [creating webhooks in the Prefect Cloud UI](/v3/how-to-guides/cloud/create-a-webhook), you can also manage them programmatically via the Prefect CLI, the Prefect Cloud API, or Terraform.

* **Prefect CLI**: Use the `prefect cloud webhook` command group. For example, to create a webhook:
  ```bash
  prefect cloud webhook create your-webhook-name \
      --description "Receives webhooks from your system" \
      --template '{ "event": "your.event.name", "resource": { "prefect.resource.id": "your.resource.id" } }'
  ```
  Use `prefect cloud webhook --help` for more commands like `ls`, `get`, `toggle`, and `rotate`. For detailed template guidance, see [Webhook Templates](#webhook-templates).

* **Prefect Cloud API**: You can interact with webhook endpoints programmatically. Refer to the [API documentation](/v3/api-ref/rest-api/cloud/) for available operations.

* **Terraform**: Use the [Prefect Terraform Provider](https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/webhook) to manage webhooks as part of your infrastructure-as-code setup. This is particularly useful for versioning webhook configurations alongside other Prefect resources.

## Troubleshooting Webhook Configuration

The initial configuration of your webhook may require some trial and error as you get the sender and your receiving webhook speaking a compatible language.

When Prefect Cloud encounters an error during receipt of a webhook, it produces a `prefect-cloud.webhook.failed` event in your workspace. This event includes critical information about the HTTP method, headers, and body it received, as well as what the template rendered. Keep an eye out for these events when something goes wrong with webhook processing or template rendering. You can inspect these events in the [event feed](/v3/concepts/events) in the UI to understand what might have gone wrong.


# Work pools
Source: https://docs-3.prefect.io/v3/concepts/work-pools

Learn how to configure dynamic infrastructure provisioning with work pools

Work pools are a bridge between the Prefect orchestration layer and the infrastructure where flows are run.

The primary reason to use work pools is for **dynamic infrastructure provisioning and configuration**.
For example, you might have a workflow that has expensive infrastructure requirements and runs infrequently.
In this case, you don't want an idle process running within that infrastructure.

Other advantages of work pools:

* Configure default infrastructure configurations on your work pools that all jobs inherit and can override.
* Allow platform teams to use work pools to expose opinionated (and enforced) interfaces to the infrastructure that they oversee.
* Allow work pools to prioritize (or limit) flow runs through the use of [work queues](/v3/deploy/infrastructure-concepts/work-pools/#work-queues).

Work pools remain a consistent interface for configuring deployment infrastructure, but only some work pool types require you to run a [worker](/v3/concepts/workers).

| Type                                                  | Description                                                                            | You run a worker |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------- |
| [Hybrid](/v3/concepts/workers)                        | a worker in your infrastructure submits runs to your infrastructure                    | Yes              |
| [Push](/v3/how-to-guides/deployment_infra/serverless) | runs are automatically submitted to your configured serverless infrastructure provider | No               |
| [Managed](/v3/how-to-guides/deployment_infra/managed) | runs are automatically submitted to Prefect-managed infrastructure                     | No               |

Each type of work pool is optimized for different use cases, allowing you to choose the best fit for your specific infrastructure and workflow requirements.
By using work pools, you can efficiently manage the distribution and execution of your Prefect flows across environments and infrastructures.

<Tip>
  **Work pools are like pub/sub topics**

  Work pools help coordinate deployments with workers
  through a known channel: the pool itself. This is similar to how "topics" are used to connect producers and consumers in a
  pub/sub or message-based system. By switching a deployment's work pool, users can quickly change the worker that will execute their runs,
  making it easy to promote runs through environments — or even to debug locally.
</Tip>

The following diagram provides a high-level overview of the conceptual elements involved in defining a work-pool based
deployment that is polled by a worker and executes a flow run based on that deployment.

```mermaid
%%{
  init: {
    'theme': 'neutral',
    'themeVariables': {
      'margin': '10px'
    }
  }
}%%

flowchart LR

    B(Deployment Definition)

    subgraph Server [Prefect API]
        C(Deployment)
    end

    subgraph Remote Storage [Remote Storage]
        D(Flow Code)
    end

    E(Worker)

    subgraph Infrastructure [Infrastructure]
        F((Flow Run))
    end

    B --> C
    B -.-> D
    C --> E
    D -.-> E
    E -.-> F
```

### Work pool types

The following work pool types are supported by Prefect:

<Tabs>
  <Tab title="Prefect Cloud">
    | Infrastructure Type                  | Description                                                                                                                                                                                                                                       |
    | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Process                              | Execute flow runs as subprocesses on a worker. Works well for local execution when first getting started.                                                                                                                                         |
    | AWS Elastic Container Service        | Execute flow runs within containers on AWS ECS. Works with EC2 and Fargate clusters. Requires an AWS account.                                                                                                                                     |
    | Azure Container Instances            | Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account.                                                                                                                                            |
    | Docker                               | Execute flow runs within Docker containers. Works well for managing flow execution environments through Docker images. Requires  access to a running Docker daemon.                                                                               |
    | Google Cloud Run                     | Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account.                                                                                                                                                |
    | Google Cloud Run V2                  | Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account.                                                                                                                                       |
    | Google Vertex AI                     | Execute flow runs within containers on Google Vertex AI. Requires a Google Cloud Platform account.                                                                                                                                                |
    | Kubernetes                           | Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a Kubernetes cluster.                                                                                                                                                   |
    | Google Cloud Run - Push              | Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account. Flow runs are pushed directly to your environment, without the need for a Prefect worker.                                                      |
    | AWS Elastic Container Service - Push | Execute flow runs within containers on AWS ECS. Works with existing ECS clusters and serverless execution through AWS Fargate. Requires an AWS account. Flow runs are pushed directly to your environment, without the need for a Prefect worker. |
    | Azure Container Instances - Push     | Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account. Flow runs are pushed directly to your environment, without the need for a Prefect worker.                                                  |
    | Modal - Push                         | Execute [flow runs on Modal](/v3/how-to-guides/deployment_infra/modal). Requires a Modal account. Flow runs are pushed directly to your Modal workspace, without the need for a Prefect worker.                                                   |
    | Coiled                               | Execute flow runs in the cloud platform of your choice with Coiled.  Makes it easy to run in your account without setting up Kubernetes or other cloud infrastructure.                                                                            |
    | Prefect Managed                      | Execute flow runs within containers on Prefect managed infrastructure.                                                                                                                                                                            |
  </Tab>

  <Tab title="Self-hosted Prefect server">
    | Infrastructure Type           | Description                                                                                                                                                        |
    | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | Process                       | Execute flow runs as subprocesses on a worker. Works well for local execution when first getting started.                                                          |
    | AWS Elastic Container Service | Execute flow runs within containers on AWS ECS. Works with EC2 and Fargate clusters. Requires an AWS account.                                                      |
    | Azure Container Instances     | Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account.                                                             |
    | Docker                        | Execute flow runs within Docker containers. Works well for managing flow execution environments through Docker images. Requires access to a running Docker daemon. |
    | Google Cloud Run              | Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account.                                                                 |
    | Google Cloud Run V2           | Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account.                                                        |
    | Google Vertex AI              | Execute flow runs within containers on Google Vertex AI. Requires a Google Cloud Platform account.                                                                 |
    | Kubernetes                    | Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a Kubernetes cluster.                                                                    |
  </Tab>
</Tabs>

### Work queues

Work queues offer advanced control over how runs are executed. Each work pool has a "default" queue which is used if another  work queue name is not specified.
Add additional queues to a work pool to enable greater control over work delivery through fine-grained priority and concurrency.

#### Queue priority

Each work queue has a priority indicated by a unique positive integer. Lower numbers take greater priority in the allocation of work with `1` being the highest priority.
You can add new queues without changing the rank of the higher-priority queues.

#### Queue concurrency limits

Work queues can also have their own concurrency limits. Each queue is also subject to the global work pool concurrency limit,
which cannot be exceeded.

#### Precise control with priority and concurrency

Together, work queue priority and concurrency enable precise control over work. For example, a pool may have three queues:

* a "low" queue with priority `10` and no concurrency limit
* a "high" queue with priority `5` and a concurrency limit of `3`
* a "critical" queue with priority `1` and a concurrency limit of `1`

This arrangement enables a pattern of two levels of priority: "high" and "low" for regularly scheduled flow runs,
with the remaining "critical" queue for unplanned, urgent work, such as a backfill.

Priority determines the order of flow runs submitted for execution.
If all flow runs are capable of being executed with no limitation due to concurrency or otherwise,
priority is still used to determine order of submission, but there is no impact to execution.

If not all flow runs can execute, usually as a result of concurrency limits, priority determines which queues receive
precedence to submit runs for execution.

Priority for flow run submission proceeds from the highest priority to the lowest priority. In the previous example, all work from the
"critical" queue (priority 1) is submitted, before any work is submitted from "high" (priority 5). Once all work is submitted
from priority queue "critical", work from the "high" queue begins submission.

If new flow runs are received on the "critical" queue while flow runs are still in scheduled on the "high" and "low" queues, flow run
submission goes back to ensuring all scheduled work is first satisfied. This happens from the highest priority queue, until it is empty,
in waterfall fashion.

<Tip>
  **Work queue status**

  A work queue has a `READY` status when it has been polled by a worker in the last 60 seconds. Pausing a work queue gives it a
  `PAUSED` status and means that it will accept no new work until it is unpaused. A user can control the work queue's paused status in the UI.
  Unpausing a work queue gives the work queue a `NOT_READY` status unless a worker has polled it in the last 60 seconds.
</Tip>

## Further reading

* Learn more about [workers](/v3/deploy/infrastructure-concepts/workers) and how they interact with work pools
* Learn how to [deploy flows](/v3/deploy/infrastructure-concepts/prefect-yaml) that run in work pools
* Learn how to set up work pools for:

  * [Kubernetes](/v3/how-to-guides/deployment_infra/kubernetes)
  * [Docker](/v3/how-to-guides/deployment_infra/docker)
  * [Serverless platforms](/v3/how-to-guides/deployment_infra/serverless)
  * [Infrastructure managed by Prefect Cloud](/v3/how-to-guides/deployment_infra/managed)


# Workers
Source: https://docs-3.prefect.io/v3/concepts/workers

Workers poll work pools for new runs to execute.

export const workers = {
  helm: "https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-server"
};

export const HELM = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect Helm charts</a>.</p>;

Workers are lightweight polling services that retrieve scheduled runs from a work pool and execute them.

Workers each have a type corresponding to the execution environment to submit flow runs to.
Workers can only poll work pools that match their type.
As a result, when deployments are assigned to a work pool, you know in which execution environment scheduled flow runs for that deployment will run.

The following diagram summarizes the architecture of a worker-based work pool deployment:

```mermaid
%%{
  init: {
    'theme': 'neutral',
    'themeVariables': {
      'margin': '10px'
    }
  }
}%%

flowchart TD
    subgraph your_infra["Your Execution Environment"]
        worker["Worker"]
        subgraph flow_run_infra[Infrastructure]
            flow_run_a(("Flow Run A"))
        end
        subgraph flow_run_infra_2[Infrastructure]
            flow_run_b(("Flow Run B"))
        end      
    end

    subgraph api["Prefect API"]
    Deployment --> |assigned to| work_pool
        work_pool(["Work Pool"])
    end

    worker --> |polls| work_pool
    worker --> |creates| flow_run_infra
    worker --> |creates| flow_run_infra_2
```

The worker is in charge of provisioning the *flow run infrastructure*.

### Worker types

Below is a list of available worker types. Most worker types require installation of an additional package.

| Worker Type                                                                                          | Description                                       | Required Package     |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------- |
| [`process`](https://reference.prefect.io/prefect/workers/process/)                                   | Executes flow runs in subprocesses                |                      |
| [`kubernetes`](https://reference.prefect.io/prefect_kubernetes/worker/)                              | Executes flow runs as Kubernetes jobs             | `prefect-kubernetes` |
| [`docker`](https://reference.prefect.io/prefect_docker/worker/)                                      | Executes flow runs within Docker containers       | `prefect-docker`     |
| [`ecs`](https://reference.prefect.io/prefect_aws/workers/ecs_worker/)                                | Executes flow runs as ECS tasks                   | `prefect-aws`        |
| [`cloud-run-v2`](https://reference.prefect.io/prefect_gcp/workers/cloud_run_v2/)                     | Executes flow runs as Google Cloud Run jobs       | `prefect-gcp`        |
| [`vertex-ai`](https://reference.prefect.io/prefect_gcp/workers/vertex/)                              | Executes flow runs as Google Cloud Vertex AI jobs | `prefect-gcp`        |
| [`azure-container-instance`](https://reference.prefect.io/prefect_azure/workers/container_instance/) | Execute flow runs in ACI containers               | `prefect-azure`      |
| [`coiled`](https://github.com/coiled/prefect-worker/blob/main/example/README.md)                     | Execute flow runs in your cloud with Coiled       | `prefect-coiled`     |

If you don't see a worker type that meets your needs, consider
[developing a new worker type](/contribute/develop-a-new-worker-type/).

### Worker options

Workers poll for work from one or more queues within a work pool. If the worker references a work queue that doesn't exist, it is created automatically.
The worker CLI infers the worker type from the work pool.
Alternatively, you can specify the worker type explicitly.
If you supply the worker type to the worker CLI, a work pool is created automatically if it doesn't exist (using default job settings).

Configuration parameters you can specify when starting a worker include:

| Option                                            | Description                                                                                                                                 |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name`, `-n`                                    | The name to give to the started worker. If not provided, a unique name will be generated.                                                   |
| `--pool`, `-p`                                    | The work pool the started worker should poll.                                                                                               |
| `--work-queue`, `-q`                              | One or more work queue names for the worker to pull from. If not provided, the worker pulls from all work queues in the work pool.          |
| `--type`, `-t`                                    | The type of worker to start. If not provided, the worker type is inferred from the work pool.                                               |
| <span class="no-wrap">`--prefetch-seconds`</span> | The amount of time before a flow run's scheduled start time to begin submission. Default is the value of `PREFECT_WORKER_PREFETCH_SECONDS`. |
| `--run-once`                                      | Only run worker polling once. By default, the worker runs forever.                                                                          |
| `--limit`, `-l`                                   | The maximum number of flow runs to start simultaneously.                                                                                    |
| `--with-healthcheck`                              | Start a healthcheck server for the worker.                                                                                                  |
| `--install-policy`                                | Install policy to use workers from Prefect integration packages.                                                                            |

You must start a worker within an environment to access or create the required infrastructure to execute flow runs.
The worker will deploy flow runs to the infrastructure corresponding to the worker type. For example, if you start a worker with
type `kubernetes`, the worker deploys flow runs to a Kubernetes cluster.

Prefect must be installed in any environment (for example, virtual environment, Docker container) where you intend to run the worker or
execute a flow run.

<Tip>
  **`PREFECT_API_URL` and `PREFECT_API_KEY`settings for workers**

  `PREFECT_API_URL` must be set for the environment where your worker is running. When using Prefect Cloud, you must also have a user or service account
  with the `Worker` role, which you can configure by setting the `PREFECT_API_KEY`.
</Tip>

### Worker status

Workers have two statuses: `ONLINE` and `OFFLINE`. A worker is online if it sends regular heartbeat messages to the Prefect API.
If a worker misses three heartbeats, it is considered offline. By default, a worker is considered offline a maximum of 90 seconds
after it stopped sending heartbeats, but you can configure the threshold with the `PREFECT_WORKER_HEARTBEAT_SECONDS` setting.

### Worker logs

<span class="badge cloud" /> Workers send logs to the Prefect Cloud API if you're connected to Prefect Cloud.

* All worker logs are automatically sent to the Prefect Cloud API
* Logs are accessible through both the Prefect Cloud UI and API
* Each flow run will include a link to its associated worker's logs

### Worker details

<span class="badge cloud" /> The **Worker Details** page shows you three key areas of information:

* Worker status
* Installed Prefect version
* Installed Prefect integrations (e.g., `prefect-aws`, `prefect-gcp`)
* Live worker logs (if worker logging is enabled)

Access a worker's details by clicking on the worker's name in the Work Pool list.

### Start a worker

Use the `prefect worker start` CLI command to start a worker. You must pass at least the work pool name.
If the work pool does not exist, it will be created if the `--type` flag is used.

```bash
prefect worker start -p [work pool name]
```

For example:

```bash
prefect worker start -p "my-pool"
```

Results in output like this:

```bash
Discovered worker type 'process' for work pool 'my-pool'.
Worker 'ProcessWorker 65716280-96f8-420b-9300-7e94417f2673' started!
```

In this case, Prefect automatically discovered the worker type from the work pool.
To create a work pool and start a worker in one command, use the `--type` flag:

```bash
prefect worker start -p "my-pool" --type "process"
```

```bash
Worker 'ProcessWorker d24f3768-62a9-4141-9480-a056b9539a25' started!
06:57:53.289 | INFO    | prefect.worker.process.processworker d24f3768-62a9-4141-9480-a056b9539a25 - Worker pool 'my-pool' created.
```

In addition, workers can limit the number of flow runs to start simultaneously with the `--limit` flag.
For example, to limit a worker to five concurrent flow runs:

```bash
prefect worker start --pool "my-pool" --limit 5
```

<HELM name="workers" href={workers.helm} />

### Configure prefetch

By default, the worker submits flow runs 10 seconds before they are scheduled to run.
This allows time for the infrastructure to be created so the flow run can start on time.

In some cases, infrastructure takes longer than 10 seconds to start the flow run. You can increase the prefetch time with the
`--prefetch-seconds` option or the `PREFECT_WORKER_PREFETCH_SECONDS` setting.

If this value is *more* than the amount of time it takes for the infrastructure to start, the flow run will *wait* until its
scheduled start time.

### Polling for work

Workers poll for work every 15 seconds by default. You can configure this interval in your [profile settings](/v3/develop/settings-and-profiles/)
with the
`PREFECT_WORKER_QUERY_SECONDS` setting.

### Install policy

The Prefect CLI can install the required package for Prefect-maintained worker types automatically. Configure this behavior
with the `--install-policy` option. The following are valid install policies:

| Install Policy                                                                                               | Description                                                                                                        |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `always`                                                                                                     | Always install the required package. Updates the required package to the most recent version if already installed. |
| `if-not-present`                                                                                             | Install the required package if it is not already installed.                                                       |
| `never`                                                                                                      | Never install the required package.                                                                                |
| `prompt`                                                                                                     | Prompt the user to choose whether to install the required package. This is the default install policy.             |
| If `prefect worker start` is run non-interactively, the `prompt` install policy behaves the same as `never`. |                                                                                                                    |

### Further reading

* See how to [daemonize a Prefect worker](/v3/advanced/daemonize-processes/).

* See more information on [overriding a work pool's job variables](/v3/deploy/infrastructure-concepts/customize).

***


# Hello, world!
Source: https://docs-3.prefect.io/v3/examples/hello-world

Your first steps with Prefect – learn how to create a basic flow and understand core concepts.

{/*
  This page is automatically generated via the `generate_example_pages.py` script. Any changes to this page will be overwritten.
  */}

<a href="https://github.com/PrefectHQ/prefect/blob/main/examples/hello_world.py" target="_blank">View on GitHub</a>

Welcome to your first Prefect flow. In under a minute you will:

1. Ship production-ready orchestration code with **zero boilerplate**.
2. See live, structured logs without writing any logging boilerplate.
3. Understand how the very same Python stays portable from a laptop to Kubernetes (or Prefect Cloud).

*Pro tip*: change anything in this file and re-run it. Prefect hot-loads your new logic in seconds, no image builds, ever.

## Importing Prefect and setting up

We start by importing the essential `flow` decorator from Prefect.

```python
from prefect import flow, tags

```

## Defining a flow

Prefect takes your Python functions and transforms them into flows with enhanced capabilities.

Let's write a simple function that takes a name parameter and prints a greeting.

To make this function work with Prefect, we just wrap it in the `@flow` decorator.

```python
@flow(log_prints=True)
def hello(name: str = "Marvin") -> None:
    """Log a friendly greeting."""
    print(f"Hello, {name}!")


```

## Running our flow locally and with parameters

Now let's see different ways we can call that flow:

1. As a regular call with default parameters
2. With custom parameters
3. Multiple times to greet different people

```python
if __name__ == "__main__":
    # run the flow with default parameters
    with tags(
        "test"
    ):  # This is a tag that we can use to filter the flow runs in the UI
        hello()  # Logs: "Hello, Marvin!"

        # run the flow with a different input
        hello("Marvin")  # Logs: "Hello, Marvin!"

        # run the flow multiple times for different people
        crew = ["Zaphod", "Trillian", "Ford"]

        for name in crew:
            hello(name)

```

## What just happened?

When we decorated our function with `@flow`, the function was transformed into a Prefect flow. Each time we called it:

1. Prefect registered the execution as a flow run
2. It tracked all inputs, outputs, and logs
3. It maintained detailed state information about the execution
4. Added tags to the flow run to make it easier to find when observing the flow runs in the UI

In short, we took a regular function and enhanced it with observability and tracking capabilities.

## But why does this matter?

This simple example demonstrates Prefect's core value proposition: taking regular Python code and enhancing it with production-grade orchestration capabilities. Let's explore why this matters for real-world data workflows.

### You can change the code and run it again

For instance, change the greeting message in the `hello` function to a different message and run the flow again.
You'll see your changes immediately reflected in the logs.

### You can process more data

Add more names to the `crew` list or create a larger data set to process. Prefect will handle each execution and track every input and output.

### You can run a more complex flow

The `hello` function is a simple example, but in its place imagine something that matters to you, like:

* ETL processes that extract, transform, and load data
* Machine learning training and inference pipelines
* API integrations and data synchronization jobs

Prefect lets you orchestrate these operations effortlessly with automatic observability, error handling, and retries.

### Key Takeaways

Remember that Prefect makes it easy to:

* Transform regular Python functions into production-ready workflows with just a [decorator](https://docs.prefect.io/v3/develop/write-flows#write-and-run-flows)
* Get automatic logging, [retries](https://docs.prefect.io/v3/develop/write-tasks#retries), and observability without extra code
* Run the same code anywhere - from your laptop to production
* Build complex data pipelines while maintaining simplicity
* Track every execution with [detailed logs](https://docs.prefect.io/v3/develop/logging#configure-logging) and state information

The `@flow` decorator is your gateway to enterprise-grade orchestration - no complex configuration needed!

For more information about the orchestration concepts demonstrated in this example, see the [Prefect documentation](https://docs.prefect.io/).


# Overview
Source: https://docs-3.prefect.io/v3/examples/index



{/*
  This page is automatically generated via the `generate_example_pages.py` script. Any changes to this page will be overwritten.
  */}

Have an example to share? Check out our [contributing guide](/contribute/docs-contribute#contributing-examples) to get started.

<CardGroup cols={3}>
  <Card title="dbt Model Orchestration" icon="database" href="/v3/examples/run-dbt-with-prefect">
    Orchestrate any dbt project with bullet-proof retries, observability, and a single Python file – no YAML or shell scripts required.
  </Card>

  <Card title="Hello, world!" icon="play" href="/v3/examples/hello-world">
    Your first steps with Prefect – learn how to create a basic flow and understand core concepts.
  </Card>

  <Card title="Simple web scraper" icon="globe" href="/v3/examples/simple-web-scraper">
    Learn how to scrape article content from web pages with Prefect tasks, retries, and automatic logging.
  </Card>

  <Card title="API-sourced ETL" icon="database" href="/v3/examples/run-api-sourced-etl">
    Build a small ETL pipeline that fetches JSON from a public API, transforms it with pandas, and writes a CSV – all orchestrated by Prefect.
  </Card>
</CardGroup>


# API-sourced ETL
Source: https://docs-3.prefect.io/v3/examples/run-api-sourced-etl

Build a small ETL pipeline that fetches JSON from a public API, transforms it with pandas, and writes a CSV – all orchestrated by Prefect.

{/*
  This page is automatically generated via the `generate_example_pages.py` script. Any changes to this page will be overwritten.
  */}

<a href="https://github.com/PrefectHQ/prefect/blob/main/examples/run_api_sourced_etl.py" target="_blank">View on GitHub</a>

Prefect turns everyday Python into production-grade workflows with **zero boilerplate**.

When you pair Prefect with pandas you get a **versatile ETL toolkit**:

* **Python** supplies a rich ecosystem of connectors and libraries for virtually every data source and destination.
* **pandas** gives you lightning-fast, expressive transforms that turn raw bits into tidy DataFrames.
* **Prefect** wraps the whole thing in battle-tested orchestration: automatic [retries](https://docs.prefect.io/v3/develop/write-tasks#retries), [scheduling](https://docs.prefect.io/v3/deploy/index#workflow-scheduling-and-parametrization), and [observability](https://docs.prefect.io/v3/develop/logging#prefect-loggers) , so you don't have to write reams of defensive code.

The result? You spend your time thinking about *what* you want to build, not *how* to keep it alive. Point this trio at any API, database, or file system and it will move the data where you need it while handling the messy details for you.

In this article you will:

1. **Extract** JSON from the public [Dev.to REST API](https://dev.to/api).
2. **Transform** it into an analytics-friendly pandas `DataFrame`.
3. **Load** the result to a CSV – ready for your BI tool of choice.

This example demonstrates these Prefect features:

* [`@task`](https://docs.prefect.io/v3/develop/write-tasks#write-and-run-tasks) – wrap any function in retries & observability.
* [`log_prints`](https://docs.prefect.io/v3/develop/logging#configure-logging) – surface `print()` logs automatically.
* Automatic [**retries**](https://docs.prefect.io/v3/develop/write-tasks#retries) with back-off, no extra code.

### Rapid analytics from a public API

Your data team wants engagement metrics from Dev.to articles, daily. You need a quick,
reliable pipeline that anyone can run locally and later schedule in Prefect Cloud.

### The Solution

Write three small Python functions (extract, transform, load), add two decorators, and
let Prefect handle [retries](https://docs.prefect.io/v3/develop/write-tasks#retries), [concurrency](https://docs.prefect.io/v3/develop/task-runners#configure-a-task-runner), and [logging](https://docs.prefect.io/v3/develop/logging#prefect-loggers). No framework-specific hoops, just
Python the way you already write it.

*For more background on Prefect's design philosophy, check out our blog post: [Built to Fail: Design Patterns for Resilient Data Pipelines](https://www.prefect.io/blog/built-to-fail-design-patterns-for-resilient-data-pipelines)*

Watch as Prefect orchestrates the ETL pipeline with automatic retries and logging. The flow fetches multiple pages of articles, transforms them into a structured DataFrame, and saves the results to CSV. This pattern is highly adaptable - use it to build pipelines that move data between any sources and destinations:

* APIs → Databases (Postgres, MySQL, etc.)
* APIs → Cloud Storage (S3, GCS, Azure)
* APIs → Data Warehouses (Snowflake, BigQuery, Redshift, etc.)
* And many more combinations

## Code walkthrough

1. **Imports** – Standard libraries for HTTP + pandas.
2. **`fetch_page` task** – Downloads a single page with retries.
3. **`to_dataframe` task** – Normalises JSON to a pandas DataFrame.
4. **`save_csv` task** – Persists the DataFrame and logs a peek.
5. **`etl` flow** – Orchestrates the tasks sequentially for clarity.
6. **Execution** – A friendly `if __name__ == "__main__"` with some basic configurations kicks things off.

```python
from __future__ import annotations

from pathlib import Path
from typing import Any

import httpx
import pandas as pd

from prefect import flow, task

```

***

## Extract – fetch a single page of articles

```python
@task(retries=3, retry_delay_seconds=[2, 5, 15])
def fetch_page(page: int, api_base: str, per_page: int) -> list[dict[str, Any]]:
    """Return a list of article dicts for a given page number."""
    url = f"{api_base}/articles"
    params = {"page": page, "per_page": per_page}
    print(f"Fetching page {page} …")
    response = httpx.get(url, params=params, timeout=30)
    response.raise_for_status()
    return response.json()


```

***

## Transform – convert list\[dict] ➜ pandas DataFrame

```python
@task
def to_dataframe(raw_articles: list[list[dict[str, Any]]]) -> pd.DataFrame:
    """Flatten & normalise JSON into a tidy DataFrame."""
    # Combine pages, then select fields we care about
    records = [article for page in raw_articles for article in page]
    df = pd.json_normalize(records)[
        [
            "id",
            "title",
            "published_at",
            "url",
            "comments_count",
            "positive_reactions_count",
            "tag_list",
            "user.username",
        ]
    ]
    return df


```

***

## Load – save DataFrame to CSV (or print preview)

```python
@task
def save_csv(df: pd.DataFrame, path: Path) -> None:
    """Persist DataFrame to disk then log a preview."""
    df.to_csv(path, index=False)
    print(f"Saved {len(df)} rows ➜ {path}\n\nPreview:\n{df.head()}\n")


```

***

## Flow – orchestrate the ETL with optional concurrency

```python
@flow(name="devto_etl", log_prints=True)
def etl(api_base: str, pages: int, per_page: int, output_file: Path) -> None:
    """Run the end-to-end ETL for *pages* of articles."""

    # Extract – simple loop for clarity
    raw_pages: list[list[dict[str, Any]]] = []
    for page_number in range(1, pages + 1):
        raw_pages.append(fetch_page(page_number, api_base, per_page))

    # Transform
    df = to_dataframe(raw_pages)

    # Load
    save_csv(df, output_file)


```

## Run it!

```bash
python 01_getting_started/03_run_api_sourced_etl.py
```

```python
if __name__ == "__main__":
    # Configuration – tweak to taste
    api_base = "https://dev.to/api"
    pages = 3  # Number of pages to fetch
    per_page = 30  # Articles per page (max 30 per API docs)
    output_file = Path("devto_articles.csv")

    etl(api_base=api_base, pages=pages, per_page=per_page, output_file=output_file)

```

## What just happened?

1. Prefect registered a *flow run* and three *task runs* (`fetch_page`, `to_dataframe`, `save_csv`).
2. Each `fetch_page` call downloaded a page and, if it failed, would automatically retry.
3. The raw JSON pages were combined into a single pandas DataFrame.
4. The CSV was written to disk and a preview printed locally (the flow's `log_prints=True` flag logs messages inside the flow body; prints inside tasks are displayed in the console).
5. You can view run details, timings, and logs in the Prefect UI.

## Key Takeaways

* **Pure Python, powered-up** – Decorators add retries and logging without changing your logic.
* **Observability first** – Each task run (including every page fetch) is logged and can be viewed in the UI if you have a Prefect Cloud account or a local Prefect server running.
* **Composable** – Swap `save_csv` for a database loader or S3 upload with one small change.
* **Reusable** – Import the `etl` flow and run it with different parameters from another flow.

Prefect lets you focus on *data*, not orchestration plumbing – happy ETL-ing! 🎉


# dbt Model Orchestration
Source: https://docs-3.prefect.io/v3/examples/run-dbt-with-prefect

Orchestrate any dbt project with bullet-proof retries, observability, and a single Python file – no YAML or shell scripts required.

{/*
  This page is automatically generated via the `generate_example_pages.py` script. Any changes to this page will be overwritten.
  */}

<a href="https://github.com/PrefectHQ/prefect/blob/main/examples/run_dbt_with_prefect.py" target="_blank">View on GitHub</a>

**Transform unreliable dbt scripts into production-grade data pipelines with enterprise observability, automatic failure recovery, and zero-downtime deployments.**

When you combine Prefect with dbt, you get the **perfect marriage of best-in-class analytics tools**:

* **Python** gives you the flexibility to integrate with any data source, API, or system your analytics need.
* **dbt Core** handles the heavy lifting of SQL transformations, testing, and documentation.
* **Prefect** wraps the entire workflow in battle-tested orchestration: automatic [retries](https://docs.prefect.io/v3/develop/write-tasks#retries), [scheduling](https://docs.prefect.io/v3/deploy/index#workflow-scheduling-and-parametrization), and [observability](https://docs.prefect.io/v3/develop/logging#prefect-loggers).

The result? Your analytics team gets reliable, observable data pipelines that leverage the strengths of both platforms. Point this combo at any warehouse and it will transform your data while providing enterprise-grade workflow management.

> **Note**: This example uses **dbt Core** (the open-source CLI). For dbt Cloud integration, see the [dbt Cloud examples](https://docs.prefect.io/integrations/prefect-dbt#dbt-cloud) in the Prefect documentation.

This example demonstrates these Prefect features:

* [`@task`](https://docs.prefect.io/v3/develop/write-tasks#write-and-run-tasks) – wrap dbt commands in retries & observability.
* [`log_prints`](https://docs.prefect.io/v3/develop/logging#configure-logging) – surface dbt output automatically in Prefect logs.
* Automatic [**retries**](https://docs.prefect.io/v3/develop/write-tasks#retries) with exponential back-off for flaky network connections.
* [**prefect-dbt integration**](https://docs.prefect.io/integrations/prefect-dbt) – native dbt execution with enhanced logging and failure handling.

### The Scenario: Reliable Analytics Workflows

Your analytics team uses dbt to model data in DuckDB for rapid local development and testing, but deploys to Snowflake in production. You need a workflow that:

* Anyone can run locally without complex setup (DuckDB)
* Automatically retries on network failures or temporary dbt errors
* Provides clear logs and observability for debugging
* Can be easily scheduled and deployed to production

### Our Solution

Write three focused Python functions (download project, run dbt commands, orchestrate workflow), add Prefect decorators, and let Prefect handle [retries](https://docs.prefect.io/v3/develop/write-tasks#retries), [logging](https://docs.prefect.io/v3/develop/logging#prefect-loggers), and [scheduling](https://docs.prefect.io/v3/deploy/index#workflow-scheduling-and-parametrization). The entire example is self-contained – no git client or global dbt configuration required.

*For more on integrating Prefect with dbt, see the [Prefect documentation](https://docs.prefect.io/integrations/dbt).*

### Running the example locally

```bash
python 02_flows/prefect_and_dbt.py
```

Watch as Prefect orchestrates the complete dbt lifecycle: downloading the project, running models, executing tests, and materializing results. The flow creates a local DuckDB file you can explore with any SQL tool.

## Code walkthrough

1. **Project Setup** – Download and cache a demo dbt project from GitHub
2. **dbt CLI Wrapper** – Execute dbt commands with automatic retries and logging using prefect-dbt
3. **Orchestration Flow** – Run the complete dbt lifecycle in sequence
4. **Execution** – Self-contained example that works out of the box

```python
import io
import shutil
import urllib.request
import zipfile
from pathlib import Path

from prefect_dbt import PrefectDbtRunner, PrefectDbtSettings

from prefect import flow, task

DEFAULT_REPO_ZIP = (
    "https://github.com/PrefectHQ/examples/archive/refs/heads/examples-markdown.zip"
)

```

***

## Project Setup – download and cache dbt project

To keep this example fully self-contained, we download a demo dbt project
directly from GitHub as a ZIP file. This means users don't need git installed.
[Learn more about tasks in the Prefect documentation](https://docs.prefect.io/v3/develop/write-tasks)

```python
@task(retries=2, retry_delay_seconds=5, log_prints=True)
def build_dbt_project(repo_zip_url: str = DEFAULT_REPO_ZIP) -> Path:
    """Download and extract the demo dbt project, returning its local path.

    To keep the example fully self-contained we grab the GitHub archive as a ZIP
    so users do **not** need `git` installed. The project is extracted from the
    PrefectHQ/examples repository into a sibling directory next to this script
    (`prefect_dbt_project`). If that directory already exists we skip the download
    to speed up subsequent runs.
    """

    project_dir = Path(__file__).parent / "prefect_dbt_project"
    if project_dir.exists():
        print(f"Using cached dbt project at {project_dir}\n")
        return project_dir

    tmp_extract_base = project_dir.parent / "_tmp_dbt_extract"
    if tmp_extract_base.exists():
        shutil.rmtree(tmp_extract_base)

    print(f"Downloading dbt project archive → {repo_zip_url}\n")
    with urllib.request.urlopen(repo_zip_url) as resp:
        data = resp.read()

    with zipfile.ZipFile(io.BytesIO(data)) as zf:
        zf.extractall(tmp_extract_base)

    # Find the folder containing dbt_project.yml (in resources/prefect_dbt_project)
    candidates = list(
        tmp_extract_base.rglob("**/resources/prefect_dbt_project/dbt_project.yml")
    )
    if not candidates:
        raise ValueError(
            "dbt_project.yml not found in resources/prefect_dbt_project – structure unexpected"
        )

    project_root = candidates[0].parent
    shutil.move(str(project_root), str(project_dir))
    shutil.rmtree(tmp_extract_base)

    print(f"Extracted dbt project to {project_dir}\n")
    return project_dir


```

***

## Create profiles.yml for DuckDB – needed for dbt to work

This task creates a simple profiles.yml file for DuckDB so dbt can connect
to the database. This keeps the example self-contained.

```python
@task(retries=2, retry_delay_seconds=5, log_prints=True)
def create_dbt_profiles(project_dir: Path) -> None:
    """Create a profiles.yml file for DuckDB connection.

    This creates a simple DuckDB profile so dbt can run without external
    database configuration. The profile points to a local DuckDB file.
    This will overwrite any existing profiles.yml to ensure correct formatting.
    """

    profiles_content = f"""demo:
  outputs:
    dev:
      type: duckdb
      path: {project_dir}/demo.duckdb
      threads: 1
  target: dev"""

    profiles_path = project_dir / "profiles.yml"
    with open(profiles_path, "w") as f:
        f.write(profiles_content)

    print(f"Created/updated profiles.yml at {profiles_path}")


```

***

## dbt CLI Wrapper – execute commands with retries and logging using prefect-dbt

This task uses the modern PrefectDbtRunner from prefect-dbt integration which
provides native dbt execution with enhanced logging, failure handling, and
automatic event emission.
[Learn more about retries in the Prefect documentation](https://docs.prefect.io/v3/develop/write-tasks#retries)

```python
@task(retries=2, retry_delay_seconds=5, log_prints=True)
def run_dbt_commands(commands: list[str], project_dir: Path) -> None:
    """Run dbt commands using the modern prefect-dbt integration.

    Uses PrefectDbtRunner which provides enhanced logging, failure handling,
    and automatic Prefect event emission for dbt node status changes.
    This is much more robust than subprocess calls and integrates natively
    with Prefect's observability features.
    """

    print(f"Running dbt commands: {commands}\n")

    # Configure dbt settings to point to our project directory
    settings = PrefectDbtSettings(
        project_dir=str(project_dir),
        profiles_dir=str(project_dir),  # Use project dir for profiles too
    )

    # Create runner and execute commands
    # Use raise_on_failure=False to handle dbt failures more gracefully
    runner = PrefectDbtRunner(settings=settings, raise_on_failure=False)

    for command in commands:
        print(f"Executing: dbt {command}")
        runner.invoke(command.split())
        print(f"Completed: dbt {command}\n")


```

***

## Orchestration Flow – run the complete dbt lifecycle

This flow orchestrates the standard dbt workflow: debug → deps → seed → run → test.
Each step is a separate task run in Prefect, providing granular observability
and automatic retry handling for any step that fails. Now using the flexible
prefect-dbt integration for enhanced dbt execution.
[Learn more about flows in the Prefect documentation](https://docs.prefect.io/v3/develop/write-flows)

```python
@flow(name="dbt_flow", log_prints=True)
def dbt_flow(repo_zip_url: str = DEFAULT_REPO_ZIP) -> None:
    """Run the demo dbt project with Prefect using prefect-dbt integration.

    Steps executed:
    1. Download and setup the dbt project
    2. Create profiles.yml for DuckDB connection
    3. `dbt deps`   – download any package dependencies (none for this tiny demo).
    4. `dbt seed`   – load seed CSVs if they exist (safe to run even when empty).
    5. `dbt run`    – build the model(s) defined under `models/`.
    6. `dbt test`   – execute any tests declared in the project.

    Each step runs as a separate Prefect task with automatic retries and logging.
    Uses the modern prefect-dbt integration for enhanced observability and
    native dbt execution.
    """

    project_dir = build_dbt_project(repo_zip_url)
    create_dbt_profiles(project_dir)

    # dbt commands – executed sequentially using prefect-dbt integration
    run_dbt_commands(["deps"], project_dir)
    run_dbt_commands(["seed"], project_dir)
    run_dbt_commands(["run"], project_dir)
    run_dbt_commands(["test"], project_dir)

    # Let users know where the DuckDB file was written for exploration
    duckdb_path = project_dir / "demo.duckdb"
    print(f"\nDone! DuckDB file located at: {duckdb_path.resolve()}")


```

### What Just Happened?

Here's the sequence of events when you run this flow:

1. **Project Download** – Prefect registered a task run to download and extract the dbt project from GitHub (with automatic caching for subsequent runs).
2. **dbt Lifecycle** – Five separate task runs executed the standard dbt workflow: `deps`, `seed`, `run`, and `test`.
3. **Native dbt Integration** – Each dbt command used the `DbtCoreOperation` for enhanced logging, failure handling, and automatic event emission.
4. **Automatic Retries** – Each dbt command would automatically retry on failure (network issues, temporary dbt errors, etc.).
5. **Centralized Logging** – All dbt output streamed directly to Prefect logs with proper log level mapping.
6. **Event Emission** – Prefect automatically emitted events for each dbt node execution, enabling advanced monitoring and alerting.
7. **Local Results** – A DuckDB file appeared at `prefect_dbt_project/demo.duckdb` ready for analysis.

**Prefect + prefect-dbt transformed a series of shell commands into a resilient, observable workflow** – no YAML files, no cron jobs, just Python with enterprise-grade dbt integration.

### Why This Matters

Traditional dbt orchestration often involves brittle shell scripts, complex YAML configurations, or heavyweight workflow tools. Prefect with the prefect-dbt integration gives you **enterprise-grade orchestration with zero operational overhead**:

* **Reliability**: Automatic retries with exponential backoff handle transient failures
* **Native Integration**: DbtCoreOperation provides enhanced logging, failure handling, and event emission
* **Observability**: Every dbt command and node is logged, timed, and searchable in the Prefect UI with proper log level mapping
* **Event-Driven**: Automatic Prefect events for dbt node status changes enable advanced monitoring and alerting
* **Portability**: The same Python file runs locally, in CI/CD, and in production
* **Composability**: Easily extend this flow with data quality checks, Slack alerts, or downstream dependencies

This pattern scales from prototype analytics to production data platforms. Whether you're running dbt against DuckDB for rapid local iteration or Snowflake for enterprise analytics, Prefect ensures your workflows are reliable, observable, and maintainable.

To learn more about orchestrating analytics workflows with Prefect, check out:

* [prefect-dbt integration guide](https://docs.prefect.io/integrations/prefect-dbt)
* [Task configuration and retries](https://docs.prefect.io/v3/develop/write-tasks#retries)
* [Workflow scheduling and deployment](https://docs.prefect.io/v3/deploy/index#workflow-scheduling-and-parametrization)

```python
if __name__ == "__main__":
    dbt_flow()

```


# Simple web scraper
Source: https://docs-3.prefect.io/v3/examples/simple-web-scraper

Learn how to scrape article content from web pages with Prefect tasks, retries, and automatic logging.

{/*
  This page is automatically generated via the `generate_example_pages.py` script. Any changes to this page will be overwritten.
  */}

<a href="https://github.com/PrefectHQ/prefect/blob/main/examples/simple_web_scraper.py" target="_blank">View on GitHub</a>

This example shows how Prefect enhances regular Python code without getting in its way.
You'll write code exactly as you normally would, and Prefect's decorators add production-ready
features with zero boilerplate.

In this example you will:

1. Write regular Python functions for web scraping
2. Add production features ([retries](https://docs.prefect.io/v3/develop/write-tasks#retries), [logging](https://docs.prefect.io/v3/develop/logging#configure-logging)) with just two decorators:
   * `@task` - Turn any function into a [retryable, observable unit](https://docs.prefect.io/v3/develop/write-tasks#write-and-run-tasks)
   * `@flow` - Compose tasks into a [reliable pipeline](https://docs.prefect.io/v3/develop/write-flows#write-and-run-flows)
3. Keep your code clean and Pythonic - no framework-specific patterns needed

## The Power of Regular Python

Notice how the code below is just standard Python with two decorators. You could remove
the decorators and the code would still work - Prefect just makes it more resilient.

* Regular Python functions? ✓
* Standard libraries (requests, BeautifulSoup)? ✓
* Normal control flow (if/else, loops)? ✓
* Prefect's magic? Just two decorators! ✓

```python
from __future__ import annotations

import requests
from bs4 import BeautifulSoup

from prefect import flow, task

```

## Defining tasks

We separate network IO from parsing so both pieces can be retried or cached independently.

```python
@task(retries=3, retry_delay_seconds=2)
def fetch_html(url: str) -> str:
    """Download page HTML (with retries).

    This is just a regular requests call - Prefect adds retry logic
    without changing how we write the code."""
    print(f"Fetching {url} …")
    response = requests.get(url, timeout=10)
    response.raise_for_status()
    return response.text


@task
def parse_article(html: str) -> str:
    """Extract article text, skipping code blocks.

    Regular BeautifulSoup parsing with standard Python string operations.
    Prefect adds observability without changing the logic."""
    soup = BeautifulSoup(html, "html.parser")

    # Find main content - just regular BeautifulSoup
    article = soup.find("article") or soup.find("main")
    if not article:
        return ""

    # Standard Python all the way
    for code in article.find_all(["pre", "code"]):
        code.decompose()

    content = []
    for elem in article.find_all(["h1", "h2", "h3", "p", "ul", "ol", "li"]):
        text = elem.get_text().strip()
        if not text:
            continue

        if elem.name.startswith("h"):
            content.extend(["\n" + "=" * 80, text.upper(), "=" * 80 + "\n"])
        else:
            content.extend([text, ""])

    return "\n".join(content)


```

## Defining a flow

`@flow` elevates a function to a *flow* – the orchestration nucleus that can call
tasks, other flows, and any Python you need. We enable `log_prints=True` so each
`print()` surfaces in Prefect Cloud or the local API.

```python
@flow(log_prints=True)
def scrape(urls: list[str] | None = None) -> None:
    """Scrape and print article content from URLs.

    A regular Python function that composes our tasks together.
    Prefect adds logging and dependency management automatically."""

    if urls:
        for url in urls:
            content = parse_article(fetch_html(url))
            print(content if content else "No article content found.")


```

## Run it!

Feel free to tweak the URL list or the regex and re-run. Prefect hot-reloads your
code instantly – no container builds required.

```python
if __name__ == "__main__":
    urls = [
        "https://www.prefect.io/blog/airflow-to-prefect-why-modern-teams-choose-prefect"
    ]
    scrape(urls=urls)

```

## What just happened?

When you ran this script, Prefect did a few things behind the scenes:

1. Turned each decorated function into a *task run* or *flow run* with structured state.
2. Applied retry logic to the network call – a flaky connection would auto-retry up to 3 times.
3. Captured all `print()` statements so you can view them in the Prefect UI or logs.
4. Passed the HTML between tasks **in memory** – no external storage required.

Yet the code itself is standard Python. You could copy-paste the body of `fetch_html` or
`parse_article` into a notebook and they'd work exactly the same.

## Key Takeaways

* **Less boilerplate, more Python** – You focus on the scraping logic, Prefect adds production features.
* **Observability out of the box** – Every run is tracked, making debugging and monitoring trivial.
* **Portability** – The same script runs on your laptop today and on Kubernetes tomorrow.
* **Reliability** – Retries, timeouts, and state management are just one decorator away.

Happy scraping – and happy orchestrating! 🎉


# Introduction
Source: https://docs-3.prefect.io/v3/get-started/index



Prefect is an open-source orchestration engine that turns your Python functions into production-grade data pipelines with minimal friction. You can build and schedule workflows in pure Python—no DSLs or complex config files—and run them anywhere you can run Python. Prefect handles the heavy lifting for you out of the box: automatic state tracking, failure handling, real-time monitoring, and more.

### Essential features

<div className="t-full-width">
  | Feature                           | Description                                                                                                                                                                                                                                                                         |
  | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | **Pythonic**                      | Write workflows in native Python—no DSLs, YAML, or special syntax. Full support for type hints, async/await, and modern Python patterns. Use your existing IDE, debugger, and testing tools.                                                                                        |
  | **State & Recovery**              | Robust state management that tracks success, failure, and retry states. Resume interrupted runs from the last successful point, and cache expensive computations to avoid unnecessary rework.                                                                                       |
  | **Flexible & Portable Execution** | Start flows locally for easy development, then deploy them anywhere—from a single process to containers, Kubernetes, or cloud services—without locking into a vendor. Infrastructure is defined by code (not just configuration), making it simple to scale or change environments. |
  | **Event-Driven**                  | Trigger flows on schedules, external events, or via API. Pause flows for human intervention or approval. Chain flows together based on states, conditions, or any custom logic.                                                                                                     |
  | **Dynamic Runtime**               | Create tasks dynamically at runtime based on actual data or conditions. Easily spawn new tasks and branches during execution for truly data-driven workflows.                                                                                                                       |
  | **Modern UI**                     | Real-time flow run monitoring, logging, and state tracking through an intuitive interface. View dependency graphs and DAGs automatically—just run your flow and open the UI.                                                                                                        |
  | **CI/CD First**                   | Test and simulate flows like normal Python code, giving you fast feedback during development. Integrate seamlessly into your existing CI/CD pipeline for automated testing and deployment.                                                                                          |
</div>

## Quickstart

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/v3/get-started/quickstart">
    Quickly create your first deployable workflow tracked by Prefect.
  </Card>

  <Card title="Install Prefect" icon="download" href="/v3/get-started/install">
    Install Prefect and get connected to Prefect Cloud or a self-hosted server.
  </Card>

  <Card title="Upgrade to Prefect 3" icon="sparkles" href="/v3/how-to-guides/migrate/upgrade-to-prefect-3">
    Upgrade from Prefect 2 to Prefect 3 to get the latest features and performance enhancements.
  </Card>
</CardGroup>

## How-to guides

<CardGroup cols={3}>
  <Card title="Build workflows" icon="code" href="/v3/how-to-guides/workflows/write-and-run">
    Learn how to write and customize your Prefect workflows with tasks and flows.
  </Card>

  <Card title="Deploy workflows" icon="rocket" href="/v3/how-to-guides/deployments/create-deployments">
    Deploy and manage your workflows as Prefect deployments.
  </Card>

  <Card title="Configure infrastructure" icon="city" href="/v3/how-to-guides/deployment_infra/managed">
    Deploy your workflows to specific infrastructure platforms.
  </Card>

  <Card title="Set up automations" icon="robot" href="/v3/how-to-guides/automations/creating-automations">
    Work with events, triggers, and automations to build reactive workflows.
  </Card>

  <Card title="Configure Prefect" icon="gears" href="/v3/how-to-guides/configuration/manage-settings">
    Configure your Prefect environment, secrets, and variables.
  </Card>

  <Card title="Use Prefect Cloud" icon="cloud" href="/v3/how-to-guides/cloud/connect-to-cloud">
    Set up and manage your Prefect Cloud account.
  </Card>
</CardGroup>

## Advanced

<CardGroup cols={3}>
  <Card title="Interactive workflows" icon="terminal" href="/v3/advanced/interactive">
    Build interactive workflows that can pause and receive input.
  </Card>

  <Card title="Platform engineering" icon="building" href="/v3/advanced/infrastructure-as-code">
    Use Prefect as a platform for your teams' data pipelines.
  </Card>

  <Card title="Extend Prefect" icon="puzzle-piece" href="/v3/advanced/api-client">
    Extend Prefect with custom blocks and API integrations.
  </Card>
</CardGroup>

## Examples

Check out the gallery of [examples](/v3/examples/index) to see Prefect in action.

## Mini-history of Prefect

**2018-2021:** Our story begins in 2018, when we introduced the idea that workflow orchestration should be Pythonic.
Inspired by distributed tools like Dask, and building on the experience of our founder, Jeremiah Lowin (a PMC member of Apache Airflow), we created a system based on simple Python decorators for tasks and flows.
But what made Prefect truly special was our introduction of task mapping—a feature that would later become foundational to our dynamic execution capabilities (and eventually imitated by other orchestration SDKs).

**2022:** Prefect's 2.0 release became inevitable once we recognized that real-world workflows don't always fit into neat, pre-planned DAG structures: sometimes you need to update a job definition based on runtime information, for example by skipping a branch of your workflow.
So we removed a key constraint that workflows be written explicitly as DAGs, fully embracing native Python control flow—if/else conditionals, while loops-everything that makes Python…Python.

**2023-present:** With our release of Prefect 3.0 in 2024, we fully embraced these dynamic patterns by open-sourcing our events and automations backend, allowing users to natively represent event-driven workflows and gain additional observability into their execution.
Prefect 3.0 also unlocked a leap forward in performance, improving the runtime overhead of Prefect by up to 90%.

## Join our community

Join Prefect's vibrant [community of nearly 30,000 engineers](/contribute/index/) to learn with others and share your knowledge!

## LLM-friendly docs

### MCP server

Connect to `https://docs.prefect.io/mcp` in Claude Desktop, Cursor, or VS Code for AI-powered documentation search and assistance.

### Plain text formats

The docs are also available in [llms.txt format](https://llmstxt.org/):

* [llms.txt](https://docs.prefect.io/llms.txt) - A sitemap listing all documentation pages
* [llms-full.txt](https://docs.prefect.io/llms-full.txt) - The entire documentation in one file (may exceed context windows)

Any page can be accessed as markdown by appending `.md` to the URL. For example, this page becomes `https://docs.prefect.io/v3/get-started.md`.

You can also copy any page as markdown by pressing "Cmd+C" (or "Ctrl+C" on Windows) on your keyboard.


# Install Prefect
Source: https://docs-3.prefect.io/v3/get-started/install



Prefect is published as a Python package, which requires Python 3.9 or newer. We recommend installing Prefect in a Python virtual environment.

To install Prefect with `pip`, run:

<CodeGroup>
  ```bash pip
  pip install -U prefect
  ```

  ```bash uv
  uv pip install -U prefect
  ```
</CodeGroup>

To confirm that Prefect was installed successfully, run:

```bash
prefect version
```

You should see output similar to:

```bash
Version:             3.1.10
API version:         0.8.4
Python version:      3.12.2
Git commit:          d6bdb075
Built:               Thu, Apr 11, 2024 6:58 PM
OS/Arch:             darwin/arm64
Profile:              local
Server type:         ephemeral
Server:
  Database:          sqlite
  SQLite version:    3.45.2
```

<Accordion title="More commands for power users">
  ### If you use `uv`

  start an `ipython` shell with python 3.12 and `prefect` installed:

  ```bash
  uvx --python 3.12 --with prefect ipython
  ```

  install prefect into a `uv` virtual environment:

  ```bash
  uv venv --python 3.12 && source .venv/bin/activate
  uv pip install -U prefect
  ```

  add prefect to an active project:

  ```bash
  uv add prefect
  ```

  run prefect server in an ephemeral python environment with `uvx`:

  ```bash
  uvx prefect server start
  ```

  ### If you use `docker`

  run prefect server in a container port-forwarded to your local machine's 4200 port:

  ```bash
  docker run -d -p 4200:4200 prefecthq/prefect:3-latest -- prefect server start --host 0.0.0.0
  ```
</Accordion>

## Windows installation

You can install and run Prefect via Windows PowerShell, the Windows Command Prompt, or [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html). After installation, you may need to manually add the Python local packages `Scripts` folder to your `Path` environment variable.

The `Scripts` folder path looks something like:

```bash
C:\Users\MyUserNameHere\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\LocalCache\local-packages\Python311\Scripts
```

Review the `pip install` output messages for the `Scripts` folder path on your system.

## Minimal Prefect installation

The `prefect-client` library is a minimal installation of Prefect designed for interacting with Prefect Cloud or a remote self-hosted Prefect server instance.

`prefect-client` enables a subset of Prefect's capabilities with a smaller installation size, making it ideal for use in lightweight, resource-constrained, or ephemeral environments.
It omits all CLI and server components found in the `prefect` library.

To install the latest release of `prefect-client`, run:

```bash
pip install -U prefect-client
```

## Next steps

You also need an API server, either:

* [Prefect Cloud](/v3/how-to-guides/cloud/connect-to-cloud/), a managed solution that provides strong scaling, performance, and security, or
* [Self-hosted Prefect server](/v3/concepts/server/), an API server that you run on your own infrastructure where you are responsible for scaling and any authentication and authorization.

Now that you have Prefect installed, go through the [quickstart](/v3/get-started/quickstart/) to try it out.

See the full history of [Prefect releases](https://github.com/PrefectHQ/prefect/releases) on GitHub.

See our [Contributing docs](/contribute/dev-contribute/) for instructions on installing Prefect for development.


# Quickstart
Source: https://docs-3.prefect.io/v3/get-started/quickstart

Create your first workflow

Prefect is a workflow orchestration tool that helps you build, deploy, run, and monitor data pipelines. It makes complex workflows reliable by tracking dependencies and handling failures gracefully.

In this tutorial, you'll deploy your first workflow to Prefect -- by specifying what code should run, where it should run, and when it should run. Choose your preferred approach below:

<Tabs>
  <Tab title="Cloud">
    <Steps>
      <Step title="Create and login to your Prefect Cloud account.">
        Prefect uses a database to store workflow metadata.
        For the ease of getting started, we'll use one hosted on Prefect Cloud. To create an account, we need to install `prefect-cloud`. We'll leverage `uv`, a modern Python package manager, to do this. Run the following commands in your terminal, after which you'll be prompted in your browser to create or login to your free Prefect Cloud account.

        ```bash
        curl -LsSf https://astral.sh/uv/install.sh | sh # Install `uv`.
        uvx prefect-cloud login # Installs `prefect-cloud` into a temporary virtual env.
        ```
      </Step>

      <Step title="What code should run?">
        Let's start with a boring Python script that fetches a list of customer ids and processes them all in parallel. You can find this code and other examples hosted in our [quickstart repository](https://github.com/PrefectHQ/quickstart/blob/main/01_getting_started.py).

        ```python 01_getting_started.py [expandable]
        from prefect import flow, task
        import random

        @task
        def get_customer_ids() -> list[str]:
            # Fetch customer IDs from a database or API
            return [f"customer{n}" for n in random.choices(range(100), k=10)]

        @task
        def process_customer(customer_id: str) -> str:
            # Process a single customer
            return f"Processed {customer_id}"

        @flow
        def main() -> list[str]:
            customer_ids = get_customer_ids()
            # Map the process_customer task across all customer IDs
            results = process_customer.map(customer_ids)
            return results


        if __name__ == "__main__":
            main()
        ```

        This looks like the ordinary Python you'd write, except there is:

        * a `@flow` decorator on the script's entrypoint.
        * a `@task` decorator on each function called within the flow.

        When you run this `flow`, Prefect dynamically creates a graph of each `task` and the state of their upstream dependencies. This allows Prefect to execute each `task` in the right order and, in the case of failure, to recover the state of your workflow and resume from its point of failure.

        Let's run this code locally on your computer. To do that, run the following command in your terminal.

        ```bash
        git clone https://github.com/PrefectHQ/quickstart && cd quickstart
        uv run 01_getting_started.py
        ```

        If all went well, you'll see a link to see its execution graph in the Prefect UI followed by a flurry of state changes and logs as Prefect dynamically discovers and executes your workflow.

        ```bash {11} [expandable]
        00:30:53.633 | INFO    | Flow run 'airborne-ringtail' - Beginning flow run 'airborne-ringtail' for flow 'main'
        00:30:53.638 | INFO    | Flow run 'airborne-ringtail' - View at https://app.prefect.cloud/account/...
        00:30:53.685 | INFO    | Task run 'get_customer_ids-136' - Finished in state Completed()
        00:30:54.512 | INFO    | Task run 'process_customer-d9b' - Finished in state Completed()
        00:30:54.518 | INFO    | Task run 'process_customer-113' - Finished in state Completed()
        00:30:54.519 | INFO    | Task run 'process_customer-1c6' - Finished in state Completed()
        00:30:54.519 | INFO    | Task run 'process_customer-30d' - Finished in state Completed()
        00:30:54.520 | INFO    | Task run 'process_customer-eaa' - Finished in state Completed()
        00:30:54.523 | INFO    | Task run 'process_customer-b2b' - Finished in state Completed()
        00:30:54.523 | INFO    | Task run 'process_customer-90a' - Finished in state Completed()
        00:30:54.524 | INFO    | Task run 'process_customer-4af' - Finished in state Completed()
        00:30:54.524 | INFO    | Task run 'process_customer-e66' - Finished in state Completed()
        00:30:54.526 | INFO    | Task run 'process_customer-e7e' - Finished in state Completed()
        00:30:54.527 | INFO    | Flow run 'airborne-ringtail' - Finished in state Completed('All states completed.')
        ```
      </Step>

      <Step title="Where should it run?">
        At this point, you've successfully run a Prefect `flow` locally. Let's get it running off of your machine! Again, for simplicity,
        we'll deploy this workflow to Prefect's Serverless Compute (so we don't have to wrangle any infrastructure). We'll tell Prefect to clone
        `https://github.com/PrefectHQ/quickstart` and invoke `01_getting_started.py:main`.

        ```bash
        uvx prefect-cloud deploy 01_getting_started.py:main \
        --name my_first_deployment \
        --from https://github.com/PrefectHQ/quickstart
        ```

        If all went well, you've created your first deployed workflow.

        Since we now know what code to run and where to run it, this can now be invoked remotely.
        To do that, run the following command and visit the returned link to see the run's status in the Prefect UI:

        ```bash
        uvx prefect-cloud run main/my_first_deployment
        ```

        Congrats! You've just run your first Prefect workflow remotely.
      </Step>

      <Step title="When should it run?">
        Now that you've deployed and run your workflow remotely, you might want to schedule it to run automatically at specific times. Prefect makes this easy with the `prefect-cloud schedule` command.

        Let's schedule our workflow to run every day at 8:00 AM with [`cron`](https://en.wikipedia.org/wiki/Cron) syntax.

        ```bash
        uvx prefect-cloud schedule main/my_first_deployment "0 8 * * *"
        ```

        After running the command, your workflow will automatically execute remotely according to the schedule you've set.

        You can view and manage all your scheduled runs in the Prefect UI.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Open Source">
    <Steps>
      <Step title="Install Prefect and start the server">
        If you're using Prefect Open Source, you'll run a server that backs your workflows. [Install Prefect](/v3/get-started/install) and start your local server:

        ```bash
        prefect server start
        ```

        If you prefer to run your Prefect server in a Docker container, you can use the following command:

        ```bash
        docker run -p 4200:4200 -d --rm prefecthq/prefect:3-python3.12 prefect server start --host 0.0.0.0
        ```

        Both commands start a server at [`http://localhost:4200`](http://localhost:4200). Keep this process running for this tutorial.
      </Step>

      <Step title="What code should run?">
        Let's start with a boring Python script that fetches a list of customer ids and processes them all in parallel. You can find this code and other examples hosted in our [quickstart repository](https://github.com/PrefectHQ/quickstart/blob/main/01_getting_started.py).

        ```python 01_getting_started.py [expandable]
        from prefect import flow, task
        import random

        @task
        def get_customer_ids() -> list[str]:
            # Fetch customer IDs from a database or API
            return [f"customer{n}" for n in random.choices(range(100), k=10)]

        @task
        def process_customer(customer_id: str) -> str:
            # Process a single customer
            return f"Processed {customer_id}"

        @flow
        def main() -> list[str]:
            customer_ids = get_customer_ids()
            # Map the process_customer task across all customer IDs
            results = process_customer.map(customer_ids)
            return results


        if __name__ == "__main__":
            main()
        ```

        This looks like the ordinary Python you'd write, except there is:

        * a `@flow` decorator on the script's entrypoint.
        * a `@task` decorator on each function called within the flow.

        When you run this `flow`, Prefect dynamically creates a graph of each `task` and the state of their upstream dependencies. This allows Prefect to execute each `task` in the right order and, in the case of failure, to recover the state of your workflow and resume from its point of failure.

        Let's run this code locally on your computer. To do that, run the following command in your terminal (in a new terminal window, keeping the server running):

        ```bash
        git clone https://github.com/PrefectHQ/quickstart && cd quickstart
        python 01_getting_started.py
        ```

        If all went well, you'll see a link to see its execution graph in the Prefect UI followed by a flurry of state changes and logs as Prefect dynamically discovers and executes your workflow.
      </Step>

      <Step title="Where should it run?">
        At this point, you've successfully run a Prefect `flow` locally. Let's set up a simple deployment by updating the file to use `.serve()`:

        ```python 01_getting_started.py [expandable]
        from prefect import flow, task
        import random

        @task
        def get_customer_ids() -> list[str]:
            # Fetch customer IDs from a database or API
            return [f"customer{n}" for n in random.choices(range(100), k=10)]

        @task
        def process_customer(customer_id: str) -> str:
            # Process a single customer
            return f"Processed {customer_id}"

        @flow
        def main() -> list[str]:
            customer_ids = get_customer_ids()
            # Map the process_customer task across all customer IDs
            results = process_customer.map(customer_ids)
            return results


        if __name__ == "__main__":
            main.serve(name="my-first-deployment")
        ```

        Now run the updated file:

        ```bash
        python 01_getting_started.py
        ```

        This starts a process listening for scheduled runs. You can now trigger the flow from the Prefect UI or programmatically.
      </Step>

      <Step title="When should it run?">
        Now let's schedule your workflow to run automatically. Update the file to add a cron schedule:

        ```python 01_getting_started.py [expandable]
        from prefect import flow, task
        import random

        @task
        def get_customer_ids() -> list[str]:
            # Fetch customer IDs from a database or API
            return [f"customer{n}" for n in random.choices(range(100), k=10)]

        @task
        def process_customer(customer_id: str) -> str:
            # Process a single customer
            return f"Processed {customer_id}"

        @flow
        def main() -> list[str]:
            customer_ids = get_customer_ids()
            # Map the process_customer task across all customer IDs
            results = process_customer.map(customer_ids)
            return results


        if __name__ == "__main__":
            main.serve(
                name="my-first-deployment",
                cron="0 8 * * *"  # Run every day at 8:00 AM
            )
        ```

        Run the updated file:

        ```bash
        python 01_getting_started.py
        ```

        Your workflow will now run automatically according to the schedule while the serve process is running.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next steps

Now that you've created your first workflow, explore Prefect's features to enable more sophisticated workflows.

* Learn more about [flows](/v3/concepts/flows) and [tasks](/v3/concepts/tasks).
* Learn more about [deployments](/v3/concepts/deployments).
* Learn more about [work pools](/v3/concepts/work-pools).
* Learn how to [run work concurrently](/v3/how-to-guides/workflows/run-work-concurrently).


# How to access deployment and flow run parameters
Source: https://docs-3.prefect.io/v3/how-to-guides/automations/access-parameters-in-templates

Learn how to access deployment and flow run parameters in templates

Many of the parameters of automation actions can be defined with [Jinja2 templates](/v3/concepts/automations#templating-with-jinja). These templates have access to objects related to the event that triggered your automation, including the deployment and flow run of that event (if applicable). Here we'll explore an example illustrating how to access their parameters in an automation action.

Let's start with two flows, `alpha` and `beta`:

```python
from prefect import flow


@flow
def alpha(name: str, value: int):
    print(name, value)


@flow
def beta(name: str, value: int, another: float):
    print(name, value, another)
```

Once a run of `alpha` completes, we'll automate running a flow of `beta` with the same parameters:

{/* pmd-metadata: notest */}

```python
from datetime import timedelta

from prefect.automations import (
    Automation,
    EventTrigger,
    Posture,
    ResourceSpecification,
    RunDeployment,
)

from .flows import alpha, beta

# Note: deploy these flows in the way you best see fit for your environment
alpha.deploy(
    name="alpha",
    work_pool_name="my-work-pool",
    image="prefecthq/prefect-client:3-latest",
)
beta_deployment_id = beta.deploy(
    name="beta",
    work_pool_name="my-work-pool",
    image="prefecthq/prefect-client:3-latest",
)

automation = Automation(
    name="Passing parameters",
    trigger=EventTrigger(
        # Here we're matching on every completion of the `alpha` flow
        expect={"prefect.flow-run.Completed"},
        match_related=ResourceSpecification(
            {
                "prefect.resource.role": "flow",
                "prefect.resource.name": "alpha"
            }
        ),
        # And we'll react to each event immediately and individually
        posture=Posture.Reactive,
        threshold=1,
        within=timedelta(0),
    ),
    actions=[
        RunDeployment(
            # We will be selecting a specific deployment (rather than attempting to
            # infer it from the event)
            source="selected",
            # The deployment we want to run is the `beta` deployment we created above
            deployment_id=beta_deployment_id,
            parameters={
                # For the "name" and "value" parameters, we tell Prefect we're using a
                # Jinja2 template by creating a nested dictionary with the special
                # `__prefect_kind` key set to "jinja".  Then we supply the `template`
                # value with any valid Jinja2 template.  This step may also be done
                # in the Prefect UI by selecting "Use Jinja input" for the parameters
                # you want to template.
                #
                # The "{{ flow_run }}" variable here is a special shortcut that gives us
                # access to the `FlowRun` object associated with this event.  There are
                # also variables like "{{ deployment }}", "{{ flow }}",
                # "{{ work_pool }}" and so on.
                #
                # In this case, the {{ flow_run }} represent the run of `alpha` that
                # emitted the `prefect.flow-run.Completed` event that triggered this
                # automation.
                "name": {
                    "template": "{{ flow_run.parameters['name'] }}",
                    "__prefect_kind": "jinja",
                },
                "value": {
                    "template": "{{ flow_run.parameters['value'] }}",
                    "__prefect_kind": "jinja",
                },
                # You can also just pass literal parameters
                "another": 1.2345,
            },
        )
    ],
).create()
```

If you are defining your automation in the Prefect web UI, you can switch the parameter input to support Jinja2 values:

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-use-jinja-input.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=9609c36afc9d6d7800f75197e07767e8" alt="Use Jinja input for an action" data-og-width="732" width="732" data-og-height="753" height="753" data-path="v3/img/guides/automation-use-jinja-input.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-use-jinja-input.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=a691e383832856eb40cc1101130cd1eb 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-use-jinja-input.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=3db43f776c1bfe800573e0cbcff3397a 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-use-jinja-input.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=af932dec4e8ab1cf04c68ff10e9b3dc2 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-use-jinja-input.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=e7632848927fa34d69c864ddd3ea8c48 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-use-jinja-input.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=4d76f281b0729de09ccca098d97846c6 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-use-jinja-input.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=8b41f48b4c5c9aef1ebd98f0842850ed 2500w" data-optimize="true" data-opv="2" />


# How to chain deployments with events
Source: https://docs-3.prefect.io/v3/how-to-guides/automations/chaining-deployments-with-events

Learn how to establish event-based dependencies between individual workflows.

This example shows how to use a trigger to schedule a run of downstream deployment when a run of an upstream deployment completes.

## Define an upstream and downstream deployment

```python event_driven_deployments.py
from prefect import flow, serve
from prefect.events import DeploymentEventTrigger


@flow(log_prints=True)
def upstream_flow():
    print("upstream flow")


@flow(log_prints=True)
def downstream_flow():
    print("downstream flow")


if __name__ == "__main__":
    upstream_deployment = upstream_flow.to_deployment(name="upstream_deployment")
    downstream_deployment = downstream_flow.to_deployment(
        name="downstream_deployment",
        triggers=[
            DeploymentEventTrigger(
                expect={"prefect.flow-run.Completed"},
                match_related={"prefect.resource.name": "upstream_deployment"},
            )
        ],
    )

    serve(upstream_deployment, downstream_deployment)
```

## Test it out

First, start the `serve` process to listen for scheduled deployments runs:

```bash
python event_driven_deployments.py
```

Now, run the upstream deployment and see the downstream deployment kick off after it completes:

```bash
prefect deployment run upstream-flow/upstream_deployment
```

<Tip>
  **Check the event feed**

  You can inspect raw events in the event feed in the UI to see what related resources are available to match against.

  For example, the following `prefect.flow-run.Completed` event's related resources include:

  ```json
  {
     "related": [
      {
        "prefect.resource.id": "prefect.flow.10e099ec-8358-4146-b188-be68027ee58f",
        "prefect.resource.role": "flow",
        "prefect.resource.name": "upstream-flow"
      },
      {
        "prefect.resource.id": "prefect.deployment.be777bbd-4b15-49f3-bc1f-4d109374cee2",
        "prefect.resource.role": "deployment",
        "prefect.resource.name": "upstream_deployment"
      },
      {
        "prefect.resource.id": "prefect-cloud.user.80546602-9f31-4396-ab4b-e873a5377feb",
        "prefect.resource.role": "creator",
        "prefect.resource.name": "stoat"
      }
    ]
  }
  ```
</Tip>


# How to create automations
Source: https://docs-3.prefect.io/v3/how-to-guides/automations/creating-automations

Learn how to define automations that trigger actions based on events.

export const automations = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/automation",
  api: "https://app.prefect.cloud/api/docs#tag/Automations",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/automation"
};

export const COMBINED = ({name, hrefTF, hrefAPI, hrefCLI}) => <p>You can manage {name} with the <a href={hrefCLI}>Prefect CLI</a>, <a href={hrefTF}>Terraform provider</a>, or <a href={hrefAPI}>Prefect API</a>.</p>;

## Create an automation

On the **Automations** page, select the **+** icon to create a new automation. You'll be prompted to configure:

* A [trigger](#triggers) condition that causes the automation to execute.
* One or more [actions](#actions) carried out by the automation.
* [Details](#details) about the automation, such as a name and description.

<COMBINED name="automations" hrefTF={automations.tf} hrefAPI={automations.api} hrefCLI={automations.cli} />

### Create automations with the CLI

You can create automations from YAML or JSON files using the Prefect CLI:

```bash
# Create from a YAML file
prefect automation create --from-file automation.yaml
# or use the short form
prefect automation create -f automation.yaml

# Create from a JSON file  
prefect automation create --from-file automation.json

# Create from a JSON string
prefect automation create --from-json '{"name": "my-automation", "trigger": {...}, "actions": [...]}'
# or use the short form
prefect automation create -j '{"name": "my-automation", "trigger": {...}, "actions": [...]}'
```

#### Single automation example

Here's an example YAML file that creates an automation to cancel long-running flows:

```yaml
name: Cancel Long Running Flows
description: Cancels flows running longer than 5 minutes
enabled: true
trigger:
  type: event
  posture: Proactive
  expect:
    - prefect.flow-run.Completed
  threshold: 1
  within: 300  # 5 minutes
  for_each:
    - prefect.resource.id
actions:
  - type: cancel-flow-run
```

#### Multiple automations example

You can also create multiple automations at once by using the `automations:` key. If any automation fails to create, the command will continue with the remaining automations and report both successes and failures:

```yaml
automations:
  - name: Cancel Long Running Flows
    description: Cancels flows running longer than 30 minutes
    enabled: true
    trigger:
      type: event
      posture: Reactive
      expect:
        - prefect.flow-run.Running
      threshold: 1
      for_each:
        - prefect.resource.id
    actions:
      - type: cancel-flow-run
        
  - name: Notify on Flow Failure
    description: Send notification when flows fail
    enabled: true
    trigger:
      type: event
      posture: Reactive
      expect:
        - prefect.flow-run.Failed
      threshold: 1
    actions:
      - type: send-notification
        subject: "Flow Failed: {{ event.resource.name }}"
        body: "Flow run {{ event.resource.name }} has failed."
```

Or as a JSON array:

```json
[
  {
    "name": "First Automation",
    "trigger": {...},
    "actions": [...]
  },
  {
    "name": "Second Automation", 
    "trigger": {...},
    "actions": [...]
  }
]
```

### Create automations with the Python SDK

You can create and access any automation with the Python SDK's `Automation` class and its methods.

```python
from prefect.automations import Automation
from prefect.events.schemas.automations import EventTrigger
from prefect.events.actions import CancelFlowRun

# creating an automation
automation = Automation(
    name="woodchonk",
    trigger=EventTrigger(
        expect={"animal.walked"},
        match={
            "genus": "Marmota",
            "species": "monax",
        },
        posture="Reactive",
        threshold=3,
    ),
    actions=[CancelFlowRun()],
).create()

# reading the automation
automation = Automation.read(id=automation.id)
# or by name
automation = Automation.read(name="woodchonk")
```


# How to create deployment triggers
Source: https://docs-3.prefect.io/v3/how-to-guides/automations/creating-deployment-triggers

Learn how to define automations that trigger deployment runs based on events.

## Creating deployment triggers

To enable the simple configuration of event-driven deployments, Prefect provides **deployment triggers**—a shorthand for
creating automations that are linked to specific deployments to run them based on the presence or absence of events.

<Info>
  Deployment triggers are a special case of automations where the configured action is always running a deployment.
</Info>

Trigger definitions for deployments are supported in `prefect.yaml`, `.serve`, and `.deploy`. At deployment time,
specified trigger definitions create linked automations triggered by events matching your chosen
[grammar](/v3/concepts/events/#event-grammar). Each trigger definition may include a [jinja template](https://en.wikipedia.org/wiki/Jinja_\(template_engine\))
to render the triggering `event` as the `parameters` of your  deployment's flow run.

### Define triggers in `prefect.yaml`

You can include a list of triggers on any deployment in a `prefect.yaml` file:

```yaml
deployments:
  - name: my-deployment
    entrypoint: path/to/flow.py:decorated_fn
    work_pool:
      name: my-work-pool
    triggers:
      - type: event
        enabled: true
        match:
          prefect.resource.id: my.external.resource
        expect:
          - external.resource.pinged
        parameters:
          param_1: "{{ event }}"
```

### Scheduling delayed deployment runs

You can configure deployment triggers to run after a specified delay using the `schedule_after` field. This is useful for implementing opt-out workflows or providing review windows before automated actions:

```yaml
deployments:
  - name: campaign-execution
    entrypoint: path/to/campaign.py:execute_campaign
    work_pool:
      name: my-work-pool
    triggers:
      - type: event
        enabled: true
        match:
          prefect.resource.id: marketing.campaign
        expect:
          - campaign.proposal.created
        schedule_after: "PT2H"  # Wait 2 hours before execution
        parameters:
          campaign_id: "{{ event.resource.id }}"
```

The `schedule_after` field accepts:

* **ISO 8601 durations** (e.g., "PT2H" for 2 hours, "PT30M" for 30 minutes)
* **Seconds as integer** (e.g., 7200 for 2 hours)
* **Python timedelta objects** in code

This deployment creates a flow run when an `external.resource.pinged` event *and* an `external.resource.replied`
event have been seen from `my.external.resource`:

```yaml
deployments:
  - name: my-deployment
    entrypoint: path/to/flow.py:decorated_fn
    work_pool:
      name: my-work-pool
    triggers:
      - type: compound
        require: all
        parameters:
          param_1: "{{ event }}"
        schedule_after: "PT1H"  # Wait 1 hour before running
        triggers:
          - type: event
            match:
              prefect.resource.id: my.external.resource
            expect:
              - external.resource.pinged
          - type: event
            match:
              prefect.resource.id: my.external.resource
            expect:
              - external.resource.replied
```

### Define deployment triggers using Terraform

You can also set up a deployment trigger via Terraform resources, specifically via the `prefect_automation` [resource](https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/automation).

```hcl
resource "prefect_deployment" "my_deployment" {
  name            = "my-deployment"
  work_pool_name  = "my-work-pool"
  work_queue_name = "default"
  entrypoint      = "path/to/flow.py:decorated_fn"
}

resource "prefect_automation" "event_trigger" {
  name = "my-automation"
  trigger = {
    event = {
      posture   = "Reactive"
      expect    = ["external.resource.pinged"]
      threshold = 1
      within    = 0
    }
  }
  actions = [
    {
      type          = "run-deployment"
      source        = "selected"
      deployment_id = prefect_deployment.my_deployment.id
      parameters = jsonencode({
        "param_1" : "{{ event }}"
      })
    },
  ]
}

```

### Define triggers in `.serve` and `.deploy`

To create deployments with triggers in Python, the trigger types `DeploymentEventTrigger`,
`DeploymentMetricTrigger`, `DeploymentCompoundTrigger`, and `DeploymentSequenceTrigger` can be imported
from `prefect.events`:

```python
from datetime import timedelta
from prefect import flow
from prefect.events import DeploymentEventTrigger


@flow(log_prints=True)
def decorated_fn(param_1: str):
    print(param_1)


if __name__=="__main__":
    decorated_fn.serve(
        name="my-deployment",
        triggers=[
            DeploymentEventTrigger(
                enabled=True,
                match={"prefect.resource.id": "my.external.resource"},
                expect=["external.resource.pinged"],
                schedule_after=timedelta(hours=1),  # Wait 1 hour before running
                parameters={
                    "param_1": "{{ event }}",
                },
            )
        ],
    )
```

As with prior examples, you must supply composite triggers with a list of underlying triggers:

```python
from datetime import timedelta
from prefect import flow
from prefect.events import DeploymentCompoundTrigger


@flow(log_prints=True)
def decorated_fn(param_1: str):
    print(param_1)


if __name__=="__main__":
    decorated_fn.deploy(
        name="my-deployment",
        image="my-image-registry/my-image:my-tag",
        triggers=[
            DeploymentCompoundTrigger(
                enabled=True,
                name="my-compound-trigger",
                require="all",
                schedule_after=timedelta(minutes=30),  # Wait 30 minutes
                triggers=[
                    {
                      "type": "event",
                      "match": {"prefect.resource.id": "my.external.resource"},
                      "expect": ["external.resource.pinged"],
                    },
                    {
                      "type": "event",
                      "match": {"prefect.resource.id": "my.external.resource"},
                      "expect": ["external.resource.replied"],
                    },
                ],
                parameters={
                    "param_1": "{{ event }}",
                },
            )
        ],
        work_pool_name="my-work-pool",
    )
```

### Pass triggers to `prefect deploy`

You can pass one or more `--trigger` arguments to `prefect deploy` as either a JSON string or a
path to a `.yaml` or `.json` file.

```bash
# Pass a trigger as a JSON string
prefect deploy -n test-deployment \
  --trigger '{
    "enabled": true,
    "match": {
      "prefect.resource.id": "prefect.flow-run.*"
    },
    "expect": ["prefect.flow-run.Completed"]
  }'

# Pass a trigger using a JSON/YAML file
prefect deploy -n test-deployment --trigger triggers.yaml
prefect deploy -n test-deployment --trigger my_stuff/triggers.json
```

For example, a `triggers.yaml` file could have many triggers defined:

```yaml
triggers:
  - enabled: true
    match:
      prefect.resource.id: my.external.resource
    expect:
      - external.resource.pinged
    parameters:
      param_1: "{{ event }}"
  - enabled: true
    match:
      prefect.resource.id: my.other.external.resource
    expect:
      - some.other.event
    parameters:
      param_1: "{{ event }}"
```

Both of the above triggers would be attached to `test-deployment` after running `prefect deploy`.

<Warning>
  **Triggers passed to `prefect deploy` will override any triggers defined in `prefect.yaml`**

  While you can define triggers in `prefect.yaml` for a given deployment, triggers passed to `prefect deploy`
  take precedence over those defined in `prefect.yaml`.
</Warning>

Note that deployment triggers contribute to the total number of automations in your workspace.

## Further reading

For more on the concepts behind deployment triggers, see the [Automations concepts](/v3/concepts/automations) page.


# How to connect to Prefect Cloud
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/connect-to-cloud

Configure a local execution environment to access Prefect Cloud.

To create flow runs in a local or remote execution environment, first connect with Prefect Cloud or a
Prefect server as the backend API server.

This involves:

* Configuring the execution environment with the location of the API.
* Authenticating with the API, either by logging in or providing a valid API key (Prefect Cloud only).

## Log into Prefect Cloud from a terminal

Configure a local execution environment to use Prefect Cloud as the API server for flow runs.
You will log in a to Prefect Cloud account from the local environment where you want to run a flow.

### Steps

1. Open a new terminal session.
2. [Install Prefect](/v3/get-started/install/) in the environment where you want to execute flow runs.

```bash
pip install -U prefect
```

3. Use the `prefect cloud login` Prefect CLI command to log into Prefect Cloud from your environment.

```bash
prefect cloud login
```

The `prefect cloud login` command provides an interactive login experience.

```bash
prefect cloud login
```

```bash
? How would you like to authenticate? [Use arrows to move; enter to select]
> Log in with a web browser
    Paste an API key
Paste your authentication key:
? Which workspace would you like to use? [Use arrows to move; enter to select]
> prefect/terry-prefect-workspace
    g-gadflow/g-workspace
Authenticated with Prefect Cloud! Using workspace 'prefect/terry-prefect-workspace'.
```

You can authenticate by manually pasting an [API key](/v3/how-to-guides/cloud/manage-users/api-keys) or through a browser-based approval that auto-generates an API key with a 30-day expiration.

### Change workspaces

To change which workspace to sync with, use the `prefect cloud workspace set`
Prefect CLI command while logged in, passing the account handle and workspace name:

```bash
prefect cloud workspace set --workspace "prefect/my-workspace"
```

If you don't provide a workspace, you will need to select one.

**Workspace Settings** also shows you the `prefect cloud workspace set` Prefect CLI
command to sync a local execution environment with a given workspace.

You may also use the `prefect cloud login` command with the `--workspace` or `-w` option to set the current workspace.

```bash
prefect cloud login --workspace "prefect/my-workspace"
```

## Manually configure Prefect API settings

You can manually configure the `PREFECT_API_URL` setting to specify the Prefect Cloud API.

For Prefect Cloud, configure the `PREFECT_API_URL` and `PREFECT_API_KEY` settings to authenticate
with Prefect Cloud by using an account ID, workspace ID, and API key.

```bash
prefect config set PREFECT_API_URL="https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]"
prefect config set PREFECT_API_KEY="[API-KEY]"
```

<Note>
  **Find account ID and workspace ID in the browser**

  When authenticated to your Prefect Cloud workspace in the browser, you can get the account ID and workspace ID for the `PREFECT_API_URL` string from the page URL.

  For example, if you're on the dashboard page, the URL looks like this:

  [https://app.prefect.cloud/account/\[ACCOUNT-ID\]/workspace/\[WORKSPACE-ID\]/dashboard](https://app.prefect.cloud/account/\[ACCOUNT-ID]/workspace/\[WORKSPACE-ID]/dashboard)
</Note>

The example above configures `PREFECT_API_URL` and `PREFECT_API_KEY` in the default profile.

You can use `prefect profile` CLI commands to create settings profiles for different configurations.
For example, you can configure a "cloud" profile to use the Prefect Cloud API URL and API key;
and another "local" profile for local development using a local Prefect API server started with `prefect server start`.
See [Settings](/v3/develop/settings-and-profiles/) for details.

<Note>
  **Environment variables**

  You can set `PREFECT_API_URL` and `PREFECT_API_KEY` just like any other environment variable.
  Setting these environment variables is a good way to connect to Prefect Cloud in a remote serverless environment.
  See [Overriding defaults with environment variables](/v3/develop/settings-and-profiles/) for more information.
</Note>

## Install requirements in execution environments

In local and remote execution environments, such as VMs and containers, ensure that you've installed any flow
requirements or dependencies before creating a flow run.


# How to create a webhook
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/create-a-webhook

Learn how to setup a webhook in the UI to trigger automations from external events.

This page shows you how to quickly set up a webhook using the Prefect Cloud UI, invoke it, and create an automation based on the received event.

## Trigger an Automation from an External Event

Here's how to set up a webhook and trigger an automation using the Prefect Cloud UI.

### 1. Create a Webhook in the UI

Navigate to the **Webhooks** page in Prefect Cloud and click **Create Webhook**.

You will need to provide a name for your webhook and a Jinja2 template. The template defines how the incoming HTTP request data is transformed into a Prefect event. For example, to capture a model ID and a friendly name from the request body:

```JSON
{
    "event": "model-update",
    "resource": {
        "prefect.resource.id": "product.models.{{ body.model_id}}",
        "prefect.resource.name": "{{ body.friendly_name }}",
        "run_count": "{{body.run_count}}"
    }
}
```

This template will look for `model_id`, `friendly_name`, and `run_count` in the body of the incoming request.

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-simple.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=40ad34d41e5e706a624c91ed79312ff9" alt="Create a webhook in the Prefect Cloud UI, showing the template editor." data-og-width="2450" width="2450" data-og-height="256" height="256" data-path="v3/img/guides/webhook-simple.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-simple.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=5a593bafdf9e60610c74d6dec4387552 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-simple.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=f4525de4ea0b4f8ed7a9390233c55309 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-simple.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=2f7fc796fd84aa873cff27d2d3a91b94 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-simple.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=3c8492661c7bf27debf39e3dbd0fbf92 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-simple.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=94d4e9acd11376347b62f380d90b33e9 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-simple.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=eae6180245a95cd9cf1e0e9baaac2f95 2500w" data-optimize="true" data-opv="2" />

After saving, Prefect Cloud will provide you with a unique URL for your webhook.

### 2. Invoke the Webhook Endpoint

Use any HTTP client to send a `POST` request to the unique URL provided for your webhook. Include the data you want to pass in the request body. For the example template above:

```console
curl -X POST https://api.prefect.cloud/hooks/YOUR_UNIQUE_WEBHOOK_ID \
  -d "model_id=my_model_123" \
  -d "friendly_name=My Awesome Model" \
  -d "run_count=15"
```

Replace `YOUR_UNIQUE_WEBHOOK_ID` with your actual webhook ID.

### 3. Observe the Event in Prefect Cloud

After invoking the webhook, navigate to the **Event Feed** in Prefect Cloud. You should see a new event corresponding to your webhook invocation.

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-created.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=1a348eaf056244f5fe2d36a4bfc55417" alt="Event feed in Prefect Cloud showing a newly created event from a webhook." data-og-width="740" width="740" data-og-height="354" height="354" data-path="v3/img/guides/webhook-created.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-created.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6e54ff9c06d453d0f6f29c0b21b3ee41 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-created.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=0b0f0ffcb9969c8009055e31e1a6e559 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-created.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=11e9749e373694a202444601058e8772 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-created.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=0a02f89c1be73ec15d2ac5f3b1cd0ed2 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-created.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=2ab2ebc271ee10af2cc580082e61c218 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-created.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=11a230783030c6a3ebd79fdbadf4d071 2500w" data-optimize="true" data-opv="2" />

### 4. Create an Automation from the Event

From the event details page (click on the event in the feed), you can click the **Automate** button.

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-automate.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=2ff4522c881fa28f9ebcbb944e552b12" alt="Event details page with the Automate button highlighted." data-og-width="2504" width="2504" data-og-height="292" height="292" data-path="v3/img/guides/webhook-automate.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-automate.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=59c7a7e463785f078d2683350404d6cf 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-automate.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=87fbeef54c261e5c97980a9d789fd93b 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-automate.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=dfeebf79b71c2d23fae30d9c35ee20a2 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-automate.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=9dbd7ff24902dded9dfcff5e98079c13 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-automate.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=c2884362f96d4684a17dfac97b96bb93 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/webhook-automate.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6740cf4de60e277e578836b0cc4ecbc9 2500w" data-optimize="true" data-opv="2" />

This will pre-fill an automation trigger based on the event you just created.

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-custom.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=b89876f934154273d59cf6778fb55d45" alt="Automation trigger definition pre-filled from a webhook event." data-og-width="2506" width="2506" data-og-height="1284" height="1284" data-path="v3/img/guides/automation-custom.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-custom.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=ee7c8f19b6a175f7d84e68ee12542603 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-custom.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=97dc3607b7b68e29b1a735da6b32fc93 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-custom.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=71cd85778f3a492d9efcb0835aa1c530 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-custom.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=7be6d1a54c548fa491e1ccc95393addf 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-custom.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=749aacc251081dfe8f3eb71ae2eab50f 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/automation-custom.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=deec7d8b8a847334a6e939d5da6ae522 2500w" data-optimize="true" data-opv="2" />

Click **Next** to define the action(s) this automation should perform, such as running a deployment or sending a notification.

## Troubleshooting Event Reception

If you've invoked your webhook but don't see the expected event in Prefect Cloud, or the event data isn't what you anticipated:

* **Check the Event Feed**: Look for any events related to your webhook, even if they don't match your exact expectations.
* **Look for `prefect-cloud.webhook.failed` events**: If Prefect Cloud encountered an error processing the webhook (e.g., an invalid template or malformed request), it will generate a `prefect-cloud.webhook.failed` event. This event contains details about the received request and any template rendering errors.
* **Verify your request**: Double-check the URL, HTTP method, headers, and body of the request you sent to the webhook.
* **Review your template**: Ensure your Jinja2 template correctly accesses the parts of the HTTP request you intend to use (e.g., `body.field_name`, `headers['Header-Name']`).

For more in-depth troubleshooting of webhook configuration and template rendering, see [Troubleshooting Webhook Configuration in the Concepts documentation](/v3/concepts/webhooks#troubleshooting-webhook-configuration).

## Further reading

For more on webhooks, see the [Webhooks Concepts](/v3/concepts/webhooks) page.


# How to manage API keys
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/api-keys

Create an API key to access Prefect Cloud from a local execution environment.

API keys enable you to authenticate a local environment to work with Prefect Cloud.

If you run `prefect cloud login` from your CLI, you can authenticate through your browser or by pasting an API key.

Authenticating through the browser directs you to an authorization page.
After you grant approval to connect, you're redirected to the CLI and the API key is saved to your local
[Prefect profile](/v3/develop/settings-and-profiles/).

If you choose to authenticate by pasting an API key, you must create an API key in the Prefect Cloud UI first.

## Create an API key

1. Select the account icon at the bottom-left corner of the UI.
2. Select **API Keys**.
   The page displays a list of previously generated keys, and allows you to create or delete API keys.
3. Select the **+** button to create a new API key.
   Provide a name for the key and an expiration date.

<Warning>
  Copy the key to a secure location since an API key cannot be revealed again in the UI after it is generated.
</Warning>

## Log in to Prefect Cloud with an API Key

```bash
prefect cloud login -k '<my-api-key>'
```

Alternatively, if you don't have a CLI available - for example, if you are connecting to Prefect Cloud within a remote serverless environment - set the `PREFECT_API_KEY` environment variable.

For more information see [Connect to Prefect Cloud](/v3/manage/cloud/connect-to-cloud).

## Service account API keys (Pro) (Enterprise)

Service accounts are a feature of Prefect Cloud [Pro and Enterprise tier plans](https://www.prefect.io/pricing) that enable you to
create a Prefect Cloud API key that is not associated with a user account.

Service accounts are useful for configuring API access for running workers, or executing flow runs on remote infrastructure.
Events and logs for flow runs in those environments are associated with the service account rather than a user. Manage or revoke API access by
configuring or removing the service account without disrupting user access.

See [service accounts](/v3/how-to-guides/cloud/manage-users/service-accounts) for more information.


# How to audit Cloud activity
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/audit-logs

Monitor user access and activity with audit logs in Prefect Cloud.

Prefect Cloud's [Pro and Enterprise plans](https://www.prefect.io/pricing) offer enhanced compliance and transparency through audit logs.
Audit logs provide a chronological record of activities performed by members in your account,
allowing you to monitor detailed Prefect Cloud actions for security and compliance purposes.

Audit logs show who took what action, when, and using what resources within your Prefect Cloud account.
In conjunction with appropriate tools and procedures, audit logs assist in detecting
potential security violations and investigating application errors.

Audit logs record:

* Access to workspaces
* User login activity
* User API key creation and removal
* Workspace creation and removal
* Account member invitations and removal
* Service account creation, API key rotation, and removal
* Billing payment method for self-serve pricing tiers

## View audit logs

From your account settings page, select the **Audit Log** page to view audit logs.
Administrators can view audit logs for:

* Account-level events in Prefect Cloud, such as:
  * Member invites
  * Changing a member's role
  * Member login and logout of Prefect Cloud
  * Creating or deleting a service account
* Workspace-level events in Prefect Cloud, such as:
  * Adding a member to a workspace
  * Changing a member's workspace role
  * Creating or deleting a workspace

Admins can filter audit logs on multiple dimensions to restrict the results they see by workspace, user, or event type.
View audit log events in the **Events** drop-down menu.

You may also filter audit logs by date range.
Audit log retention period varies by [Prefect Cloud plan](https://www.prefect.io/pricing).


# How to configure single sign-on
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/configure-sso

Configure single sign-on (SSO) for your Prefect Cloud users.

Prefect Cloud's [Enterprise plans](https://www.prefect.io/pricing) offer single sign-on (SSO) integration with your team's identity provider.
You can set up SSO integration with any identity provider that supports:

* OIDC
* SAML 2.0

When using SSO, Prefect Cloud won't store passwords for any accounts managed by your identity provider.
Members of your Prefect Cloud account will log in and authenticate using your identity provider.

Once your SSO integration is set up, non-admins are required to authenticate through the SSO provider when
accessing account resources.

See the [Prefect Cloud plans](https://www.prefect.io/pricing) to learn more about options for supporting more users and
workspaces, service accounts, and SSO.

## Configure SSO

Within your account, select the **SSO** page to enable SSO for users.

If you haven't enabled SSO for a domain yet, enter the email domains for enabling SSO in Prefect Cloud, and save it.

Under **Enabled Domains**, select the domains from the **Domains** list, then select **Generate Link**.
This step creates a link to configure SSO with your identity provider.

Using the provided link, navigate to the Identity Provider Configuration dashboard and select your identity provider to continue
configuration. If your provider isn't listed, try `SAML` or `Open ID Connect` instead.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/cloud-sso-dashboard.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=d432b99de6e99f434e5fabd0674210bc" alt="Opening the Identity Provider Configuration dashboard." data-og-width="1280" width="1280" data-og-height="965" height="965" data-path="v3/img/ui/cloud-sso-dashboard.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/cloud-sso-dashboard.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=77727915166cb40018b110782c869686 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/cloud-sso-dashboard.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=e06a42888e2eae48a7175e728ebbf278 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/cloud-sso-dashboard.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=915170eb1bdebec9af2faaac77ce3c42 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/cloud-sso-dashboard.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c95ce23fa809180bde4dd6edcc04df96 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/cloud-sso-dashboard.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=2acc19f9a522efcbf1fe459d59f96a0a 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/cloud-sso-dashboard.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=d182d655b3ebfc51222e342a77f33a69 2500w" data-optimize="true" data-opv="2" />

Once you complete SSO configuration, your users must authenticate through your identity provider when accessing account resources, giving you full control over application access.

## Directory sync

**Directory sync** automatically provisions and de-provisions users for your account.

Provisioned users are given basic “Member” roles and have access to any resources that role entails.

When a user is unassigned from the Prefect Cloud application in your identity provider, they automatically lose access to
Prefect Cloud resources. This allows your IT team to control access to Prefect Cloud without signing into the Prefect UI.

## SCIM Provisioning

Enterprise plans have access to SCIM for user provisioning.
The SSO tab provides access to enable SCIM provisioning.


# How to manage user accounts
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/index

Special features for Prefect Cloud users

Sign up for a Prefect Cloud account at [app.prefect.cloud](https://app.prefect.cloud).

<Note>
  An individual user can be invited to become a member of other accounts.
</Note>

## User settings

You can access your personal settings in the [profile menu](https://app.prefect.cloud/my/profile), including:

* **Profile**: View and edit basic information, such as name.
* **API keys**: Create and view [API keys](/v3/how-to-guides/cloud/manage-users/api-keys)
  for connecting to Prefect Cloud from the CLI or other environments.
* **Preferences**: Manage settings, such as color mode and default time zone.
* **Feature previews**: Enable or disable feature previews.

## Account roles

Users who are part of an account can hold the role of Admin or Member.
Admins can invite other users to join the account and manage the account's workspaces and teams.

Admins on Pro and Enterprise tier Prefect Cloud accounts can grant members of the account
[roles](/v3/how-to-guides/cloud/manage-users/manage-roles) in a workspace, such as Runner or Viewer.
Custom roles are available on Enterprise tier accounts.

## API keys

[API keys](/v3/how-to-guides/cloud/manage-users/api-keys) enable you to authenticate an environment to work with Prefect Cloud.

## Service accounts (Pro) (Enterprise)

[Service accounts](/v3/how-to-guides/cloud/manage-users/service-accounts) enable you to create a
Prefect Cloud API key that is not associated with a user account.

## Single sign-on (Pro)

Enterprise tier plans offer [single sign-on (SSO)](/v3/how-to-guides/cloud/manage-users/configure-sso/)
integration with your team's identity provider, including options for
[directory sync and SCIM provisioning](/v3/how-to-guides/cloud/manage-users/configure-sso/#directory-sync).

## Audit log (Pro) (Enterprise)

[Audit logs](/v3/how-to-guides/cloud/manage-users/audit-logs/) provide a chronological record of
activities performed by Prefect Cloud users who are members of an account.

## Object-level access control lists (Enterprise)

Prefect Cloud's Enterprise plan offers object-level access control lists (ACLs) to
restrict access to specific users and service accounts within a workspace.

## Teams (Enterprise)

Users of Enterprise tier Prefect Cloud accounts can be added to
[Teams](/v3/how-to-guides/cloud/manage-users/manage-teams/) to simplify access control governance.


# How to manage account roles
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/manage-roles

Configure user workspace roles in Prefect Cloud.

Prefect Cloud's [Pro and Enterprise tiers](https://www.prefect.io/pricing) allow you to set team member
access to the appropriate level within specific workspaces.

Role-based access controls (RBAC) enable you to assign users granular permissions to perform certain activities.

Enterprise account administrators can create custom roles for users to give users access to capabilities
beyond the scope of Prefect's built-in workspace roles.

## Built-in roles

Roles give users abilities at either the account level or at the individual workspace level.

* An *account-level role* defines a user's default permissions within an account.
* A *workspace-level role* defines a user's permissions within a specific workspace.

The following sections outline the abilities of the built-in, Prefect-defined access controls and workspace roles.

### Account-level roles

The following built-in roles have permissions across an account in Prefect Cloud.

{/*
  <!-- vale off -->
  */}

| Role   | Abilities                                                                                                                                                                                                                                                                                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Owner  | - Set/change all account profile settings allowed to be set/changed by a Prefect user. <br /> - Add and remove account members, and their account roles. <br /> - Create and delete service accounts in the account. <br /> - Create workspaces in the account. <br /> - Implicit workspace owner access on all workspaces in the account. <br /> - Bypass SSO.        |
| Admin  | - Set/change all account profile settings allowed to be set/changed by a Prefect user. <br /> - Add and remove account members, and their account roles. <br /> - Create and delete service accounts in the account. <br /> - Create workspaces in the account. <br /> - Implicit workspace owner access on all workspaces in the account. <br /> - Cannot bypass SSO. |
| Member | - View account profile settings. <br /> - View workspaces you have access to in the account. <br /> - View account members and their roles. <br /> - View service accounts in the account.                                                                                                                                                                             |

{/*
  <!-- vale on -->
  */}

### Workspace-level roles

The following built-in roles have permissions within a given workspace in Prefect Cloud.

| Role      | Abilities                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Viewer    | - View flow runs within a workspace. <br /> - View deployments within a workspace. <br /> - View all work pools within a workspace. <br /> - View all blocks within a workspace. <br /> - View all automations within a workspace. <br /> - View workspace handle and description.                                                                                                                                                               |
| Runner    | All Viewer abilities, *plus*: <br /> - Run deployments within a workspace.                                                                                                                                                                                                                                                                                                                                                                       |
| Developer | All Runner abilities, *plus*: <br /> - Run flows within a workspace. <br /> - Delete flow runs within a workspace. <br /> - Create, edit, and delete deployments within a workspace. <br /> - Create, edit, and delete work pools within a workspace. <br /> - Create, edit, and delete all blocks and their secrets within a workspace. <br /> - Create, edit, and delete automations within a workspace. <br /> - View all workspace settings. |
| Owner     | All Developer abilities, *plus*: <br /> - Add and remove account members, and set their role within a workspace. <br /> - Set the workspace's default workspace role for all users in the account. <br /> - Set, view, edit workspace settings.                                                                                                                                                                                                  |
| Worker    | The minimum scopes required for a worker to poll for and submit work.                                                                                                                                                                                                                                                                                                                                                                            |

## Custom workspace roles

The built-in roles serve the needs of most users, but custom roles give users access to
specific permissions within a workspace.

Custom roles can inherit permissions from a built-in role.
This enables tweaks to the role to meet your team's needs, while ensuring users still benefit
from Prefect's default workspace role permission curation as new capabilities becomes available.

{/*
  <!-- vale off -->
  */}

You can create custom workspace roles independently of Prefect's built-in roles. This option gives
workspace admins full control of user access to workspace capabilities. However, for non-inherited custom roles,
the workspace Admin takes on the responsibility for monitoring and setting permissions for new capabilities as it is released.

{/*
  <!-- vale on -->
  */}

See [Role permissions](#workspace-role-permissions) for details of permissions you may set for custom roles.

After you create a new role, it becomes available in the account **Members** page and the **Workspace Sharing**
page for you to apply to users.

### Inherited roles

You can configure a custom role as an **Inherited Role**. Using an inherited role allows you to create a
custom role from a set of initial permissions associated with a built-in Prefect role.
You can add additional permissions to the custom role. Permissions included in the inherited role cannot be removed.

Custom roles created from an inherited role follow Prefect's default workspace role permission curation as
new capabilities becomes available.

To configure an inherited role alongside a custom role, select **Inherit permission from a default role**, then select the role from which the new role should inherit permissions.

## Workspace role permissions

The following permissions are available for custom roles.

### Automations

| Permission                           | Description                                                                                                     |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| View automations                     | User can see configured automations within a workspace.                                                         |
| Create, edit, and delete automations | User can create, edit, and delete automations within a workspace. Includes permissions of **View automations**. |

### Blocks

| Permission                      | Description                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| View blocks                     | User can see configured blocks within a workspace.                                                                                   |
| View secret block data          | User can see configured blocks and their secrets within a workspace. Includes permissions of **View blocks**.                        |
| Create, edit, and delete blocks | User can create, edit, and delete blocks within a workspace. Includes permissions of **View blocks** and **View secret block data**. |

### Deployments

| Permission                  | Description                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| View deployments            | User can see configured deployments within a workspace.                                                                                                                                                                                                                                                                                                              |
| Run deployments             | User can run deployments within a workspace. This does not give a user permission to execute the flow associated with the deployment. This only gives a user (through their key) the ability to run a deployment—another user/key must actually execute that flow, such as a service account with an appropriate role. Includes permissions of **View deployments**. |
| Create and edit deployments | User can create and edit deployments within a workspace. Includes permissions of **View deployments** and **Run deployments**.                                                                                                                                                                                                                                       |
| Delete deployments          | User can delete deployments within a workspace. Includes permissions of **View deployments**, **Run deployments**, and **Create and edit deployments**.                                                                                                                                                                                                              |

### Flows

| Permission                                      | Description                                                                                                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| View flows and flow runs                        | User can see flows and flow runs within a workspace.                                                                                                   |
| Create, update, and delete saved search filters | User can create, update, and delete saved flow run search filters configured within a workspace. Includes permissions of **View flows and flow runs**. |
| Create, update, and run flows                   | User can create, update, and run flows within a workspace. Includes permissions of **View flows and flow runs**.                                       |
| Delete flows                                    | User can delete flows within a workspace. Includes permissions of **View flows and flow runs** and **Create, update, and run flows**.                  |

### Notifications

| Permission                            | Description                                                                                                                                                                |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| View notification policies            | User can see notification policies configured within a workspace.                                                                                                          |
| Create and edit notification policies | User can create and edit notification policies configured within a workspace. Includes permissions of **View notification policies**.                                      |
| Delete notification policies          | User can delete notification policies configured within a workspace. Includes permissions of **View notification policies** and **Create and edit notification policies**. |

### Task run concurrency

| Permission                                  | Description                                                                                                                            |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| View concurrency limits                     | User can see configured task run concurrency limits within a workspace.                                                                |
| Create, edit, and delete concurrency limits | User can create, edit, and delete task run concurrency limits within a workspace. Includes permissions of **View concurrency limits**. |

### Work pools

| Permission                         | Description                                                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| View work pools                    | User can see work pools configured within a workspace.                                                                                            |
| Create, edit, and pause work pools | User can create, edit, and pause work pools configured within a workspace. Includes permissions of **View work pools**.                           |
| Delete work pools                  | User can delete work pools configured within a workspace. Includes permissions of **View work pools** and **Create, edit, and pause work pools**. |

### Workspace management

| Permission                                        | Description                                                                                                       |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| View information about workspace service accounts | User can see service accounts configured within a workspace.                                                      |
| View information about workspace users            | User can see user accounts for users invited to the workspace.                                                    |
| View workspace settings                           | User can see settings configured within a workspace.                                                              |
| Edit workspace settings                           | User can edit settings for a workspace. Includes permissions of **View workspace settings**.                      |
| Delete the workspace                              | User can delete a workspace. Includes permissions of **View workspace settings** and **Edit workspace settings**. |


# How to manage teams
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/manage-teams

Manage teams of users in Prefect Cloud.

Prefect Cloud's [Enterprise plan](https://www.prefect.io/pricing) offers team management to simplify access control governance.

Account Admins can configure teams and team membership from the account settings menu by clicking **Teams**.
Teams are composed of users and service accounts.
Teams can be added to workspaces or object access control lists just like users and service accounts.

If SCIM is enabled on your account, the set of teams and the users within them is governed by your IDP.
Prefect Cloud service accounts, which are not governed by your IDP, can be still be added to your existing set of teams.

See the [Prefect Cloud plans](https://www.prefect.io/pricing) to learn more about options for supporting teams.


# How to manage Access Control Lists (ACLs)
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/object-access-control-lists

Restrict block and deployment access to individual actors within a workspace.

Prefect Cloud's [Enterprise plan](https://www.prefect.io/pricing) offers object-level access control lists (ACLs) to restrict access to
specific users and service accounts within a workspace. ACLs are supported for blocks, deployments, and work pools.

Organization Admins and Workspace Owners can configure access control lists by navigating to an object and clicking **manage access**.
When an ACL is added, all users and service accounts with access to an object through their workspace role will lose access if not
explicitly added to the ACL.

<Note>
  **ACLs and visibility**

  Objects not governed by access control lists such as flow runs, flows, and artifacts are visible to a user within a
  workspace even if an associated block or deployment has been restricted for that user.
</Note>

See the [Prefect Cloud plans](https://www.prefect.io/pricing) to learn more about options for supporting object-level access control.

## ACL delegation for work pools and deployments

Deployments can delegate their permission checks to work pools. This delegation works as follows:

1. If a work pool has ACLs configured, those ACLs apply to all deployments that use the work pool.
2. If a work pool does not have ACLs, the ACLs of the individual deployments apply instead.

This delegation system allows for more efficient management of permissions, especially when multiple deployments use the same work pool.


# How to secure access by IP address
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/secure-access-by-ip-address

Manage network access to Prefect Cloud accounts with IP Allowlists.

IP allowlisting is an available upgrade to certain Enterprise plans.
IP allowlisting enables account administrators to restrict access to Prefect Cloud APIs and the UI at the network level.
To learn more, please contact your account manager or the Prefect team at [sales@prefect.io](mailto:sales@prefect.io).

Once the feature has been enabled for your team's Enterprise account, use the Prefect CLI to add an IP address to the allowlist:

<Note>To help prevent accidental account lockouts, an update to an allowlist requires the requestor's current IP address to be on the list.</Note>

```bash
prefect cloud ip-allowlist add <your-ip-address> --description "My home IP address"
```

The allowlist has a limit of 25 entries;
however in addition to individual IP addresses, a range of IP addresses can be added as a single entry using CIDR notation:

```bash
prefect cloud ip-allowlist add "192.168.1.0/24" -d "A CIDR block containing 256 IP addresses from 192.168.1.0 to 192.168.1.255"
```

Next, enable the allowlist for your account to start enforcing the restrictions:

```bash
prefect cloud ip-allowlist enable
```

Individual entries can also be toggled on or off:

```bash
prefect cloud ip-allowlist toggle <ip-address>
```

Once turned on with at least one enabled IP entry, the allowlist will be enforced for all incoming requests to Prefect Cloud from the UI and API.

For other related commands, see the CLI help documentation with:

```bash
prefect cloud ip-allowlist --help
```


# How to secure access over PrivateLink
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/secure-access-by-private-link

Manage network access to Prefect Cloud accounts over PrivateLink.

PrivateLink is an available upgrade to certain Enterprise plans.\
[PrivateLink](https://aws.amazon.com/privatelink/) enables account administrators to restrict access to Prefect Cloud APIs and the UI at the network level, by routing all network traffic through AWS and GCP.\
Traffic between your network and Prefect Cloud is encrypted, and does not traverse the public internet.

To learn more, please contact your account manager or the Prefect team at [sales@prefect.io](mailto:sales@prefect.io).

Your Prefect team will provide the service endpoint to register.
Provide the following information for the registered endpoint so that Prefect can accept the connection:

* AWS Account Number
* AWS VPC IDs
* Source Region for each VPC (for example, `us-east-1`, `us-east-2`, etc.)
* VPC Endpoint ID

Prefect will match your pending connection to the information provided, and accept the connection once approved.

Once accepted, customers should enable "Modify Private DNS" to ensure the VPCs can resolve the Prefect service endpoint.

With Private DNS and the accepted connection, connectivity can be validated through curl:

```bash
curl -i https://api-internal.private.prefect.cloud/api/health
```

To configure Prefect clients and workers to use the endpoint, `PREFECT_API_URL` and `PREFECT_CLOUD_API_URL` should be set to the endpoint provided by Prefect.

```bash
prefect config set PREFECT_API_URL=https://api-internal.private.prefect.cloud/api/accounts/<ACCOUNT_ID>/workspaces/<WORKSPACE_ID>
prefect config set PREFECT_CLOUD_API_URL=https://api-internal.private.prefect.cloud/api
```


# How to manage service accounts
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/manage-users/service-accounts

Workspaces are isolated environments for flows and deployments within Prefect Cloud.

Service accounts enable you to create a Prefect Cloud API key that is not associated with a user account.
Service accounts are typically used to configure API access for running workers or executing deployment flow runs on remote infrastructure.

Service accounts are non-user accounts that have the following features:

* Prefect Cloud [API keys](/v3/how-to-guides/cloud/manage-users/api-keys)
* [Roles](/v3/how-to-guides/cloud/manage-users/manage-roles) and permissions

With service account credentials, you can
[configure an execution environment](/v3/manage/cloud/connect-to-cloud/#configure-a-local-execution-environment)
to interact with your Prefect Cloud workspaces without a user manually logging in from that environment.
Service accounts may be created, added to workspaces, have their roles changed, or deleted without affecting other user accounts.
You may apply any valid *workspace-level* role to a service account.

Select **Service Accounts** to view, create, or edit service accounts.

Service accounts are created at the account level, but individual workspaces may be shared with the service account.
See [workspace sharing](/v3/manage/cloud/workspaces/#workspace-sharing) for more information.

<Tip>
  **Service account credentials**

  When you create a service account, Prefect Cloud creates a new API key for the account and provides the
  API configuration command for the execution environment.
  Save these to a safe location for future use.
  If the access credentials are lost or compromised, regenerate them from the service account page.
</Tip>

## Create a service account

On the **Service Accounts** page, select the **+** icon to create a new service account. Configure:

* The service account name. This name must be unique within your account.
* An expiration date, or the **Never Expire** option.

<Note>
  **Service account roles**

  A service account may only be a Member of an account.
  You may apply any valid *workspace-level* role to a service account when it is
  [added to a workspace](/v3/manage/cloud/workspaces/#workspace-sharing).
</Note>

Select **Create** to create the new service account.

<Warning>
  Copy the key to a secure location since an API key cannot be revealed again in the UI after it is generated.
</Warning>

Change the API key and expiration for a service account by rotating the API key.
Select **Rotate API Key** from the menu on the left side of the service account's information on this page.
Optionally, you can set a period of time for your old service account key to remain active.

To delete a service account, select **Remove** from the menu on the left side of the service account's information.


# How to troubleshoot Prefect Cloud
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/troubleshoot-cloud

Learn how to identify and resolve common issues with Prefect Cloud.

## Prefect Cloud and proxies

Proxies handle network requests between a server and a client.

To communicate with Prefect Cloud, the Prefect client library makes HTTPS requests.
These requests are made with the [`httpx`](https://www.python-httpx.org/) Python library.
`httpx` respects accepted proxy environment variables, so the Prefect client can communicate through proxies.

To enable communication through proxies, set the `HTTPS_PROXY` and `SSL_CERT_FILE` environment
variables in your execution environment.

See the [Using Prefect Cloud with proxies](https://github.com/PrefectHQ/prefect/discussions/16175)
GitHub Discussion for more information.

You should whitelist the URLs for the UI, API, Authentication,
and the current OCSP server for outbound-communication in a secure environment:

* app.prefect.cloud
* api.prefect.cloud
* auth.workos.com
* api.github.com
* github.com
* ocsp.pki.goog/s/gts1d4/OxYEb8XcYmo

## Prefect Cloud access through the API

If the Prefect Cloud API key, environment variable settings, or account login for your execution environment
are not configured correctly, you may experience errors or unexpected flow run results when using Prefect CLI commands,
running flows, or observing flow run results in Prefect Cloud.

Use the `prefect config view` CLI command to make sure your execution environment is correctly configured
to access Prefect Cloud:

```bash
$ prefect config view
PREFECT_PROFILE='cloud'
PREFECT_API_KEY='pnu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' (from profile)
PREFECT_API_URL='https://api.prefect.cloud/api/accounts/...' (from profile)
```

Make sure `PREFECT_API_URL` is configured to use `https://api.prefect.cloud/api/...`.

Make sure `PREFECT_API_KEY` is configured to use a valid API key.

You can use the `prefect cloud workspace ls` CLI command to view or set the active workspace.

```bash
prefect cloud workspace ls
```

```shell
┏━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃   Available Workspaces: ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━┩
│   g-gadflow/g-workspace │
│    * prefect/workinonit │
━━━━━━━━━━━━━━━━━━━━━━━━━━━
    * active workspace
```

You can also check that the account and workspace IDs specified in the URL for `PREFECT_API_URL`
match those shown in the URL for your Prefect Cloud workspace.

## Prefect Cloud login errors

If you're having difficulty logging in to Prefect Cloud, the following troubleshooting steps may resolve the issue,
or will provide more information when sharing your case to the support channel.

* Are you logging into Prefect Cloud 3? Prefect Cloud 1, Prefect Cloud 2, and Prefect Cloud 3 use separate accounts.
  Make sure to use the right Prefect Cloud 3 URL: \<[https://app.prefect.cloud/>](https://app.prefect.cloud/>)
* Do you already have a Prefect Cloud account? If you're having difficulty accepting an invitation,
  try creating an account first using the email associated with the invitation, then accept the invitation.
* Are you using a single sign-on (SSO) provider, social authentication (Google, Microsoft, or GitHub) or just using an emailed link?

Other tips to help with login difficulties:

* Hard refresh your browser with Cmd+Shift+R.
* Try in a different browser. We actively test against the following browsers:
  * Chrome
  * Edge
  * Firefox
  * Safari
* Clear recent browser history/cookies

None of this worked?

Email us at \<[help@prefect.io](mailto:help@prefect.io)> and provide answers to the questions above in your email to make it faster to troubleshoot
and unblock you. Make sure you add the email address you used to attempt to log in, your Prefect Cloud account name, and, if applicable,
the organization it belongs to.

# General troubleshooting

The first troubleshooting step is to confirm that you are running the latest version of Prefect.
If you are not, upgrade (see below) to the latest version, since the issue may have already been fixed.
Beyond that, there are several categories of errors:

* The issue may be in your flow code, in which case you should carefully read the [logs](#logs).
* The issue could be with how you are authenticated, and whether or not you are connected to [Cloud](#cloud).
* The issue might have to do with how your code is [executed](#execution).

## Upgrade

Prefect is constantly evolving by adding new features and fixing bugs. A patch may have already been
identified and released. Search existing [issues](https://github.com/PrefectHQ/prefect/issues) for similar reports
and check out the [Release Notes](https://github.com/PrefectHQ/prefect/releases).

Upgrade to the newest version with the following command:

```bash
pip install --upgrade prefect
```

Different components may use different versions of Prefect:

* **Cloud** is generally the newest version. Cloud is continuously deployed by the Prefect team.
  When using a self-hosted server, you can control this version.
* **Workers** change versions infrequently, and are usually the latest version at the time of creation.
  Workers provision infrastructure for flow runs, so upgrading them may help with infrastructure problems.
* **Flows** could use a different version than the worker that created them, especially when running in different environments.
  Suppose your worker and flow both use the latest official Docker image, but your worker was created a month ago.
  Your worker is often an older version than your flow.

<Note>
  **Integration Versions**

  [Integrations](/integrations/) are versioned and released independently of the core Prefect library.
  They should be upgraded simultaneously with the core library, using the same method.
</Note>

## Logs

In many cases, there is an informative stack trace in Prefect's [logs](/v3/develop/logging/).
**Read it carefully**, locate the source of the error, and try to identify the cause.

There are two types of logs:

* **Flow and task logs** are always scoped to a flow. They are sent to Prefect and are viewable in the UI.
* **Worker logs** are not scoped to a flow and may have more information on what happened before the flow started.
  These logs are generally only available where the worker is running.

If your flow and task logs are empty, there may have been an infrastructure issue that prevented your flow from starting.
Check your worker logs for more details.

If there is no clear indication of what went wrong, try updating the logging level from the default `INFO` level
to the `DEBUG` level. [Settings](https://reference.prefect.io/prefect/settings/) such as the logging level are propagated
from the worker environment to the flow run environment. Set them with environment variables or the `prefect config set` CLI:

```bash
# Using the CLI
prefect config set PREFECT_LOGGING_LEVEL=DEBUG

# Using environment variables
export PREFECT_LOGGING_LEVEL=DEBUG
```

The `DEBUG` logging level produces a high volume of logs, so consider setting it back to `INFO` once any issues are resolved.

## Cloud

When using Prefect Cloud, there are the additional concerns of authentication and authorization.
The Prefect API authenticates users and service accounts, collectively known as actors, with API keys.
Missing, incorrect, or expired API keys result in a 401 response with detail `Invalid authentication credentials`.
Use the following command to check your authentication, replacing `$PREFECT_API_KEY` with your API key:

```bash
curl -s -H "Authorization: Bearer $PREFECT_API_KEY" "https://api.prefect.cloud/api/me/"
```

<Note>
  **Users vs Service Accounts**

  [Service accounts](/v3/how-to-guides/cloud/manage-users/service-accounts) (sometimes referred to as bots),
  represent non-human actors that interact with Prefect such as workers and CI/CD systems.
  Each human that interacts with Prefect should be represented as a user.
  User API keys start with `pnu_` and service account API keys start with `pnb_`.
</Note>

Actors can be members of [workspaces](/v3/manage/cloud/workspaces/). An actor attempting an action in a
workspace they are not a member of results in a 404 response. Use the following command to check your actor's workspace memberships:

```bash
curl -s -H "Authorization: Bearer $PREFECT_API_KEY" "https://api.prefect.cloud/api/me/workspaces"
```

<Note>
  **Formatting JSON**

  Python comes with a helpful [tool](https://docs.python.org/3/library/json.html#module-json.tool) for formatting JSON.
  Append the following to the end of the command above to make the output more readable: `| python -m json.tool`
</Note>

Make sure your actor is a member of the workspace you are working in. Within a workspace,
an actor has a [role](/v3/how-to-guides/cloud/manage-users/manage-roles) which grants them certain permissions.
Insufficient permissions result in an error. For example, starting a worker with the **Viewer** role results in errors.

## Execution

The user can execute flows locally, or remotely by a worker. Local execution generally means that you, the user,
run your flow directly with a command like `python flow.py`. Remote execution generally means that a worker runs your flow
through a [deployment](/v3/how-to-guides/deployment_infra/docker) (optionally on different infrastructure).

With remote execution, the creation of your flow run happens separately from its execution.
Flow runs are assigned to a work pool and a work queue. For flow runs to execute, a worker must be subscribed
to the work pool and work queue, or the flow runs will go from `Scheduled` to `Late`.
Ensure that your work pool and work queue have a subscribed worker.

Local and remote execution can also differ in their treatment of relative imports.
If switching from local to remote execution results in local import errors, try replicating the
behavior by executing the flow locally with the `-m` flag (For example, `python -m flow` instead of `python flow.py`).
Read more about `-m` in this [Stack Overflow post](https://stackoverflow.com/a/62923810).

## API tests return an unexpected 307 Redirected

**Summary:** requests require a trailing `/` in the request URL.

If you write a test that does not include a trailing `/` when making a request to a specific endpoint:

```python
async def test_example(client):
    response = await client.post("/my_route")
    assert response.status_code == 201
```

You'll see a failure like:

```bash
E       assert 307 == 201
E        +  where 307 = <Response [307 Temporary Redirect]>.status_code
```

To resolve this, include the trailing `/`:

```python
async def test_example(client):
    response = await client.post("/my_route/")
    assert response.status_code == 201
```

Note: requests to nested URLs may exhibit the *opposite* behavior and require no trailing slash:

```python
async def test_nested_example(client):
    response = await client.post("/my_route/filter/")
    assert response.status_code == 307

    response = await client.post("/my_route/filter")
    assert response.status_code == 200
```

**Reference:** "HTTPX disabled redirect following by default" in
[`0.22.0`](https://github.com/encode/httpx/blob/master/CHANGELOG.md#0200-13th-october-2021).

## `pytest.PytestUnraisableExceptionWarning` or `ResourceWarning`

As you're working with one of the `FlowRunner` implementations, you may get an
error like this:

```bash
E               pytest.PytestUnraisableExceptionWarning: Exception ignored in: <ssl.SSLSocket fd=-1, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0>
E
E               Traceback (most recent call last):
E                 File ".../pytest_asyncio/plugin.py", line 306, in setup
E                   res = await func(**_add_kwargs(func, kwargs, event_loop, request))
E               ResourceWarning: unclosed <ssl.SSLSocket fd=10, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, laddr=('127.0.0.1', 60605), raddr=('127.0.0.1', 6443)>

.../_pytest/unraisableexception.py:78: PytestUnraisableExceptionWarning

```

This error states that your test suite (or the `prefect` library code) opened a
connection to something (like a Docker daemon or a Kubernetes cluster) and didn't close
it.

It may help to re-run the specific test with `PYTHONTRACEMALLOC=25 pytest ...` so that
Python can display more of the stack trace where the connection was opened.


# How to manage workspaces
Source: https://docs-3.prefect.io/v3/how-to-guides/cloud/workspaces

Organize and compartmentalize your workflows with workspaces.

A workspace is a discrete environment within Prefect Cloud for your workflows and related information.
For example, you can use separate workspaces to isolate dev, staging, and prod environments, or to provide separation between different teams.

## Get started with workspaces

When you first log into Prefect Cloud, you are prompted to create your own workspace.

To see all workspace workspaces you can access, click on your workspace name in the top of the navigation sidebar.
To see all workspace workspaces you can access, click on your workspace name in the top of the navigation sidebar.

Your list of available workspaces may include:

* Your own account's workspace.
* Workspaces in an account you're invited to with Admin or Member access.

Your user permissions within workspaces may vary. Account admins can assign roles and permissions at the workspace level.

## Create a workspace

On the Account settings dropdown, select the "Create a new workspace" button to create a new workspace.

Configure:

* The **Workspace Owner** from the dropdown account menu options.
* A unique **Workspace Name** must be unique within the account.
* An optional description for the workspace.

Select **Create** to create the new workspace. The number of available workspaces varies by [Prefect Cloud plan](https://www.prefect.io/pricing/).
See [Pricing](https://www.prefect.io/pricing/) if you need additional workspaces or users.

## Control access

Within a Prefect Cloud Pro or Enterprise tier account, workspace owners can invite other people as members, and provision [service accounts](https://docs.prefect.io/ui/service-accounts/) to a workspace.
A workspace owner assigns a [workspace role](https://docs.prefect.io/ui/roles/) to the user and specifies the user's scope of permissions within the workspace.

As a workspace owner, select **Workspaces -> Members** to manage members and **Workspaces -> Service Accounts** and service accounts for the workspace.
Previously invited individuals or provisioned service accounts are listed here.

To invite someone to an account, select the **Members +** icon. You can select from a list of existing account members.

Select a role for the user. This is the initial role for the user within the workspace.
A workspace owner can change this role at any time.

To remove a workspace member, select **Remove** from the menu on the right side of the user information on this page.

To add a service account to a workspace, select the **Service Accounts +** icon.
Select a **Name**, **Account Role**, **Expiration Date**, and optionally, a **Workspace**.

To update, delete, or rotate the API key for a service account, select an option for an existing service account from the menu on the right side of the service account.

## Transfer a workspace

Workspace transfer enables you to move an existing workspace from one account to another.

Workspace transfer retains existing workspace configuration and flow run history, including blocks, deployments, automations, work pools, and logs.

<Note>
  **Workspace transfer permissions**

  You must have administrator privileges to initiate or approve a workspace transfer.

  To initiate a workspace transfer between personal accounts, contact [support@prefect.io](mailto:support@prefect.io).
</Note>

Click on the name of your workspace in the sidebar navigation and select **Workspace settings**.

From the three dot menu in the upper right of the page, select **Transfer**.

The **Transfer Workspace** page shows the workspace to be transferred on the left.
Select the target account for the workspace on the right.

<Tip>
  **Workspace transfer impact on accounts**

  Workspace transfer may impact resource usage and costs for source and target accounts.

  When you transfer a workspace, users, API keys, and service accounts may lose access to the workspace.
  The audit log will no longer track activity on the workspace.
  Flow runs ending outside of the destination account's flow run retention period will be removed.
  You may also need to update Prefect CLI profiles and execution environment settings to access the workspace's new location.

  You may incur new charges in the target account to accommodate the transferred workspace.
</Tip>

## Delete a workspace

Deleting a workspace deletes all of its data including deployments, flow run history, work pools, and automations.

Click on the name of your workspace in the sidebar navigation and select **Workspace settings**.

From the three dot menu in the upper right of the page, select **Delete**.


# How to manage settings
Source: https://docs-3.prefect.io/v3/how-to-guides/configuration/manage-settings



### View current configuration

To view all available settings and their active values from the command line, run:

```bash
prefect config view --show-defaults
```

These settings are type-validated and you may verify your setup at any time with:

```bash
prefect config validate
```

### Configure settings for the active profile

To update a setting for the active profile, run:

```bash
prefect config set <setting>=<value>
```

For example, to set the `PREFECT_API_URL` setting to `http://127.0.0.1:4200/api`, run:

```bash
prefect config set PREFECT_API_URL=http://127.0.0.1:4200/api
```

To restore the default value for a setting, run:

```bash
prefect config unset <setting>
```

For example, to restore the default value for the `PREFECT_API_URL` setting, run:

```bash
prefect config unset PREFECT_API_URL
```

### Create a new profile

To create a new profile, run:

```bash
prefect profile create <profile>
```

To switch to a new profile, run:

```bash
prefect profile use <profile>
```

### Configure settings for a project

To configure settings for a project, create a `prefect.toml` or `.env` file in the project directory and add the settings with the values you want to use.

For example, to configure the `PREFECT_API_URL` setting to `http://127.0.0.1:4200/api`, create a `.env` file with the following content:

```bash
PREFECT_API_URL=http://127.0.0.1:4200/api
```

To configure the `PREFECT_API_URL` setting to `http://127.0.0.1:4200/api` in a `prefect.toml` file, create a `prefect.toml` file with the following content:

```bash
api.url = "http://127.0.0.1:4200/api"
```

Refer to the [setting concept guide](/v3/concepts/settings-and-profiles/) for more information on how to configure settings and the [settings reference guide](/v3/api-ref/settings-ref/) for more information on the available settings.

### Configure temporary settings for a process

To configure temporary settings for a process, set an environment variable with the name matching the setting you want to configure.

For example, to configure the `PREFECT_API_URL` setting to `http://127.0.0.1:4200/api` for a process, set the `PREFECT_API_URL` environment variable to `http://127.0.0.1:4200/api`.

```bash
export PREFECT_API_URL=http://127.0.0.1:4200/api
```

You can use this to run a command with the temporary setting:

```bash
PREFECT_LOGGING_LEVEL=DEBUG python my_script.py
```


# How to store secrets
Source: https://docs-3.prefect.io/v3/how-to-guides/configuration/store-secrets



### Store secret strings

You can use the `Secret` block to store secret strings.

```python
from prefect.blocks.system import Secret

secret = Secret(value="Marvin's surprise birthday party is on the 15th")
secret.save("surprise-party")
```

You can access the secret value in your workflow by loading a `Secret` block with the same name.

{/* pmd-metadata: notest */}

```python
from prefect import flow    
from prefect.blocks.system import Secret

@flow
def my_flow():
    secret = Secret.load("surprise-party")
    print(secret.get())
```

Secret values are encrypted at rest when stored in your Prefect backend.

To update a secret, save the new value with the `overwrite` parameter set to `True`.

{/* pmd-metadata: notest */}

```python
from prefect.blocks.system import Secret

secret = Secret(value="Marvin's surprise birthday party is actually on the 16th")
secret.save("surprise-party", overwrite=True)
```

Secret blocks can also be created and updated through the Prefect UI.

### Store common configuration securely

Prefect offers a set of blocks for storing common configuration.

Many of these blocks are included as part of Prefect's integration libraries.

For example, use the `AwsCredentials` block to store AWS keys to connect to AWS services in your workflows.

<Tip>
  You can install `prefect-aws` by running `pip install prefect-aws`.
</Tip>

```python
from prefect_aws import AwsCredentials

aws_credentials = AwsCredentials(
    aws_access_key_id="my-access-key-id",
    aws_secret_access_key="nice-try-you-are-not-getting-my-key-friend")

aws_credentials.save("aws-credentials")
```

You can load the block to use the credentials in your workflow.

{/* pmd-metadata: notest */}

```python
from prefect_aws import AwsCredentials
import boto3

# Load AWS credentials from Prefect
creds = AwsCredentials.load("aws-credentials")

# Create boto3 session using the credentials
session = boto3.Session(
    aws_access_key_id=creds.aws_access_key_id,
    aws_secret_access_key=creds.aws_secret_access_key
)

# Create S3 client
s3_client = session.client('s3')

# List all buckets
response = s3_client.list_buckets()
for bucket in response['Buckets']:
    print(f"Bucket name: {bucket['Name']}")
```


# How to share configuration between workflows
Source: https://docs-3.prefect.io/v3/how-to-guides/configuration/variables



### Create a variable

To create a variable stored in the Prefect backend, use `Variable.set()`.

```python
from prefect.variables import Variable

Variable.set("answer", 42)
```

### Read a variable

To read a variable, use `Variable.get()`.

```python
from prefect.variables import Variable

Variable.get("answer")
```

To read a variable with a fallback value, use `Variable.get(default=...)`.

```python
from prefect.variables import Variable

Variable.get("answer", default=42)
```

### Update a variable

To update a variable, use `Variable.set(value, overwrite=True)`.

```python
from prefect.variables import Variable

Variable.set("answer", 42, overwrite=True)
```

### Delete a variable

To delete a variable, use `Variable.unset()`.

```python
from prefect.variables import Variable

Variable.unset("answer")
```

<Warning>
  **Contextual Behavior**

  In a sync context (such as an `if __name__ == "__main__"` block or simple `def` scope), these methods are used synchronously.
  In an async context (such as an `async def` scope), they are used asynchronously.
</Warning>

<CodeGroup>
  ```python Synchronous

  from prefect import flow
  from prefect.variables import Variable

  @flow(log_prints=True)
  def space_mission_sync(mission_name: str):
      crew = Variable.get("crew_members", default=["Backup1", "Backup2"])
      print(f"Launching {mission_name} with crew: {', '.join(crew)}")

  if __name__ == "__main__":
      Variable.set("crew_members", ["Zaphod", "Arthur", "Trillian"])
      space_mission_sync("Mars Expedition")
  ```

  ```python Asynchronous
  import asyncio
  from prefect import flow
  from prefect.variables import Variable

  @flow(log_prints=True)
  async def space_mission_async(mission_name: str):
      crew = await Variable.get("crew_members", default=["Backup1", "Backup2"])
      print(f"Launching {mission_name} with crew: {', '.join(crew)}")

  if __name__ == "__main__":
      Variable.set("crew_members", ["Zaphod", "Arthur", "Trillian"])
      asyncio.run(space_mission_async("Mars Expedition"))
  ```
</CodeGroup>

### Use variables in `prefect.yaml` deployment steps

In `prefect.yaml` files, variables are expressed as strings wrapped in quotes and double curly brackets:

```
"{{ prefect.variables.my_variable }}"
```

Use variables to templatize deployment steps by
referencing them in the `prefect.yaml` file that creates the deployments.

For example, you can pass in a variable to specify a branch for a git repo in a deployment `pull` step:

```
pull:
- prefect.deployments.steps.git_clone:
    repository: https://github.com/PrefectHQ/hello-projects.git
    branch: "{{ prefect.variables.deployment_branch }}"
```

The `deployment_branch` variable is evaluated at runtime for the deployed flow, allowing changes to variables used in a pull action without updating a deployment directly.


# How to run flows on Coiled
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/coiled

Deploy cloud infrastructure without expertise with Coiled

This page provides a step-by-step guide to run Prefect flows in your own cloud
account using two technologies:

* [Serverless push work pools](/v3/how-to-guides/deployment_infra/serverless), which remove the need to
  host any always-on Prefect worker
* [Coiled](https://coiled.io?utm_source=prefect-docs), which manages cloud VMs such as
  ECS, Cloud Run, and ACI in your account ergonomically and accessibly.

This combination combines the cost efficiency and security
of a cloud VM with easy setup and zero-maintenance infrastructure.

Coiled is a for-profit service, but its free tier is usually enough for most
Prefect users.  Coiled is provided by the makers of Dask.  This video
walks through the steps in this article:

<script src="https://fast.wistia.com/embed/medias/lhn157i193.jsonp" async />

<script src="https://fast.wistia.com/assets/external/E-v1.js" async />

<div class="wistia_responsive_padding" style={{padding: '45% 0 0 0', position: 'relative', width: '100%', margin: 'auto' }}>
  <div class="wistia_responsive_wrapper" style={{height:"100%", left:0, position:"absolute", top:0, width:"100%"}}>
    <div class="wistia_embed wistia_async_lhn157i193 seo=true videoFoam=true" style={{height:"100%", position:"relative", width:"100%"}}>
       
    </div>
  </div>
</div>

## Install and set up accounts

```
pip install prefect coiled prefect-coiled
```

If you haven't used Prefect Cloud before, you'll need to [create a Prefect account](https://app.prefect.cloud) and log in:

```
prefect cloud login
```

If you haven't used Coiled before, you'll need to [create a Coiled account](https://cloud.coiled.io/signup?utm_source=prefect-docs) and log in:

```
coiled login
```

and then connect Coiled to your cloud account (AWS, Google Cloud, or Azure) where Coiled will run your flows. You can either use our interactive setup CLI:

```
coiled setup
```

or via the web app UI at [cloud.coiled.io/settings/setup](https://cloud.coiled.io/settings/setup).

## Create the Prefect push work pool

To create the push work pool:

```
prefect work-pool create --type coiled:push --provision-infra 'example-coiled-pool'
```

## Create flow and create deployment

We write our flow in Python as normal, using the work pool `"example-coiled-pool"` that we created in the last step.

<Tabs>
  <Tab title="example_flow.py">
    ```py
    #example_flow.py
    from prefect import flow, task

    @task
    def f(n):
        return n**2

    @task
    def do_something(x):
        print(x)

    @flow(log_prints=True)
    def my_flow():
        print("Hello from your Prefect flow!")
        X = f.map(list(range(10)))
        do_something(X)
        return X


    if __name__ == "__main__":
        my_flow.deploy(
            name="example-coiled-deployment",
            work_pool_name="example-coiled-pool",
            image="my-image",
        )
    ```
  </Tab>
</Tabs>

```
python example_flow.py
```

Here we specified the Docker image `”my-image”` that you would replace with your own image location.  Alternatively, if you don’t enjoy working with Docker, see the section [Dockerless Execution](#dockerless-execution) below.

Our deployment is now launched and we can execute runs either on the command line using the command printed out:

```
prefect deployment run 'my-flow/example-coiled-deployment'
```

Or by going to the deployment at the URL that Prefect prints in the CLI.

## Dockerless execution

You don’t have to use Docker if you don’t want to.  In our example above we used Docker to build an image locally and push up to our Docker image repository:

{/* pmd-metadata: notest */}

```python
if __name__ == "__main__":
    my_flow.deploy(
        name="example-coiled-deployment",
        work_pool_name="example-coiled-pool",
        image="my-image",                       # <--------
    )
```

This works well if you and your team are familiar with Docker.  However, if you’re not familiar, then it can cause confusion in a variety of ways:

* You may not have Docker installed
* You may be on a Mac, and be generating ARM-based Docker images for Intel-based cloud machines
* You may need to rebuild your Docker image each time you update libraries
* People on your team may not know how Docker works, limiting who can use Prefect

Because of this, Coiled also provides a Dockerless execution process that called [Package Sync](#how-environment-synchronization).  Coiled can automatically inspect your local environment and build a remote cloud environment on the fly.  This can be more ergonomic and accessible to everyone on the team.

To invoke this feature today you need to have both a Python file such as `example_flow.py` with your flow defined, and a `prefect.yaml` deployment configuration file .

<Tabs>
  <Tab title="example_flow.py">
    ```py
    from prefect import flow, task

    @task
    def foo(n):
        return n**2

    @task
    def do_something(x):
        print(x)

    @flow(log_prints=True)
    def my_flow():
        print("Hello from your Prefect flow!")
        X = foo.map(list(range(10)))
        do_something(X)
        return X
    ```
  </Tab>

  <Tab title="prefect.yaml">
    ```yaml
    push:
    - prefect_coiled.deployments.steps.build_package_sync_senv:
        id: coiled_senv

    pull:
    - prefect.deployments.steps.set_working_directory:
        directory: /scratch/batch

    deployments:
    - name: example-coiled-deploy
      build: null
      entrypoint: example_flow:my_flow
      work_pool:
        name: example-coiled-pool
        job_variables:
          software: '{{ coiled_senv.name }}'
    ```
  </Tab>
</Tabs>

You can deploy this flow to Prefect Cloud with the `prefect deploy` command, which makes it ready to run in the cloud.

```
prefect deploy --prefect-file prefect.yaml --all
```

You can then run this flow as follows:

```
prefect deployment run 'my-flow/example-coiled-deployment'
```

If the Docker example above didn’t work for you (for example because you didn’t have Docker installed, or because you have a Mac) then you may find this approach to be more robust.

## Configure hardware

One of the great things about the cloud is that you can experiment with different kinds of machines.  Need lots of memory?  No problem.  A big GPU?  Of course!  Want to try ARM architectures for cost efficiency?  Sure!

If you’re using Coiled’s Dockerless framework you can specify the following variables in your `prefect.yaml` file:

```
job_variables:
  cpu: 16
  memory: 32GB
```

If you’re operating straight from Python you can add these as a keyword in the `.deploy` call.

{/* pmd-metadata: notest */}

```py
my_flow.deploy(
    ...,
    job_variables={"cpu": 16, "memory": "32GB"}
)
```

For a full list of possible configuration options see [Coiled API Documentation](https://docs.coiled.io/user_guide/api.html?utm_source=prefect-docs#coiled-batch-run).

## Extra: scale out

Coiled makes it simple to parallelize individual flows on distributed cloud hardware.  The easiest way to do this is to annotate your Prefect tasks with the `@coiled.function` decorator.

Let’s modify our example from above:

{/* pmd-metadata: notest */}

```python
from prefect import flow, task
import coiled                               # new!

@task
def f(n):
    return n**2

@task
@coiled.function(memory="64 GiB")           # new!
def do_something(x):
    print(x)

@flow(log_prints=True)
def my_flow():
    print("Hello from your Prefect flow!")
    X = f.map(list(range(10)))
```

If you’re using Docker, then you’ll have to rerun the Python script to rebuild the image.  If you’re using the Dockerless approach, then you’ll need to redeploy your flow.

```
prefect deploy --prefect-file prefect.yaml --all
```

And then you can re-run things to see the new machines show up:

```
prefect deployment run 'my-flow/example-coiled-deployment'
```

## Architecture: How does this work?

It’s important to know where work happens so that you can understand the security and cost implications involved.

Coiled runs flows on VMs spun up in *your* cloud account (this is why you had to setup Coiled with your cloud account earlier). This means that …

* You’ll be charged directly by your cloud provider for any computation used.
* Your data stays within your cloud account.  Neither Prefect nor Coiled ever see your data.

Coiled uses raw VM services (like AWS EC2) rather than systems like Kubernetes or Fargate, which has both good and bad tradeoffs:

* **Bad:** there will be a 30-60 second spin-up time on any new flow.
* **Good:** there is no resting infrastructure like a Kubernetes controller or long-standing VM, so there are no standing costs when you aren’t actively running flows.
* **Good:** you can use any VM type available on the cloud, like big memory machines or GPUs.
* **Good:** there is no cloud infrastructure to maintain and keep up-to-date.
* **Good:** Raw VMs are cheap. They cost from $0.02 to $0.05 per CPU-hour.

See [Coiled Documentation](https://docs.coiled.io/user_guide/why.html?utm_source=prefect-docs) to learn more about Coiled architecture and design decisions.

## FAQ

* **Q:** Where do my computations run?<br />
  **A:** Coiled deploys VMs inside your account.<br />

* **Q:** Can anyone see my data?<br />
  **A:** Only you and people in your own cloud account.<br />

* **Q:** When I update my software libraries how does that software get on my cloud machines?<br />
  **A:** If you’re using Docker then you handle this.  Otherwise, when you redeploy your flow Coiled scans your local Python environment and ships a specification of all libraries you’re using, along with any local .py files you have lying around.  These live in a secure S3 bucket while waiting for your VMs.<br />

* **Q:** How much does this cost?<br />
  **A:** You’ll have to pay your cloud provider for compute that you use.  Additionally, if you use more than 10,000 CPU-hours per month, you’ll have to pay Coiled \$0.05 per CPU-hour.<br />
  The average cost we see of Prefect flows is less than \$0.02.<br />

* **Q:** Will this leave expensive things running in my cloud account?<br />
  **A:** No.  We clean everything up very thoroughly (VMs, storage, …)  It is safe to try and cheap to run.<br />

* **Q:** What permissions do I need to give Coiled?<br />
  **A:** In the [cloud setup process above](#install-and-setup-accounts) you give us permissions to do things like turn on and off VMs, set up security groups, and put logs into your cloud logging systems.  You do not give us any access to your data.<br />
  Coiled is happy to talk briefly to your IT group if they’re concerned.  Reach out at [support@coiled.io](mailto:support@coiled.io)<br />


# How to run flows in Docker containers
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/docker

Learn how to execute deployments in isolated Docker containers

In this example, you will set up:

* a Docker [**work pool**](/v3/deploy/infrastructure-concepts/work-pools/): stores the infrastructure configuration for your deployment
* a Docker [**worker**](/v3/deploy/infrastructure-concepts/workers/): process that polls the Prefect API for flow runs to execute as Docker containers
* a [**deployment**](/v3/deploy/index/): a flow that should run according to the configuration on your Docker work pool

Then you can execute your deployment via the Prefect API (through the SDK, CLI, UI, etc).

You must have [Docker](https://docs.docker.com/engine/install/) installed and running on your machine.

<Note>
  **Executing flows in a long-lived container**

  This guide shows how to run a flow in an ephemeral container that is removed after the flow run completes.
  To instead learn how to run flows in a static, long-lived container, see [this](/v3/deploy/static-infrastructure-examples/docker/) guide.
</Note>

### Create a work pool

A work pool provides default infrastructure configurations that all jobs inherit and can override.
You can adjust many defaults, such as the base Docker image, container cleanup behavior, and resource limits.

To set up a **Docker** type work pool with the default values, run:

```bash
prefect work-pool create --type docker my-docker-pool
```

... or create the work pool in the UI.

To confirm the work pool creation was successful, run:

```bash
prefect work-pool ls
```

You should see your new `my-docker-pool` listed in the output.

Next, check that you can see this work pool in your Prefect UI.
Navigate to the **Work Pools** tab and verify that you see `my-docker-pool` listed.
When you click into `my-docker-pool`, you should see a red status icon signifying that this work pool is not ready.

To make the work pool ready, you'll need to start a worker.
We'll show how to do this next.

### Start a worker

Workers are a lightweight polling process that kick off scheduled flow runs on a specific type of infrastructure (such as Docker).
To start a worker on your local machine, open a new terminal and confirm that your virtual environment has `prefect` installed.

Run the following command in this new terminal to start the worker:

```bash
prefect worker start --pool my-docker-pool
```

You should see the worker start.
It's now polling the Prefect API to check for any scheduled flow runs it should pick up and then submit for execution.
You'll see your new worker listed in the UI under the **Workers** tab of the Work Pools page with a recent last polled date.
The work pool should have a `Ready` status indicator.

<Tip>
  **Pro Tip:**

  If `my-docker-pool` does not already exist, the below command will create it for you automatically with the default settings for that work pool type, in this case `docker`.

  ```bash
  prefect worker start --pool my-docker-pool --type docker
  ```
</Tip>

Keep this terminal session active for the worker to continue to pick up jobs.
Since you are running this worker locally, the worker will if you close the terminal.
In a production setting this worker should run as a [daemonized or managed process](/v3/deploy/daemonize-processes/).

## Create the deployment

From the previous steps, you now have:

* A work pool
* A worker

Next, you'll create a deployment from your flow code.

### Automatically bake your code into a Docker image

Create a deployment from Python code by calling the `.deploy` method on a flow:

```python deploy_buy.py
from prefect import flow

@flow(log_prints=True)
def buy():
    print("Buying securities")

if __name__ == "__main__":
    buy.deploy(
        name="my-code-baked-into-an-image-deployment",
        work_pool_name="my-docker-pool",
        image="my_registry/my_image:my_image_tag" # YOUR IMAGE REGISTRY
    )
```

Now, run the script to create a deployment (in future examples this step is omitted for brevity):

```bash
python deploy_buy.py
```

You should see messages in your terminal that Docker is building your image.
When the deployment build succeeds, you will see information in your terminal showing you how to start a worker for your
deployment, and how to run your deployment.
Your deployment is visible on the `Deployments` page in the UI.

By default, `.deploy` builds a Docker image with your flow code baked into it and pushes the image to the
[Docker Hub](https://hub.docker.com/) registry implied by the `image` argument to `.deploy`.

<Note>
  **Authentication to Docker Hub**

  Your environment must be authenticated to your Docker registry to push an image to it.
</Note>

You can specify a registry other than Docker Hub by providing the full registry path in the `image` argument.

<Warning>
  If building a Docker image, your environment with your deployment needs Docker installed and running.
</Warning>

To avoid pushing to a registry, set `push=False` in the `.deploy` method:

```python

if __name__ == "__main__":
    buy.deploy(
        name="my-code-baked-into-an-image-deployment",
        work_pool_name="my-docker-pool",
        image="my_registry/my_image:my_image_tag",
        push=False
    )
```

To avoid building an image, set `build=False` in the `.deploy` method:

```python

if __name__ == "__main__":
    buy.deploy(
        name="my-code-baked-into-an-image-deployment",
        work_pool_name="my-docker-pool",
        image="my_registry/already-built-image:1.0",
        build=False
    )
```

The specified image must be available in your deployment's execution environment for accessible flow code.

Prefect generates a Dockerfile for you that builds an image based off of one of Prefect's published images.
The generated Dockerfile copies the current directory into the Docker image and installs any dependencies listed
in a `requirements.txt` file.

### Automatically build a custom Docker image with a local Dockerfile

If you want to use a custom image, specify the path to your Dockerfile via `DockerImage`:

```python my_flow.py
from prefect import flow
from prefect.docker import DockerImage


@flow(log_prints=True)
def buy():
    print("Buying securities")


if __name__ == "__main__":
    buy.deploy(
        name="my-custom-dockerfile-deployment",
        work_pool_name="my-docker-pool",
        image=DockerImage(
            name="my_image",
            tag="deploy-guide",
            dockerfile="Dockerfile"
    ),
    push=False
)

```

The `DockerImage` object enables image customization.

For example, you can install a private Python package from GCP's artifact registry like this:

1. Create a custom base Dockerfile.

   ```Dockerfile sample.Dockerfile
   FROM python:3.12

   ARG AUTHED_ARTIFACT_REG_URL
   COPY ./requirements.txt /requirements.txt

   RUN pip install --extra-index-url ${AUTHED_ARTIFACT_REG_URL} -r /requirements.txt
   ```

2. Create your deployment with the `DockerImage` class:

   ```python deploy_using_private_package.py
   from prefect import flow
   from prefect.deployments.runner import DockerImage
   from prefect.blocks.system import Secret
   from myproject.cool import do_something_cool


   @flow(log_prints=True)
   def my_flow():
       do_something_cool()


   if __name__ == "__main__":
       artifact_reg_url = Secret.load("artifact-reg-url")

       my_flow.deploy(
           name="my-deployment",
           work_pool_name="my-docker-pool",
           image=DockerImage(
               name="my-image",
               tag="test",
               dockerfile="sample.Dockerfile",
               buildargs={"AUTHED_ARTIFACT_REG_URL": artifact_reg_url.get()},
           ),
       )
   ```

Note that this example used a [Prefect Secret block](/v3/develop/blocks/) to load the URL configuration for
the artifact registry above.

See all the optional keyword arguments for the [`DockerImage` class](https://docker-py.readthedocs.io/en/stable/images.html#docker.models.images.ImageCollection.build).

<Tip>
  **Default Docker namespace**

  You can set the `PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE` setting to append a default Docker namespace to all images
  you build with `.deploy`. This is helpful if you use a private registry to store your images.

  To set a default Docker namespace for your current profile run:

  ```bash
  prefect config set PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE=<docker-registry-url>/<organization-or-username>
  ```

  Once set, you can omit the namespace from your image name when creating a deployment:

  ```python with_default_docker_namespace.py
  if __name__ == "__main__":
      buy.deploy(
          name="my-code-baked-into-an-image-deployment",
          work_pool_name="my-docker-pool",
          image="my_image:my_image_tag"
      )
  ```

  The above code builds an image with the format `<docker-registry-url>/<organization-or-username>/my_image:my_image_tag`
  when `PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE` is set.
</Tip>

### Store your code in git-based cloud storage

While baking code into Docker images is a popular deployment option, many teams store their workflow code in git-based
storage, such as GitHub, Bitbucket, or GitLab.

If you don't specify an `image` argument for `.deploy`, you must specify where to pull the flow code from at runtime
with the `from_source` method.

Here's how to pull your flow code from a GitHub repository:

```python git_storage.py
from prefect import flow

if __name__ == "__main__":
    flow.from_source(
        "https://github.com/my_github_account/my_repo/my_file.git",
        entrypoint="flows/no-image.py:hello_world",
    ).deploy(
        name="no-image-deployment",
        work_pool_name="my-docker-pool",
        build=False
    )
```

The `entrypoint` is the path to the file the flow is located in and the function name, separated by a colon.

See the [Store flow code](/v3/deploy/infrastructure-concepts/store-flow-code/) guide for more flow code storage options.

### Additional configuration with `.deploy`

Next, see deployment configuration options.

To pass parameters to your flow, you can use the `parameters` argument in the `.deploy` method. Just pass in a dictionary of
key-value pairs.

```python pass_params.py
from prefect import flow


@flow
def hello_world(name: str):
    print(f"Hello, {name}!")


if __name__ == "__main__":
    hello_world.deploy(
        name="pass-params-deployment",
        work_pool_name="my-docker-pool",
        parameters=dict(name="Prefect"),
        image="my_registry/my_image:my_image_tag",
    )
```

The `job_variables` parameter allows you to fine-tune the infrastructure settings for a deployment.
The values passed in override default values in the specified work pool's
[base job template](/v3/deploy/infrastructure-concepts/work-pools/#base-job-template).

You can override environment variables, such as `image_pull_policy` and `image`, for a specific deployment with the `job_variables`
argument.

```python job_var_image_pull.py
if __name__ == "__main__":
    get_repo_info.deploy(
        name="my-deployment-never-pull",
        work_pool_name="my-docker-pool",
        job_variables={"image_pull_policy": "Never"},
        image="my-image:my-tag",
        push=False
    )
```

Similarly, you can override the environment variables specified in a work pool through the `job_variables` parameter:

```python job_var_env_vars.py
if __name__ == "__main__":
    get_repo_info.deploy(
        name="my-deployment-never-pull",
        work_pool_name="my-docker-pool",
        job_variables={"env": {"EXTRA_PIP_PACKAGES": "boto3"} },
        image="my-image:my-tag",
        push=False
    )
```

The dictionary key "EXTRA\_PIP\_PACKAGES" denotes a special environment variable that Prefect uses to install additional
Python packages at runtime.
This approach is an alternative to building an image with a custom `requirements.txt` copied into it.

See [Override work pool job variables](/v3/deploy/infrastructure-concepts/customize) for more information about how to customize these variables.

### Work with multiple deployments with `deploy`

Create multiple deployments from one or more Python files that use `.deploy`.
You can manage these deployments independently of one another to deploy the same flow with different configurations
in the same codebase.

To create multiple deployments at once, use the `deploy` function, which is analogous to the `serve` function:

```python
from prefect import deploy, flow


@flow(log_prints=True)
def buy():
    print("Buying securities")


if __name__ == "__main__":
    deploy(
        buy.to_deployment(name="dev-deploy", work_pool_name="my-docker-pool"),
        buy.to_deployment(name="prod-deploy", work_pool_name="my-other-docker-pool"),
        image="my-registry/my-image:dev",
        push=False,
    )
```

In the example above you created two deployments from the same flow, but with different work pools.
Alternatively, you can create two deployments from different flows:

```python
from prefect import deploy, flow


@flow(log_prints=True)
def buy():
    print("Buying securities.")


@flow(log_prints=True)
def sell():
    print("Selling securities.")


if __name__ == "__main__":
    deploy(
        buy.to_deployment(name="buy-deploy"),
        sell.to_deployment(name="sell-deploy"),
        work_pool_name="my-docker-pool",
        image="my-registry/my-image:dev",
        push=False,
    )
```

In the example above, the code for both flows is baked into the same image.

You can specify one or more flows to pull from a remote location at runtime with the `from_source` method.
Here's an example of deploying two flows, one defined locally and one defined in a remote repository:

```python
from prefect import deploy, flow


@flow(log_prints=True)
def local_flow():
    print("I'm a flow!")


if __name__ == "__main__":
    deploy(
        local_flow.to_deployment(name="example-deploy-local-flow"),
        flow.from_source(
            source="https://github.com/org/repo.git",
            entrypoint="flows.py:my_flow",
        ).to_deployment(
            name="example-deploy-remote-flow",
        ),
        work_pool_name="my-docker-pool",
        image="my-registry/my-image:dev",
    )
```

You can pass any number of flows to the `deploy` function.
This is useful if using a monorepo approach to your workflows.

## Learn more

* [Deploy flows on Kubernetes](/v3/how-to-guides/deployment_infra/kubernetes/)
* [Deploy flows on serverless infrastructure](/v3/how-to-guides/deployment_infra/serverless)
* [Daemonize workers](/v3/deploy/daemonize-processes/)


# How to run flows on Kubernetes
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/kubernetes

Learn how to run flows on Kubernetes using containers.

This guide explains how to run flows on Kubernetes.
Though much of the guide is general to any Kubernetes cluster, it focuses on
Amazon Elastic Kubernetes Service (EKS). Prefect is tested against
Kubernetes 1.26.0 and newer minor versions.

## Prerequisites

1. A Prefect Cloud account
2. A cloud provider (AWS, GCP, or Azure) account
3. Python and Prefect [installed](/v3/get-started/install/)
4. Helm [installed](https://helm.sh/docs/intro/install/)
5. Kubernetes CLI (kubectl)[installed](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
6. Admin access for Prefect Cloud and your cloud provider. You can downgrade it after this setup.

## Create a cluster

If you already have one, skip ahead to the next section.

<Tabs>
  <Tab title="AWS">
    One easy way to get set up with a cluster in EKS is with [`eksctl`](https://eksctl.io/).
    Node pools can be backed by either EC2 instances or FARGATE.
    Choose FARGATE so there's less to manage.
    The following command takes around 15 minutes and must not be interrupted:

    ```bash
    # Replace the cluster name with your own value
    eksctl create cluster --fargate --name <CLUSTER-NAME>

    # Authenticate to the cluster.
    aws eks update-kubeconfig --name <CLUSTER-NAME>
    ```
  </Tab>

  <Tab title="GCP">
    You can get a GKE cluster up and running with a few commands using the
    [`gcloud` CLI](https://cloud.google.com/sdk/docs/install).
    This builds a bare-bones cluster that is accessible over the open
    internet - but it should **not** be used in a production environment.
    To deploy the cluster, your project must have a VPC network configured.

    First, authenticate to GCP by setting the following configuration options:

    ```bash
    # Authenticate to gcloud
    gcloud auth login

    # Specify the project & zone to deploy the cluster to
    # Replace the project name with your GCP project name
    gcloud config set project <GCP-PROJECT-NAME>
    gcloud config set compute/zone <AVAILABILITY-ZONE>
    ```

    Next, deploy the cluster. This command takes \~15 minutes to complete.
    Once the cluster has been created, authenticate to the cluster.

    ```bash
    # Create cluster
    # Replace the cluster name with your own value
    gcloud container clusters create <CLUSTER-NAME> --num-nodes=1 \
    --machine-type=n1-standard-2

    # Authenticate to the cluster
    gcloud container clusters <CLUSTER-NAME> --region <AVAILABILITY-ZONE>
    ```

    <Warning>
      **GCP potential errors**

      ```
      ERROR: (gcloud.container.clusters.create) ResponseError: code=400, message=Service account "000000000000-compute@developer.gserviceaccount.com" is disabled.
      ```

      * You must enable the default service account in the IAM console, or
        specify a different service account with the appropriate permissions.

      ```
      creation failed: Constraint constraints/compute.vmExternalIpAccess violated for project 000000000000. Add instance projects/<GCP-PROJECT-NAME>/zones/us-east1-b/instances/gke-gke-guide-1-default-pool-c369c84d-wcfl to the constraint to use external IP with it."
      ```

      * Organization policy blocks creation of external (public) IPs. Override
        this policy (if you have the appropriate permissions) under the `Organizational Policy`
        page within IAM.
    </Warning>
  </Tab>

  <Tab title="Azure">
    Create an AKS cluster using the
    [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/get-started-with-azure-cli),
    or use the Cloud Shell directly from the Azure portal [shell.azure.com](https://shell.azure.com).

    First, authenticate to Azure if not already done.

    ```bash
      az login
    ```

    Next, deploy the cluster - this command takes \~4 minutes to complete.
    Once the cluster is created, authenticate to the cluster.

    ```bash

      # Create a Resource Group at the desired location, e.g. westus
      az group create --name <RESOURCE-GROUP-NAME> --location <LOCATION>

      # Create a kubernetes cluster with default kubernetes version, default SKU load balancer (Standard) and default vm set type (VirtualMachineScaleSets)
      az aks create --resource-group <RESOURCE-GROUP-NAME> --name <CLUSTER-NAME>

      # Configure kubectl to connect to your Kubernetes cluster
      az aks get-credentials --resource-group <RESOURCE-GROUP-NAME> --name <CLUSTER-NAME>

      # Verify the connection by listing the cluster nodes
      kubectl get nodes
    ```
  </Tab>
</Tabs>

## Create a container registry

Besides a cluster, the other critical resource is a container registry.
A registry is not strictly required, but in most cases you'll want to use custom
images and/or have more control over where images are stored.
If you already have a registry, skip ahead to the next section.

<Tabs>
  <Tab title="AWS">
    Create a registry using the AWS CLI and authenticate the docker daemon to
    that registry:

    ```bash
    # Replace the image name with your own value
    aws ecr create-repository --repository-name <IMAGE-NAME>

    # Login to ECR
    # Replace the region and account ID with your own values
    aws ecr get-login-password --region <REGION> | docker login \
      --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com
    ```
  </Tab>

  <Tab title="GCP">
    Create a registry using the gcloud CLI and authenticate the docker daemon to
    that registry:

    ```bash
    # Create artifact registry repository to host your custom image
    # Replace the repository name with your own value; it can be the
    # same name as your image
    gcloud artifacts repositories create <REPOSITORY-NAME> \
    --repository-format=docker --location=us

    # Authenticate to artifact registry
    gcloud auth configure-docker us-docker.pkg.dev
    ```
  </Tab>

  <Tab title="Azure">
    Create a registry using the Azure CLI and authenticate the docker daemon to
    that registry:

    ```bash
    # Name must be a lower-case alphanumeric
    # Tier SKU can easily be updated later, e.g. az acr update --name <REPOSITORY-NAME> --sku Standard
    az acr create --resource-group <RESOURCE-GROUP-NAME> \
      --name <REPOSITORY-NAME> \
      --sku Basic

    # Attach ACR to AKS cluster
    # You need Owner, Account Administrator, or Co-Administrator role on your Azure subscription as per Azure docs
    az aks update --resource-group <RESOURCE-GROUP-NAME> --name <CLUSTER-NAME> --attach-acr <REPOSITORY-NAME>

    # You can verify AKS can now reach ACR
    az aks check-acr --resource-group RESOURCE-GROUP-NAME> --name <CLUSTER-NAME> --acr <REPOSITORY-NAME>.azurecr.io

    ```
  </Tab>
</Tabs>

## Create a Kubernetes work pool

[Work pools](/v3/deploy/infrastructure-concepts/work-pools/) allow you to manage deployment
infrastructure.
This section shows you how to configure the default values for your
Kubernetes base job template.
These values can be overridden by individual deployments.

Switch to the Prefect Cloud UI to create a new Kubernetes work pool.
(Alternatively, you could use the Prefect CLI to create a work pool.)

1. Click on the **Work Pools** tab on the left sidebar
2. Click the **+** button at the top of the page
3. Select **Kubernetes** as the work pool type
4. Click **Next** to configure the work pool settings
5. Set the `namespace` field to `prefect`

<Note>
  If you set a different namespace, use your selected namespace instead of `prefect` in all commands below.
</Note>

You may come back to this page to configure the work pool options at any time.

### Configure work pool options

Here are some popular configuration options.

**Environment Variables**

Add environment variables to set when starting a flow run.
If you are using a Prefect-maintained image and haven't overwritten the image's
entrypoint, you can specify Python packages to install at runtime with `{"EXTRA_PIP_PACKAGES":"my_package"}`.
For example `{"EXTRA_PIP_PACKAGES":"pandas==1.2.3"}` installs pandas version 1.2.3.
Alternatively, you can specify package installation in a custom Dockerfile, which
allows you to use image caching.
As shown below, Prefect can help create a Dockerfile with your flow code and the
packages specified in a `requirements.txt` file baked in.

**Namespace**

Set the Kubernetes namespace to create jobs within, such as `prefect`. By default, set
to **default**.

**Image**

Specify the Docker container image for created jobs.
If not set, the latest Prefect 3 image is used (for example, `prefecthq/prefect:3-latest`).
You can override this on each deployment through `job_variables`.

**Image Pull Policy**

Select from the dropdown options to specify when to pull the image.
When using the `IfNotPresent` policy, make sure to use unique image tags, or
old images may get cached on your nodes.

**Finished Job TTL**

Number of seconds before finished jobs are automatically cleaned up by the Kubernetes
controller.
Set to 60 so completed flow runs are cleaned up after a minute.

**Pod Watch Timeout Seconds**

Number of seconds for pod creation to complete before timing out.
Consider setting to 300, especially if using a **serverless** type node pool, as
these tend to have longer startup times.

**Kubernetes cluster config**

Specify a KubernetesClusterConfig block to configure the Kubernetes cluster for job creation.
In most cases, leave the cluster config blank since the worker should already have appropriate
access and permissions.
We recommend using this setting when deploying a worker to a cluster that differs from the one
executing the flow runs.

<Note>
  **Advanced Settings**

  Modify the default base job template to add other fields or delete existing
  fields.

  Select the **Advanced** tab and edit the JSON representation of the base job template.

  For example, to set a CPU request, add the following section under variables:

  ```json
  "cpu_request": {
    "title": "CPU Request",
    "description": "The CPU allocation to request for this pod.",
    "default": "default",
    "type": "string"
  },
  ```

  Next add the following to the first `containers` item under `job_configuration`:

  ```json
  ...
  "containers": [
    {
      ...,
      "resources": {
        "requests": {
          "cpu": "{{ cpu_request }}"
        }
      }
    }
  ],
  ...
  ```

  Running deployments with this work pool will request the specified CPU.
</Note>

After configuring the work pool settings, move to the next screen.

Give the work pool a name and save.

Your new Kubernetes work pool should appear in the list of work pools.

## Create a Prefect Cloud API key

If you already have a Prefect Cloud API key, you can skip these steps.

To create a Prefect Cloud API key:

1. Log in to the Prefect Cloud UI.
2. Click on your profile avatar picture in the top right corner.
3. Click on your name to go to your profile settings.
4. In the left sidebar, click on [API Keys](https://app.prefect.cloud/my/api-keys).
5. Click the **+** button to create a new API key.
6. Securely store the API key, ideally using a password manager.

## Deploy a worker using Helm

After you create a cluster and work pool, the next step is to deploy a worker.
The worker sets up the necessary Kubernetes infrastructure to run your flows.
The recommended method for deploying a worker is with the [Prefect Helm Chart](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker).

### Add the Prefect Helm repository

Add the Prefect Helm repository to your Helm client:

```bash
helm repo add prefect https://prefecthq.github.io/prefect-helm
helm repo update
```

### Create a namespace

Create a new namespace in your Kubernetes cluster to deploy the Prefect worker:

```bash
kubectl create namespace prefect
```

### Create a Kubernetes secret for the Prefect API key

```bash
kubectl create secret generic prefect-api-key \
--namespace=prefect --from-literal=key=your-prefect-cloud-api-key
```

### Configure Helm chart values

Create a `values.yaml` file to customize the Prefect worker configuration.
Add the following contents to the file:

```yaml
worker:
  cloudApiConfig:
    accountId: <target account ID>
    workspaceId: <target workspace ID>
  config:
    workPool: <target work pool name>
```

These settings ensure that the worker connects to the proper account, workspace,
and work pool.

View your Account ID and Workspace ID in your browser URL when logged into Prefect Cloud.
For example: \<[https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here>](https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here>).

### Create a Helm release

Install the Prefect worker using the Helm chart with your custom `values.yaml` file:

```bash
helm install prefect-worker prefect/prefect-worker \
  --namespace=prefect \
  -f values.yaml
```

### Verify deployment

Check the status of your Prefect worker deployment:

```bash
kubectl get pods -n prefect
```

## Define a flow

Start simple with a flow that just logs a message.
In a directory named `flows`, create a file named `hello.py` with the following contents:

```python
from prefect import flow, tags
from prefect.logging import get_run_logger

@flow
def hello(name: str = "Marvin"):
    logger = get_run_logger()
    logger.info(f"Hello, {name}!")

if __name__ == "__main__":
    with tags("local"):
        hello()
```

Run the flow locally with `python hello.py` to verify that it works.
Use the `tags` context manager to tag the flow run as `local`.
This step is not required, but does add some helpful metadata.

## Define a Prefect deployment

Prefect has two recommended options for creating a deployment with dynamic infrastructure.
You can define a deployment in a Python script using the `flow.deploy` mechanics or in a
`prefect.yaml` definition file.
The `prefect.yaml` file currently allows for more customization in terms of push and pull
steps.

To learn about the Python deployment creation method with `flow.deploy` see
[Workers](/v3/how-to-guides/deployment_infra/docker).

The [`prefect.yaml`](/v3/deploy/infrastructure-concepts/prefect-yaml/#managing-deployments) file is used
by the `prefect deploy` command to deploy your flows.
As a part of that process it also builds and pushes your image.
Create a new file named `prefect.yaml` with the following contents:

```yaml
# Generic metadata about this project
name: flows
prefect-version: 3.0.0

# build section allows you to manage and build docker images
build:
- prefect_docker.deployments.steps.build_docker_image:
    id: build-image
    requires: prefect-docker>=0.4.0
    image_name: "{{ $PREFECT_IMAGE_NAME }}"
    tag: latest
    dockerfile: auto
    platform: "linux/amd64"

# push section allows you to manage if and how this project is uploaded to remote locations
push:
- prefect_docker.deployments.steps.push_docker_image:
    requires: prefect-docker>=0.4.0
    image_name: "{{ build-image.image_name }}"
    tag: "{{ build-image.tag }}"

# pull section allows you to provide instructions for cloning this project in remote
locations
pull:
- prefect.deployments.steps.set_working_directory:
    directory: /opt/prefect/flows

# the definitions section allows you to define reusable components for your deployments
definitions:
  tags: &common_tags
    - "eks"
  work_pool: &common_work_pool
    name: "kubernetes"
    job_variables:
      image: "{{ build-image.image }}"

# the deployments section allows you to provide configuration for deploying flows
deployments:
- name: "default"
  tags: *common_tags
  schedule: null
  entrypoint: "flows/hello.py:hello"
  work_pool: *common_work_pool

- name: "arthur"
  tags: *common_tags
  schedule: null
  entrypoint: "flows/hello.py:hello"
  parameters:
    name: "Arthur"
  work_pool: *common_work_pool
```

We define two deployments of the `hello` flow: `default` and `arthur`.
By specifying `dockerfile: auto`, Prefect automatically creates a dockerfile
that installs any `requirements.txt` and copies over the current directory.

You can pass a custom Dockerfile instead with `dockerfile: Dockerfile` or
`dockerfile: path/to/Dockerfile`.
We are specifically building for the `linux/amd64` platform.
This specification is often necessary when images are built on Macs with M series chips
but run on cloud provider instances.

<Note>
  **Deployment specific build, push, and pull**

  You can override the build, push, and pull steps for each deployment.
  This allows for more custom behavior, such as specifying a different image for each
  deployment.
</Note>

Define your requirements in a `requirements.txt` file:

```
prefect>=3.0.0
prefect-docker>=0.4.0
prefect-kubernetes>=0.3.1
```

The directory should now look something like this:

```
.
├── prefect.yaml
└── flows
    ├── requirements.txt
    └── hello.py
```

### Tag images with a Git SHA

If your code is stored in a GitHub repository, it's good practice to tag your images
with the Git SHA of the code used to build it.
Do this in the `prefect.yaml` file with a few minor modifications, since it's not yet
an option with the Python deployment creation method.

Use the `run_shell_script` command to grab the SHA and pass it to the `tag`
parameter of `build_docker_image`:

```yaml
build:
- prefect.deployments.steps.run_shell_script:
    id: get-commit-hash
    script: git rev-parse --short HEAD
    stream_output: false
- prefect_docker.deployments.steps.build_docker_image:
    id: build-image
    requires: prefect-docker>=0.4.0
    image_name: "{{ $PREFECT_IMAGE_NAME }}"
    tag: "{{ get-commit-hash.stdout }}"
    dockerfile: auto
    platform: "linux/amd64"
```

Set the SHA as a tag for easy identification in the UI:

```yaml
definitions:
  tags: &common_tags
    - "eks"
    - "{{ get-commit-hash.stdout }}"
  work_pool: &common_work_pool
    name: "kubernetes"
    job_variables:
      image: "{{ build-image.image }}"
```

## Authenticate to Prefect

Before deploying the flows to Prefect, you need to authenticate through the Prefect CLI.
You also need to ensure that all of your flow's dependencies are present at `deploy` time.

This example uses a virtual environment to ensure consistency across environments.

```bash
# Create a virtualenv & activate it
virtualenv prefect-demo
source prefect-demo/bin/activate

# Install dependencies of your flow
prefect-demo/bin/pip install -r requirements.txt

# Authenticate to Prefect & select the appropriate
# workspace to deploy your flows to
prefect-demo/bin/prefect cloud login
```

## Deploy the flows

You're ready to deploy your flows to build your images.
The image name determines its registry.
You have configured our `prefect.yaml` file to get the image name from the
`PREFECT_IMAGE_NAME` environment variable, so set that first:

<Tabs>
  <Tab title="AWS">
    ```bash
    export PREFECT_IMAGE_NAME=<AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<IMAGE-NAME>
    ```
  </Tab>

  <Tab title="GCP">
    ```bash
    export PREFECT_IMAGE_NAME=us-docker.pkg.dev/<GCP-PROJECT-NAME>/<REPOSITORY-NAME>/<IMAGE-NAME>
    ```
  </Tab>

  <Tab title="Azure">
    ```bash
    export PREFECT_IMAGE_NAME=<REPOSITORY-NAME>.azurecr.io/<IMAGE-NAME>
    ```
  </Tab>
</Tabs>

To deploy your flows, ensure your Docker daemon is running. Deploy all the
flows with `prefect deploy --all` or deploy them individually by name: `prefect deploy
-n hello/default` or `prefect deploy -n hello/arthur`.

## Run the flows

Once the deployments are successfully created, you can run them from the UI or the CLI:

```bash
prefect deployment run hello/default
prefect deployment run hello/arthur
```

You can now check the status of your two deployments in the UI.


# How to manage work pools
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/manage-work-pools

Configure Prefect work pools using the CLI, Terraform, or REST API

export const API = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect API</a>.</p>;

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

export const work_pools = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/work-pool",
  api: "https://app.prefect.cloud/api/docs#tag/Work-Pools",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/work_pool"
};

export const CLI = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect CLI</a>.</p>;

You can configure work pools by using the Prefect UI.

To manage work pools in the UI, click the **Work Pools** icon. This displays a list of currently configured work pools.

<img src="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/work-pool-list.png?fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=16ad4508be0804e4a593a3091ce3182f" alt="The UI displays a list of configured work pools" data-og-width="2540" width="2540" data-og-height="1410" height="1410" data-path="v3/img/ui/work-pool-list.png" srcset="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/work-pool-list.png?w=280&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=a4d31b24491f63d340add8f004fd6879 280w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/work-pool-list.png?w=560&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=af91a2bb291950047fab3e13d37ea934 560w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/work-pool-list.png?w=840&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=1eae26672cbbb9d91147b5bb5124fbcd 840w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/work-pool-list.png?w=1100&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=b1e4bbcdabf67810064dc2de55febd6b 1100w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/work-pool-list.png?w=1650&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=2c6c3b625e5e86ce76329b0b5aab601d 1650w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/work-pool-list.png?w=2500&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=9d2753ab0c8cd0dea186414706b608f4 2500w" data-optimize="true" data-opv="2" />

Select the **+** button to create a new work pool. You can specify the details about infrastructure created for this work pool.

## Using the CLI

<CLI name="work pools" href={work_pools.cli} />

```bash
prefect work-pool create [OPTIONS] NAME
```

`NAME` is a required, unique name for the work pool.

Optional configuration parameters to filter work on the pool include:

<Tip>
  **Managing work pools in CI/CD**

  Version control your base job template by committing it as a JSON file to a git repository and control updates to your
  work pools' base job templates with the `prefect work-pool update` command in your CI/CD pipeline.

  For example, use the following command to update a work pool's base job template to the contents of a file named `base-job-template.json`:

  ```bash
  prefect work-pool update --base-job-template base-job-template.json my-work-pool
  ```
</Tip>

### List available work pools

```bash
prefect work-pool ls
```

### Inspect a work pool

```bash
prefect work-pool inspect 'test-pool'
```

### Preview scheduled work

```bash
prefect work-pool preview 'test-pool' --hours 12
```

### Pause a work pool

```bash
prefect work-pool pause 'test-pool'
```

### Resume a work pool

```bash
prefect work-pool resume 'test-pool'
```

### Delete a work pool

```bash
prefect work-pool delete 'test-pool'
```

<Note>
  **Pausing a work pool does not pause deployment schedules**
</Note>

### Manage concurrency for a work pool

Set concurrency:

```bash
prefect work-pool set-concurrency-limit [LIMIT] [POOL_NAME]
```

Clear concurrency:

```bash
prefect work-pool clear-concurrency-limit [POOL_NAME]
```

### Base job template

View default base job template:

```bash
prefect work-pool get-default-base-job-template --type process
```

Example `prefect.yaml`:

```yaml
deployments:
- name: demo-deployment
  entrypoint: demo_project/demo_flow.py:some_work
  work_pool:
    name: above-ground  
    job_variables:
        stream_output: false
```

<Tip>
  **Advanced customization of the base job template**

  For advanced use cases, create work pools with fully customizable job templates. This customization is available when
  creating or editing a work pool on the 'Advanced' tab within the UI or when updating a work pool via the Prefect CLI.

  Advanced customization is useful anytime the underlying infrastructure supports a high degree of customization.
  In these scenarios a work pool job template allows you to expose a minimal and easy-to-digest set of options to deployment authors.
  Additionally, these options are the *only* customizable aspects for deployment infrastructure, which are useful for restricting
  capabilities in secure environments. For example, the `kubernetes` worker type allows users to specify a custom job template\
  to configure the manifest that workers use to create jobs for flow execution.

  See more information about [overriding a work pool's job variables](/v3/deploy/infrastructure-concepts/customize).
</Tip>

## Using Terraform

<TF name="work pools" href={work_pools.tf} />

## Using the REST API

<API name="work pools" href={work_pools.api} />

## Further reading

* [Work pools](/v3/concepts/work-pools) concept page
* [Customize job variables](/v3/deploy/infrastructure-concepts/customize) page


# How to run flows on Prefect Managed infrastructure
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/managed

Learn how Prefect runs deployments on Prefect's infrastructure.

<span class="badge cloud" /> Prefect Cloud can run your flows on your behalf with Prefect Managed work pools.

Flows that run with this work pool do not require a worker or cloud provider
account—Prefect handles the infrastructure and code execution for you.

Managed execution is a great option for users who want to get started quickly, with no infrastructure setup.

## Create a managed deployment

1. Create a new work pool of type Prefect Managed in the UI or the CLI.
   Use this command to create a new work pool using the CLI:

   ```bash
   prefect work-pool create my-managed-pool --type prefect:managed
   ```

2. Create a deployment using the flow `deploy` method or `prefect.yaml`.
   Specify the name of your managed work pool, as shown in this example that uses the `deploy` method:

   ```python managed-execution.py
   from prefect import flow

   if __name__ == "__main__":
       flow.from_source(
           source="https://github.com/prefecthq/demo.git",
           entrypoint="flow.py:my_flow",
       ).deploy(
           name="test-managed-flow",
           work_pool_name="my-managed-pool",
       )
   ```

3. With your [CLI authenticated to your Prefect Cloud workspace](/v3/how-to-guides/cloud/manage-users/api-keys), run the script to create your deployment:

   ```bash
   python managed-execution.py
   ```

4. Run the deployment from the UI or from the CLI.

   This process runs a flow on remote infrastructure without any infrastructure setup, starting a worker, or requiring a cloud provider account.

## Add dependencies

Prefect can install Python packages in the container that runs your flow at runtime.
Specify these dependencies in the **Pip Packages** field in the UI, or by configuring
`job_variables={"pip_packages": ["pandas", "prefect-aws"]}` in your deployment creation like this:

```python
from prefect import flow

if __name__ == "__main__":
    flow.from_source(
        source="https://github.com/prefecthq/demo.git",
        entrypoint="flow.py:my_flow",
    ).deploy(
        name="test-managed-flow",
        work_pool_name="my-managed-pool",
        job_variables={"pip_packages": ["pandas", "prefect-aws"]}
    )
```

Alternatively, you can create a `requirements.txt` file and reference it in your [prefect.yaml pull step](/v3/deploy/infrastructure-concepts/prefect-yaml#utility-steps).

## Networking

### Static Outbound IP addresses

Flows running on Prefect Managed infrastructure can be assigned static IP addresses on outbound traffic, which will pose as the `source` address for requests interacting with your system or database.

Include these `source` addresses in your firewall rules to explicitly allow flows to communicate with your environment.

* `184.73.85.134`
* `52.4.218.198`
* `44.217.117.74`

### Images

Managed execution requires that you run an official Prefect Docker image, such as `prefecthq/prefect:3-latest`.
However, as noted above, you can install Python package dependencies at runtime.
If you need to use your own image, we recommend using another type of work pool.

### Code storage

You must store flow code in an accessible remote location.
Prefect supports git-based cloud providers such as GitHub, Bitbucket, or GitLab.
Remote block-based storage is also supported, so S3, GCS, and Azure Blob are additional code storage options.

### Resources & Limitations

All flow runs receive:

* 4vCPUs
* 16GB of RAM
* 128GB of ephemeral storage

Maximum flow run time is limited to 24 hours.

Every account has a compute usage limit per workspace that resets monthly. Compute used is defined as the duration
between compute startup and teardown, rounded up to the nearest minute. This is approximately, although not exactly,
the duration of a flow run going from `PENDING` to `COMPLETED`.

## Next steps

Read more about creating deployments in [Run flows in Docker containers](/v3/how-to-guides/deployment_infra/docker).

For more control over your infrastructure, such as the ability to run
custom Docker images, [serverless push work pools](/v3/how-to-guides/deployment_infra/serverless)
are a good option.


# How to run flows on Modal
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/modal

Learn how to use Modal as a push work pool to schedule, run, and debug your Prefect flows

Prefect is the world's best orchestrator.
Modal is the world's best serverless compute framework.
It only makes sense that they would fit together perfectly.

In this tutorial, you'll build your first Prefect deployment that runs on Modal every hour, and create a scalable framework to grow your project.

Here's an architecture diagram which shows what you'll build.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/0.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=4a4e18e1bc8d72a7e70443c7c52dba23" alt="image.png" data-og-width="741" width="741" data-og-height="677" height="677" data-path="v3/img/tutorials/modal/0.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/0.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1d4079a8bbd00d84f53c5e7828de774f 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/0.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=4adb16c8ed49598d7c0f84e19bc436eb 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/0.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=3685e0064c4dfb5ccd388e7b100bc19f 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/0.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=c4f61b69e53770c507493312b09b1f1a 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/0.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1ba7b78f440d2815c0334ad2a7ed1a05 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/0.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=0b1876b858a9baa43934039d1268b7b5 2500w" data-optimize="true" data-opv="2" />

You'll build a full serverless infrastructure framework for scheduling and provisioning workflows.
GitHub will act as the source of truth, Prefect will be the orchestrator, and Modal will be the serverless infrastructure.
You'll only pay for the Modal CPU time you use.

First, here's a recap of some important terms:

| Term         | Definition                                                                                                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Flow*       | A Python function in a file, decorated with `@flow`, that is an entrypoint to perform a task in Prefect.                                                                         |
| *Run*        | An instance of a flow, executed at a specific time with a specific payload.                                                                                                      |
| *Deployment* | A manifest around a flow, including where it should run, when it should run, and any variables it needs to run. A deployment can schedule your flows, creating runs when needed. |
| *Work Pool*  | An interface to the hardware used to run a given flow.                                                                                                                           |

## Prerequisites

* A free [Prefect Cloud](https://app.prefect.cloud/auth/sign-in) account.
* A free [Modal](https://modal.com/signup?next=%2Fapps) account.

## Create a GitHub repository

Create a GitHub repository containing your Prefect flows.
You can reference the [Ben-Epstein/prefect-modal](https://github.com/Ben-Epstein/prefect-modal) repository for a complete example.
Your repository should have a `prefect.yaml` deployment configuration file, standard Python tooling, and CI/CD.

1. Start by creating the following `Makefile` to keep things easy:

   ```makefile Makefile
   export PYTHONPATH = .venv

   .PHONY: uv
   uv:
     pip install --upgrade 'uv>=0.5.6,<0.6'
     uv venv

   setup:
     @if [ ! -d ".venv" ] || ! command -v uv > /dev/null; then \
       echo "UV not installed or .venv does not exist, running uv"; \
       make uv; \
     fi
     @if [ ! -f "uv.lock" ]; then \
       echo "Can't find lockfile. Locking"; \
       uv lock; \
     fi
     uv sync --all-extras --all-groups
     uv pip install --no-deps -e .
   ```

2. Set up and manage your environment with `uv`.

   ```bash
   make setup
   ```

3. Create your Python project.

   ```bash
   uv init --lib --name prefect_modal --python 3.12
   ```

   <Info>
     If `uv` creates a `python-version` that is pinned to a micro version (for example, 3.12.6), remove the micro version (for example, 3.12) to avoid downstream issues.
   </Info>

4. Add your dependencies:

   ```bash
   uv add modal 'prefect[github]'
   ```

5. Add the following to the end of the `pyproject.toml` file created by `uv`:

   ```makefile
   [tool.hatch.build.targets.wheel]
   packages = ["src/prefect_modal"]
   ```

6. Initialize the Prefect environment:

   ```bash
   uv run prefect init
   ```

   You will be prompted to choose your code storage; select `git` to store code within a git repository.

   <img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/1.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=3998fff07e902af8b6bc8539593bce2e" alt="image.png" data-og-width="1012" width="1012" data-og-height="223" height="223" data-path="v3/img/tutorials/modal/1.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/1.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=c40db62770bb19fc82af916649519620 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/1.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=0b88362bb029a8bed5a11eeef22ab89e 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/1.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=dd360472072e35b16f57974f1e60ad5c 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/1.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=6d5e6b8fa00b13be84ac36d2bc050f47 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/1.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1af2c7cc3000444608c9070e928f254f 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/1.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=b3fddb39729eedb5bc44a76bda0bbe15 2500w" data-optimize="true" data-opv="2" />

7. Because this is meant to be a scalable repository, create a submodule just for your workflows.

   ```bash
   mkdir src/prefect_modal/flows
   touch src/prefect_modal/flows/__init__.py
   ```

Now that your repository is set up, take a look at the `prefect.yaml` file that you generated.

```yaml prefect.yaml
# Welcome to your prefect.yaml file! You can use this file for storing and managing
# configuration for deploying your flows. We recommend committing this file to source
# control along with your flow code.

# Generic metadata about this project
name: prefect-modal
prefect-version: 3.1.15

# build section allows you to manage and build docker images
build: null

# push section allows you to manage if and how this project is uploaded to remote locations
push: null

# pull section allows you to provide instructions for cloning this project in remote locations
pull:
- prefect.deployments.steps.git_clone:
    repository: https://github.com/Ben-Epstein/prefect-modal
    branch: main
    access_token: null

# the deployments section allows you to provide configuration for deploying flows
deployments:
- name: null
  version: null
  tags: []
  description: null
  schedule: {}
  flow_name: null
  entrypoint: null
  parameters: {}
  work_pool:
    name: null
    work_queue_name: null
    job_variables: {}
```

The important sections here are `pull`, which defines the repository and branch to pull from, as well as `deployments`, which define the `flows` that will be `run` at some `schedule` on a `work_pool`.
The work pool will be set to modal later in this tutorial.

Finally, create your flow.

```bash
touch src/prefect_modal/flows/flow1.py
```

You can do anything in your flow, but use the following code to keep it simple.

```python src/prefect_modal/flows/flow1.py
from prefect import flow, task

@task()
def do_print(param: str) -> None:
    print("Doing the task")
    print(param)

@flow(log_prints=True)
def run_my_flow(param: str) -> None:
    print("flow 2")
    do_print(param)

@flow(log_prints=True)
def main(name: str = "world", goodbye: bool = False):
    print(f"Hello {name} from Prefect! 🤗")
    run_my_flow(name)
    if goodbye:
        print(f"Goodbye {name}!")
```

## Give Prefect access to your GitHub repository

First, authenticate to Prefect Cloud.

```bash
uv run prefect cloud login
```

You'll need a Personal Access Token (PAT) for authentication.
For simplicity, use a classic token, but you can configure a fine-grained token if you want.

In GitHub, go to [Personal access tokens](https://github.com/settings/tokens) and click **Generate new token (classic)**.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/2.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7c14394650d398bd359d940cea743757" alt="image.png" data-og-width="1384" width="1384" data-og-height="800" height="800" data-path="v3/img/tutorials/modal/2.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/2.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=c8c9a9bbca21bec91dd30ea9faff451a 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/2.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=848dad8856a06e2b23320990f7260c63 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/2.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=e0084c907d313c94dcea4fda1f99bc31 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/2.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=8d35c97333b1cafb366fc84ca40a5d31 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/2.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=bcca026a217e348b2f7fbd390dbd2ae3 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/2.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=05b53933cc5d93bdeefd4ce8967d84f6 2500w" data-optimize="true" data-opv="2" />

Give the token a name, an expiration date, and repository access.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/3.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=d5961a522ab8264b6cd2268731364fae" alt="image.png" data-og-width="653" width="653" data-og-height="429" height="429" data-path="v3/img/tutorials/modal/3.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/3.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=21110b7f8d32fdb4318cd5519b9b1822 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/3.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=61b04b994c186ff7c440f6d4262a1a87 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/3.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=e9ee414967d5d81bbf0d410426bcfc61 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/3.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1a6402d296bc04831ccebe50c9ce6db9 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/3.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=c55a601936c13eb6616a060120199bb9 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/3.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=c626233c5f16764c1561632a3a87b143 2500w" data-optimize="true" data-opv="2" />

Once you've created the token, copy it and give it to Prefect.
First, run:

```bash
# Register the block
uv run prefect block register -m prefect_github

# Create the block
uv run prefect block create prefect_github
```

The second command returns a URL.
Click that URL to give your block a name and paste in the token you got from GitHub.
Name the block `prefect-modal`.

In `prefect.yaml`, edit the `pull:` section as follows:

```yaml
pull:
- prefect.deployments.steps.git_clone:
    id: clone-step
    repository: https://github.com/Ben-Epstein/prefect-modal
    branch: main
    credentials: '{{ prefect.blocks.github-credentials.prefect-modal }}'
```

* Replace the `access_token` key name with `credentials`.
* Change the repository name to the name of your repository.

Now, add the following section to configure how you install your package and what your working directory is:

```yaml
- prefect.deployments.steps.run_shell_script:
    directory: '{{ clone-step.directory }}'
    script: pip install --upgrade 'uv>=0.5.6,<0.6'
- prefect.deployments.steps.run_shell_script:
    directory: '{{ clone-step.directory }}'
    script: uv sync --no-editable --no-dev
```

<Info>
  Typically, `uv sync` creates a new virtual environment.
  The following steps show how to tell `uv` to use the root Python version.
</Info>

This configuration tells Prefect how to download the code from GitHub into the Modal pod before running the flow.
This is important: you are telling Modal to load the code from `main`.
This means that if you push new code to main, the next run of a flow in Modal will change to whatever is in main.
To keep this stable, you can set that to a release branch, for example, to only update that release branch when you’re stable and ready.

Now, configure a few more options on the `deployment` to get it ready: `entrypoint`, `schedule`, and `description`.

```yaml
  name: prefect-modal-example
  description: "Your first deployment which runs daily at 12:00 on Modal"
  entrypoint: prefect_modal.flows.flow1:main
  schedules:
  - cron: '0 12 * * *'
    timezone: America/New_York
    active: true
```

This schedule runs once a day at 12PM EST.
You can add another schedule by adding another list element.

<Info>
  Because you referenced the entrypoint as a module and not a path, you can call it from anywhere (as long as it’s installed).
  This is much more flexible.
</Info>

## Connect Prefect and Modal

You need to give Prefect access to your Modal account to provision a serverless instance to run your flows and tasks.
Modal will be the *Work Pool* in Prefect terms, remaining off when unused, and spinning up the infrastructure you need when a new flow run is scheduled.
Prefect makes this incredibly easy.

First, authenticate with Modal:

```bash
uv run modal setup
```

Next, create a token:

```bash
uv run modal token new
```

Finally, create a work pool:

```bash
uv run prefect work-pool create --type modal:push --provision-infra pref-modal-pool
```

The name `pref-modal-pool` in the last command is custom, you can name it whatever you want.
Take the work pool name and update your `prefect.yaml` file with it.

```yaml prefect.yaml {2}
...
work_pool:
    name: "pref-modal-pool"
    work_queue_name: "default"
    job_variables: {
        "env": {"UV_PROJECT_ENVIRONMENT": "/usr/local"}
    }
```

<Info>
  This `UV_PROJECT_ENVIRONMENT` is how you tell uv to use the root python.
  You could `pip install` without `uv` but it would be significantly slower (minutes instead of seconds) and you can't leverage your lockfile, resulting in unexpected behavior!
</Info>

You can create multiple work queues across the same pool (for example, if you have another job using this pool).
Multiple work queues let you handle concurrency and swim-lane priorities.
To keep things simple, this tutorial will use the the default queue name that comes with every new pool.

When you deploy to Prefect, it will know to schedule all of the flow runs for this particular deployment on your modal work pool!

At this point, you could `git add . && git commit -m "prefect modal" && git push` to get your code into GitHub, and then `uv run prefect deploy --all` to get your deployment live.
But first, learn how to automate Prefect deployments.

## Configure CI/CD

Since the code must exist in GitHub in order for Modal to download, install, and run it, GitHub should also be the source of truth for telling Prefect what to do with the code.

First, create two secrets to add to the GitHub repository: `PREFECT_API_KEY` and `PREFECT_API_URL`.

1. For `PREFECT_API_URL`, the format is as follows: `https://api.prefect.cloud/api/accounts/{account_id}/workspaces/{workspace_id}`.

   Go to the Prefect Cloud Dashboard, and then extract the account ID and workspace ID from the URL.

   <Note>
     The Prefect console URL uses `/account` and `/workspace` but the API uses `/accounts` and `/workspaces`, respectively.
   </Note>

2. For `PREFECT_API_KEY`, go to the [API keys](https://app.prefect.cloud/my/api-keys) page and create a new API key.

   <img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/4.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=22db8bb67f9faa3f051f6a22994685ed" alt="image.png" data-og-width="511" width="511" data-og-height="354" height="354" data-path="v3/img/tutorials/modal/4.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/4.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=2e16527daf99adc6deff582a24c2b5a7 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/4.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=b3a0a98419e53487265c63898b100dfe 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/4.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=5e6322f22464f88d4189b1f915e06b6a 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/4.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=f3e8fa2f401bf17cad6f95b90410f4d1 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/4.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=59db06f4b15a98145901381e7dbc84cd 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/4.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=3495367f284b2fc4f1ecd3fe2c83b976 2500w" data-optimize="true" data-opv="2" />

Go to your repository, and then **Settings** / **Secrets and variables** / **Actions**.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/5.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=67f61f7362368a8fd4b163590e227bf3" alt="image.png" data-og-width="1204" width="1204" data-og-height="813" height="813" data-path="v3/img/tutorials/modal/5.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/5.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=bb0305ee93925cb0fb6da563361b8414 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/5.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=a5fffa73a8ecdfa4fd9e3d28a3ded5b8 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/5.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=b246fd2d72d44056de270b428c82df9c 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/5.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=0354774da5134118424df893a138408e 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/5.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=d27b4e3cb16d6cb4ccce6abf8e15123f 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/5.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=86140a751a53a1df53225daa2012dd07 2500w" data-optimize="true" data-opv="2" />

Click **New repository secret** to add these secrets to your GitHub repository.

Now, add a simple GitHub workflow.
Create a new folder in the root of your GitHub repository:

```bash
mkdir -p .github/workflows
```

Create a workflow file.

```bash
touch .github/workflows/prefect_cd.yaml
```

Add the following code to this workflow.

```yaml .github/workflows/prefect_cd.yaml
name: Deploy Prefect flow

on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Prefect Deploy
        env:
          PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}
          PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}
        run: |
          make prefect-deploy

```

The `make prefect-deploy` command is used to deploy the flows in your deployment.

<Tip>
  You can run `make prefect-deploy` locally at any time to keep your deployment up to date.
</Tip>

Add the following command to your `Makefile`.

```makefile Makefile
prefect-deploy: setup
    uv run prefect deploy --prefect-file prefect.yaml --all
```

Before pushing your code, run `make prefect-deploy` once to make sure everything works.
Prefect will suggest changes to `prefect.yaml`, which you should accept.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/6.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=e64a05a860e344c8c79a102b819569fe" alt="image.png" data-og-width="1546" width="1546" data-og-height="373" height="373" data-path="v3/img/tutorials/modal/6.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/6.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1cf1e88bf279278652f9b9072e8e2139 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/6.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=40beebf67e9c9f44ab61de9dd69831ac 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/6.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=62e3a0d1289f090f21a6c67181dbf762 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/6.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=3383e77bd26ebe69c7de24154fb24df3 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/6.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=0543c3dd72c03d0064c07971ec33e1a3 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/6.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=2db68e256119a1d06e841be083c7cfa4 2500w" data-optimize="true" data-opv="2" />

You let Prefect override your deployment spec, which allowed your CD to run without any interruptions or prompts.
If you go to the **Deployment** page in Prefect Cloud, you'll see your deployment!

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/7.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=aeb05225ab1e4ec603edc49806adc51b" alt="image.png" data-og-width="1629" width="1629" data-og-height="366" height="366" data-path="v3/img/tutorials/modal/7.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/7.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=acd73de2e6587432c2979f8475d109a3 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/7.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7e0dc2d285f8618263a19b8345d4c817 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/7.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=ec6da33abcdc2964ca2c3d5524d9b2d3 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/7.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=45e93c39d702275a320f1c899754b4cc 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/7.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=eb74a7e5dbad9f5853c137e3997f54bf 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/7.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=a59fb06502e9bdb3b3d1124cd6071838 2500w" data-optimize="true" data-opv="2" />

There are no runs yet.
The output from `make prefect-deploy` shows the command to run your deployed flow.
However, since the code isn’t in GitHub yet, this will fail.
To fix this, push your code:

```bash
git push
```

Go to the repository in **GitHub**, and then open **Actions** to verify that your CI/CD is running successfully.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/8.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7fa4a81f7489dd7e405a1d59c0af1c27" alt="image.png" data-og-width="1610" width="1610" data-og-height="636" height="636" data-path="v3/img/tutorials/modal/8.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/8.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7e4fc98f6b33f079f44ef5b7193d3a27 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/8.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=4eeb088999525d534acb4fc6891e9241 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/8.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=6457bd2320a922e7a1d9afa58f7bd84c 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/8.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=925e3a29905a506347c20776bd076c09 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/8.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=ac9c6e19e14ddbdf235081756749bebd 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/8.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=3501f27d3447b4e35318e83103726111 2500w" data-optimize="true" data-opv="2" />

You can see the flow run in Prefect Cloud as well.

The flow will run automatically at 12 PM, but you can also run it manually.

In a new browser tab, open your \[[https://modal.com/apps/\](Modal](https://modal.com/apps/]\(Modal) dashboard) alongside your Prefect Cloud dashboard.

In your terminal, run the following command:

```bash
uv run prefect deployment run main/prefect-modal-example
```

You should see the run start in your Prefect dashboard.
In 30-60 seconds, you should see it run in Modal.
You can click on the run to see the logs.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/9.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=8db98eb8807965b3333dd36122bce457" alt="image.png" data-og-width="452" width="452" data-og-height="73" height="73" data-path="v3/img/tutorials/modal/9.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/9.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=6a54347cd440b4c28a7bd4cb3bae4249 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/9.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=dc25c7aa60062fa4ad3ce6863c8990ae 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/9.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=6f3deba49d09367c98eae2109b4bcab4 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/9.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=e6da492e31d1ca92f24e6262da11db54 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/9.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=922cf2ea1ca798e77874ae822a19ad45 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/9.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7eb61285ddabd23eda75109d6a866848 2500w" data-optimize="true" data-opv="2" />

Click into the app and then click **App Logs** on the left to show everything that’s happening inside the flow run!

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/10.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=0ed44b69a5f58f0547d129ae1180e0c1" alt="image.png" data-og-width="1915" width="1915" data-og-height="829" height="829" data-path="v3/img/tutorials/modal/10.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/10.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=3f9def5b3098853c627100cf0406a3dc 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/10.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=120916d83da19b7ec13f6ad4f496458d 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/10.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=5f8cc8d9e66d17e60bf54c668bd798ce 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/10.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7c438551abef3e7d7e1ed34e89a08eaa 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/10.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=65cdb38bec91f5e78e0445de1faecf2d 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/10.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=9d026d2a2630b980f878dc565f7ef5b8 2500w" data-optimize="true" data-opv="2" />

Click on a specific log line to get more details.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/11.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7f10980722d9f62f824307ccedd7eee9" alt="image.png" data-og-width="1613" width="1613" data-og-height="721" height="721" data-path="v3/img/tutorials/modal/11.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/11.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=f14f899200bcf7123e569d4dfff56d93 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/11.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=52817640f07d05c301aa975751cb73e4 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/11.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=8a9a7e77ff59c74f02d436c8dc5869e1 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/11.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=fc4492f7b4815006a3655c2c239c6e36 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/11.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=cc15fc63031a896084c7544698b7e647 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/11.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=9aaad7d016f6393ec21395cbd078b072 2500w" data-optimize="true" data-opv="2" />

If you open the URL in that log, you’ll see the corresponding logs in Prefect Cloud.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/12.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=361cfb3d4a4a66310c6e187fae01dc23" alt="image.png" data-og-width="1616" width="1616" data-og-height="918" height="918" data-path="v3/img/tutorials/modal/12.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/12.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=f51c48a7583e2925cfd1aefcb27df2d9 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/12.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=6e974efb38f84ed3c1a96cee37d29b02 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/12.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=a8958002e69a707fbb40c1670d0e2b44 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/12.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=7de60c05415588bec2fedc01f67c43f2 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/12.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=25753a1a94f8e67b1b8fef2fb5c48505 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/tutorials/modal/12.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=896deca8d474edc20fa80d641b4060c2 2500w" data-optimize="true" data-opv="2" />

As you make changes to either the code or deployment file, Prefect will redeploy and Modal will automatically pick up changes.
You've successfully built your first Prefect deployment that runs on Modal every hour!

<Note>
  For more information about CI/CD in Prefect, see [Build deployments via CI/CD](/v3/advanced/deploy-ci-cd).
</Note>


# How to run flows in local processes
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/run-flows-in-local-processes

Create a deployment for a flow by calling the `serve` method.

The simplest way to create a [deployment](/v3/deploy) for your flow is by calling its `serve` method.

## Serve a flow

The serve method creates a deployment for the flow and starts a long-running process
that monitors for work from the Prefect server.
When work is found, it is executed within its own isolated subprocess.

```python hello_world.py
from prefect import flow


@flow(log_prints=True)
def hello_world(name: str = "world", goodbye: bool = False):
    print(f"Hello {name} from Prefect! 🤗")

    if goodbye:
        print(f"Goodbye {name}!")


if __name__ == "__main__":
    # creates a deployment and starts a long-running
    # process that listens for scheduled work
    hello_world.serve(name="my-first-deployment",
        tags=["onboarding"],
        parameters={"goodbye": True},
        interval=60
    )
```

This interface provides the configuration for a deployment (with no
strong infrastructure requirements), such as:

* schedules
* event triggers
* metadata such as tags and description
* default parameter values

<Tip>
  **Schedules are auto-paused on shutdown**

  By default, stopping the process running `flow.serve` will pause the schedule
  for the deployment (if it has one).

  When running this in environments where restarts are expected use the

  `pause_on_shutdown=False` flag to prevent this behavior:

  ```python
  if __name__ == "__main__":
      hello_world.serve(
          name="my-first-deployment",
          tags=["onboarding"],
          parameters={"goodbye": True},
          pause_on_shutdown=False,
          interval=60
      )
  ```
</Tip>

## Additional serve options

The `serve` method on flows exposes many options for the deployment.
Here's how to use some of those options:

* `cron`: a keyword that allows you to set a cron string schedule for the deployment; see
  [schedules](/v3/automate/add-schedules/) for more advanced scheduling options
* `tags`: a keyword that allows you to tag this deployment and its runs for bookkeeping and filtering purposes
* `description`: a keyword that allows you to document what this deployment does; by default the
  description is set from the docstring of the flow function (if documented)
* `version`: a keyword that allows you to track changes to your deployment; uses a hash of the
  file containing the flow by default; popular options include semver tags or git commit hashes
* `triggers`: a keyword that allows you to define a set of conditions for when the deployment should run; see
  [triggers](/v3/concepts/event-triggers/) for more on Prefect Events concepts

Next, add these options to your deployment:

```python
if __name__ == "__main__":
    get_repo_info.serve(
        name="my-first-deployment",
        cron="* * * * *",
        tags=["testing", "tutorial"],
        description="Given a GitHub repository, logs repository statistics for that repo.",
        version="tutorial/deployments",
    )
```

<Tip>
  **Triggers with `.serve`**

  See this [example](/v3/how-to-guides/automations/chaining-deployments-with-events) that triggers downstream work on upstream events.
</Tip>

When you rerun this script, you will find an updated deployment in the UI that is actively scheduling work.
Stop the script in the CLI using `CTRL+C` and your schedule automatically pauses.

<Note>
  **`serve()` is a long-running process**

  To execute remotely triggered or scheduled runs, your script with `flow.serve` must be actively running.
</Note>

## Serve multiple flows at once

Serve multiple flows with the same process using the `serve` utility along with the `to_deployment` method of flows:

```python serve_two_flows.py
import time
from prefect import flow, serve


@flow
def slow_flow(sleep: int = 60):
    "Sleepy flow - sleeps the provided amount of time (in seconds)."
    time.sleep(sleep)


@flow
def fast_flow():
    "Fastest flow this side of the Mississippi."
    return


if __name__ == "__main__":
    slow_deploy = slow_flow.to_deployment(name="sleeper", interval=45)
    fast_deploy = fast_flow.to_deployment(name="fast")
    serve(slow_deploy, fast_deploy)
```

The behavior and interfaces are identical to the single flow case.
A few things to note:

* the `flow.to_deployment` interface exposes the *exact same* options as `flow.serve`; this method
  produces a deployment object
* the deployments are only registered with the API once `serve(...)` is called
* when serving multiple deployments, the only requirement is that they share a Python environment;
  they can be executed and scheduled independently of each other

A few optional steps for exploration include:

* pause and unpause the schedule for the `"sleeper"` deployment
* use the UI to submit ad-hoc runs for the `"sleeper"` deployment with different values for `sleep`
* cancel an active run for the `"sleeper"` deployment from the UI

<Tip>
  **Hybrid execution option**

  Prefect's deployment interface allows you to choose a hybrid execution model.
  Whether you use Prefect Cloud or self-host Prefect server, you can run workflows in the
  environments best suited to their execution.
  This model enables efficient use of your infrastructure resources while maintaining the privacy
  of your code and data.
  There is no ingress required.
  Read more about our [hybrid model](https://www.prefect.io/security/overview/#hybrid-model).
</Tip>

## Retrieve a flow from remote storage

Just like the `.deploy` method, the `flow.from_source` method is used to define how to retrieve the flow that you want to serve.

### `from_source`

The `flow.from_source` method on `Flow` objects requires a `source` and an `entrypoint`.

#### `source`

The `source` of your deployment can be:

* a path to a local directory such as `path/to/a/local/directory`
* a repository URL such as `https://github.com/org/repo.git`
* a `GitRepository` object that accepts
  * a repository URL
  * a reference to a branch, tag, or commit hash
  * `GitCredentials` for private repositories

#### `entrypoint`

A flow `entrypoint` is the path to the file where the flow is located within that `source`, in the form

```python
{path}:{flow_name}
```

For example, the following code will load the `hello` flow from the `flows/hello_world.py` file in the `PrefectHQ/examples` repository:

```python load_from_url.py
from prefect import flow


my_flow = flow.from_source(
    source="https://github.com/PrefectHQ/examples.git",
    entrypoint="flows/hello_world.py:hello"
)


if __name__ == "__main__":
    my_flow()
```

```bash
16:40:33.818 | INFO    | prefect.engine - Created flow run 'muscular-perch' for flow 'hello'
16:40:34.048 | INFO    | Flow run 'muscular-perch' - Hello world!
16:40:34.706 | INFO    | Flow run 'muscular-perch' - Finished in state Completed()
```

For more ways to store and access flow code, see the [Retrieve code from storage page](/v3/deploy/infrastructure-concepts/store-flow-code).

<Tip>
  **You can serve loaded flows**

  You can serve a flow loaded from remote storage with the same [`serve`](#serve-a-flow) method as a local flow:

  ```python serve_loaded_flow.py
  from prefect import flow


  if __name__ == "__main__":
      flow.from_source(
          source="https://github.com/org/repo.git",
          entrypoint="flows.py:my_flow"
      ).serve(name="my-deployment")
  ```
</Tip>

### Remote storage polling

When you serve a flow loaded from remote storage, the serving process periodically polls your remote storage for updates to the flow's code.
This pattern allows you to update your flow code without restarting the serving process.
Note that if you change metadata associated with your flow's deployment such as parameters, you *will* need to restart the serve process.

## Further reading

* [Serve flows in a long-lived Docker container](/v3/deploy/static-infrastructure-examples/docker)
* [Work pools and deployments with dynamic infrastructure](/v3/deploy/infrastructure-concepts/work-pools)


# How to run flows in a long-lived Docker container
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/serve-flows-docker

Learn how to serve a flow in a long-lived Docker container

The `.serve` method allows you to easily elevate a flow to a deployment, listening for scheduled work to execute [as a local process](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes).

However, this *"local"* process does not need to be on your local machine. In this example we show how to run a flow in Docker container on your local machine, but you could use a Docker container on any machine that has [Docker installed](https://docs.docker.com/engine/install/).

## Overview

In this example, you will set up:

* a simple flow that retrieves the number of stars for some GitHub repositories
* a `Dockerfile` that packages up your flow code and dependencies into a container image

## Writing the flow

Say we have a flow that retrieves the number of stars for a GitHub repository:

```python serve_retrieve_github_stars.py {19-23}
import httpx
from prefect import flow, task


@task(log_prints=True)
def get_stars_for_repo(repo: str) -> int:
    response = httpx.Client().get(f"https://api.github.com/repos/{repo}")
    stargazer_count = response.json()["stargazers_count"]
    print(f"{repo} has {stargazer_count} stars")
    return stargazer_count


@flow
def retrieve_github_stars(repos: list[str]) -> list[int]:
    return get_stars_for_repo.map(repos).wait()


if __name__ == "__main__":
    retrieve_github_stars.serve(
        parameters={
            "repos": ["python/cpython", "prefectHQ/prefect"],
        }
    )
```

We can serve this flow on our local machine using:

```bash
python serve_retrieve_github_stars.py
```

... but how can we package this up so we can run it on other machines?

## Writing the Dockerfile

Assuming we have our Python requirements defined in a file:

```txt requirements.txt
prefect
```

and this directory structure:

```
├── Dockerfile
├── requirements.txt
└── serve_retrieve_github_stars.py
```

We can package up our flow into a Docker container using a `Dockerfile`.

<CodeGroup>
  ```dockerfile Using pip
  # Use an official Python runtime as the base image
  FROM python:3.12-slim

  # Set the working directory in the container
  WORKDIR /app

  # Copy the requirements file into the container
  COPY requirements.txt .

  # Install the required packages
  RUN pip install --no-cache-dir -r requirements.txt

  # Copy the rest of the application code
  COPY serve_retrieve_github_stars.py .

  # Set the command to run your application
  CMD ["python", "serve_retrieve_github_stars.py"]
  ```

  ```dockerfile Using uv
  # Use the official Python image with uv pre-installed
  FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim

  # Set the working directory
  WORKDIR /app

  # Set environment variables
  ENV UV_SYSTEM_PYTHON=1
  ENV PATH="/root/.local/bin:$PATH"

  # Copy only the requirements file first to leverage Docker cache
  COPY requirements.txt .

  # Install dependencies
  RUN --mount=type=cache,target=/root/.cache/uv \
      uv pip install -r requirements.txt

  # Copy the rest of the application code
  COPY serve_retrieve_github_stars.py .

  # Set the entrypoint
  ENTRYPOINT ["python", "serve_retrieve_github_stars.py"]
  ```
</CodeGroup>

<Note>
  Using `pip`, the image is built in about 20 seconds, and using `uv`, the image is built in about 3 seconds.

  You can learn more about using `uv` in the [Astral documentation](https://docs.astral.sh/uv/guides/integration/docker/).
</Note>

## Build and run the container

Now that we have a flow and a Dockerfile, we can build the image from the Dockerfile and run a container from this image.

### Build (and push) the image

We can build the image with the `docker build` command and the `-t` flag to specify a name for the image.

```bash
docker build -t my-flow-image .
```

At this point, you may also want to push the image to a container registry such as [Docker Hub](https://hub.docker.com/) or [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). Please refer to each registry's respective documentation for details on authentication and registry naming conventions.

### Run the container

You'll likely want to inject some environment variables into your container, so let's define a `.env` file:

```bash .env
PREFECT_API_URL=<YOUR-API-URL>
PREFECT_API_KEY=<YOUR-API-KEY-IF-USING-PREFECT-CLOUD>
```

Then, run the container in [detached mode](https://docs.docker.com/engine/reference/commandline/run/#detached-d) (in other words, in the background):

```bash
docker run -d --env-file .env my-flow-image
```

#### Verify the container is running

```bash
docker ps | grep my-flow-image
```

You should see your container in the list of running containers, note the `CONTAINER ID` as we'll need it to view logs.

#### View logs

```bash
docker logs <CONTAINER-ID>
```

You should see logs from your newly served process, with the link to your deployment in the UI.

### Stop the container

```bash
docker stop <CONTAINER-ID>
```

## Health checks for production deployments

When deploying to production environments like Google Cloud Run, AWS ECS, or Kubernetes, you may need to configure health checks to ensure your container is running properly. The `.serve()` method supports an optional webserver that exposes a health endpoint.

### Enabling the health check webserver

You can enable the health check webserver in two ways:

1. **Pass `webserver=True` to `.serve()`:**

```python
if __name__ == "__main__":
    retrieve_github_stars.serve(
        parameters={
            "repos": ["python/cpython", "prefectHQ/prefect"],
        },
        webserver=True  # Enable health check webserver
    )
```

2. **Set the environment variable:**

```bash
PREFECT_RUNNER_SERVER_ENABLE=true
```

When enabled, the webserver exposes a health endpoint at `http://localhost:8080/health` by default.

### Configuring the health check port

You can customize the host and port using environment variables:

```bash
PREFECT_RUNNER_SERVER_HOST=0.0.0.0  # Allow external connections
PREFECT_RUNNER_SERVER_PORT=8080      # Port for health checks
```

### Docker with health checks

Add a health check to your Dockerfile:

```dockerfile
# ... your existing Dockerfile content ...

# Health check configuration
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD python -c "import urllib.request as u; u.urlopen('http://localhost:8080/health', timeout=1)"

# Set the command to run your application with webserver enabled
CMD ["python", "serve_retrieve_github_stars.py"]
```

Or if you prefer to use environment variables:

```dockerfile
# ... your existing Dockerfile content ...

# Enable the health check webserver
ENV PREFECT_RUNNER_SERVER_ENABLE=true
ENV PREFECT_RUNNER_SERVER_HOST=0.0.0.0
ENV PREFECT_RUNNER_SERVER_PORT=8080

# Health check configuration
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD python -c "import urllib.request as u; u.urlopen('http://localhost:8080/health', timeout=1)"

CMD ["python", "serve_retrieve_github_stars.py"]
```

### Platform-specific configurations

<Tabs>
  <Tab title="Google Cloud Run">
    Cloud Run requires containers to listen on a port. Configure your container to expose the health check port:

    ```yaml
    # In your Cloud Run configuration
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 60
      periodSeconds: 30
    ```

    Make sure to set the container port to 8080 in Cloud Run settings.
  </Tab>

  <Tab title="AWS ECS/Fargate">
    Configure health checks in your task definition:

    ```json
    {
      "healthCheck": {
        "command": ["CMD-SHELL", "python -c \"import urllib.request as u; u.urlopen('http://localhost:8080/health', timeout=1)\""],
        "interval": 30,
        "timeout": 10,
        "retries": 3,
        "startPeriod": 60
      }
    }
    ```
  </Tab>

  <Tab title="Kubernetes">
    Add liveness and readiness probes to your deployment:

    ```yaml
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 60
      periodSeconds: 30
      timeoutSeconds: 10
      failureThreshold: 3

    readinessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 10
      periodSeconds: 5
    ```
  </Tab>
</Tabs>

The health endpoint returns:

* **200 OK** with `{"message": "OK"}` when the runner is healthy and polling for work
* **503 Service Unavailable** when the runner hasn't polled recently (indicating it may be unresponsive)

## Next steps

Congratulations! You have packaged and served a flow on a long-lived Docker container.

You may now easily deploy this container to other infrastructures, such as:

* [Modal](https://modal.com/)
* [Google Cloud Run](https://cloud.google.com/run)
* [AWS Fargate / ECS](https://aws.amazon.com/fargate/)
* Managed Kubernetes (For example: GKE, EKS, or AKS)

or anywhere else you can run a Docker container!


# How to run flows on serverless compute
Source: https://docs-3.prefect.io/v3/how-to-guides/deployment_infra/serverless

Learn how to use Prefect push work pools to schedule work on serverless infrastructure without having to run a worker.

<span class="badge cloud" /> Push [work pools](/v3/deploy/infrastructure-concepts/work-pools/) are a special type of work pool. They allow
Prefect Cloud to submit flow runs for execution to serverless computing infrastructure without requiring you to run a worker.
Push work pools currently support execution in AWS ECS tasks, Azure Container Instances, Google Cloud Run jobs, Modal, and Coiled.

In this guide you will:

* Create a push work pool that sends work to Amazon Elastic Container Service (AWS ECS), Azure Container Instances (ACI),
  Google Cloud Run, Modal, or Coiled
* Deploy a flow to that work pool
* Execute a flow without having to run a worker process to poll for flow runs

{/*
  <!-- vale off -->
  */}

<Note>
  You can automatically provision infrastructure and create your push work pool using the `prefect work-pool create`
  CLI command with the `--provision-infra` flag.
  This approach greatly simplifies the setup process.
</Note>

{/*
  <!-- vale on -->
  */}

First, you will set up automatic infrastructure provisioning for push work pools. Then you will learn how to manually
set up your push work pool.

## Automatic infrastructure provisioning

With Perfect Cloud you can provision infrastructure for use with an AWS ECS, Google Cloud Run, ACI push work pool.
Push work pools in Prefect Cloud simplify the setup and management of the infrastructure necessary to run your flows.
However, setting up infrastructure on your cloud provider can still be a time-consuming process.
Prefect dramatically simplifies this process by automatically provisioning the necessary infrastructure for you.

We'll use the `prefect work-pool create` CLI command with the `--provision-infra` flag to automatically provision your
serverless cloud resources and set up your Prefect workspace to use a new push pool.

### Prerequisites

To use automatic infrastructure provisioning, you need:

* the relevant cloud CLI library installed
* to be authenticated with your cloud provider

<Tabs>
  <Tab title="AWS ECS">
    Install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html),
    [authenticate with your AWS account](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html),
    and [set a default region](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-methods).

    If you already have the AWS CLI installed, be sure to [update to the latest version](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions).

    You will need the following permissions in your authenticated AWS account:

    IAM Permissions:

    * iam:CreatePolicy
    * iam:GetPolicy
    * iam:ListPolicies
    * iam:CreateUser
    * iam:GetUser
    * iam:AttachUserPolicy
    * iam:CreateRole
    * iam:GetRole
    * iam:AttachRolePolicy
    * iam:ListRoles
    * iam:PassRole

    Amazon ECS Permissions:

    * ecs:CreateCluster
    * ecs:DescribeClusters

    Amazon EC2 Permissions:

    * ec2:CreateVpc
    * ec2:DescribeVpcs
    * ec2:CreateInternetGateway
    * ec2:AttachInternetGateway
    * ec2:CreateRouteTable
    * ec2:CreateRoute
    * ec2:CreateSecurityGroup
    * ec2:DescribeSubnets
    * ec2:CreateSubnet
    * ec2:DescribeAvailabilityZones
    * ec2:AuthorizeSecurityGroupIngress
    * ec2:AuthorizeSecurityGroupEgress

    Amazon ECR Permissions:

    * ecr:CreateRepository
    * ecr:DescribeRepositories
    * ecr:GetAuthorizationToken

    If you want to use AWS managed policies, you can use the following:

    * AmazonECS\_FullAccess
    * AmazonEC2FullAccess
    * IAMFullAccess
    * AmazonEC2ContainerRegistryFullAccess

    The above policies give you all the permissions needed, but are more permissive than necessary.

    [Docker](https://docs.docker.com/get-docker/) is also required to build and push images to your registry.
  </Tab>

  <Tab title="Azure Container Instances">
    Install the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) and
    [authenticate with your Azure account](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli).

    If you already have the Azure CLI installed, be sure to update to the latest version with `az upgrade`.

    You will also need the following roles in your Azure subscription:

    * Contributor
    * User Access Administrator
    * Application Administrator
    * Managed Identity Operator
    * Azure Container Registry Contributor

    Docker is also required to build and push images to your registry. You can install Docker
    [here](https://docs.docker.com/get-docker/).
  </Tab>

  <Tab title="Google Cloud Run">
    Install the [gcloud CLI](https://cloud.google.com/sdk/docs/install) and
    [authenticate with your GCP project](https://cloud.google.com/docs/authentication/gcloud).

    If you already have the gcloud CLI installed, be sure to update to the latest version with `gcloud components update`.

    You will also need the following permissions in your GCP project:

    * resourcemanager.projects.list
    * serviceusage.services.enable
    * iam.serviceAccounts.create
    * iam.serviceAccountKeys.create
    * resourcemanager.projects.setIamPolicy
    * artifactregistry.repositories.create

    Docker is also required to build and push images to your registry. You can install Docker
    [here](https://docs.docker.com/get-docker/).
  </Tab>

  <Tab title="Modal">
    Install `modal` by running:

    ```bash
    pip install modal
    ```

    Create a Modal API token by running:

    ```bash
    modal token new
    ```

    See [Run flows on Modal](/v3/how-to-guides/deployment_infra/modal) for more details.
  </Tab>

  <Tab title="Coiled">
    Install `coiled` by running:

    ```bash
    pip install coiled prefect-coiled
    ```

    Create a Coiled API token by running:

    ```bash
    coiled login
    ```

    Connect Coiled to your cloud account by running

    ```bash
    coiled setup
    ```

    or by navigating to [cloud.coiled.io/get-started](https://cloud.coiled.io/get-started)
  </Tab>
</Tabs>

### Automatically create a new push work pool and provision infrastructure

To create a new push work pool and configure the necessary infrastructure,
run this command for your particular cloud provider:

<Tabs>
  <Tab title="AWS ECS">
    ```bash
    prefect work-pool create --type ecs:push --provision-infra my-ecs-pool
    ```

    The `--provision-infra` flag automatically sets up your default AWS account to execute
    flows with ECS tasks.
    In your AWS account, this command creates a new IAM user, IAM policy, and
    ECS cluster that uses AWS Fargate, VPC, and ECR repository (if they don't already exist).
    In your Prefect workspace, this command creates an
    [`AWSCredentials` block](/integrations/prefect-aws/index#save-credentials-to-an-aws-credentials-block) for storing the generated credentials.

    Here's an abbreviated example output from running the command:

    ```bash
    _____________________________________________________________________________________________
    | Provisioning infrastructure for your work pool my-ecs-pool will require:                   |
    |                                                                                            |
    |          - Creating an IAM user for managing ECS tasks: prefect-ecs-user                   |
    |          - Creating and attaching an IAM policy for managing ECS tasks: prefect-ecs-policy |
    |          - Storing generated AWS credentials in a block                                    |
    |          - Creating an ECS cluster for running Prefect flows: prefect-ecs-cluster          |
    |          - Creating a VPC with CIDR 172.31.0.0/16 for running ECS tasks: prefect-ecs-vpc   |
    |          - Creating an ECR repository for storing Prefect images: prefect-flows            |
    _____________________________________________________________________________________________
    Proceed with infrastructure provisioning? [y/n]: y
    Provisioning IAM user
    Creating IAM policy
    Generating AWS credentials
    Creating AWS credentials block
    Provisioning ECS cluster
    Provisioning VPC
    Creating internet gateway
    Setting up subnets
    Setting up security group
    Provisioning ECR repository
    Authenticating with ECR
    Setting default Docker build namespace
    Provisioning Infrastructure ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
    Infrastructure successfully provisioned!
    Created work pool 'my-ecs-pool'!
    ```

    <Tip>
      **Default Docker build namespace**

      After infrastructure provisioning completes, you will be logged into your new ECR repository and the default
      Docker build namespace will be set to the URL of the registry.
    </Tip>

    While the default namespace is set, you do not need to provide the registry URL when building images as
    part of your deployment process.

    To take advantage of this, you can write your deploy scripts like this:

    ```python example_deploy_script.py
    from prefect import flow
    from prefect.docker import DockerImage

    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello {name}! I'm a flow running in a ECS task!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image=DockerImage(
                name="my-repository:latest",
                platform="linux/amd64",
            )
        )
    ```

    This builds an image with the tag `<ecr-registry-url>/my-image:latest` and push it to the registry.

    Your image name needs to match the name of the repository created with your work pool. You can create
    new repositories in the ECR console.
  </Tab>

  <Tab title="Azure Container Instances">
    ```bash
    prefect work-pool create --type azure-container-instance:push --provision-infra my-aci-pool
    ```

    The `--provision-infra` flag automatically sets up your default Azure account to execute
    flows through Azure Container Instances.
    In your Azure account, this command creates a resource group, app registration, service account with necessary permission,
    generates a secret for the app registration, and creates an Azure Container Registry, (if they don't already exist).
    In your Prefect workspace, this command creates an
    [`AzureContainerInstanceCredentials` block](/integrations/prefect-azure)
    to store the client secret value from the generated secret.

    Here's an abbreviated example output from running the command:

    ```bash
    _____________________________________________________________________________________________
    | Provisioning infrastructure for your work pool my-aci-work-pool will require:             |
    |                                                                                           |
    |     Updates in subscription Azure subscription 1                                          |
    |                                                                                           |
    |         - Create a resource group in location eastus                                      |
    |         - Create an app registration in Azure AD prefect-aci-push-pool-app                |
    |         - Create/use a service principal for app registration                             |
    |         - Generate a secret for app registration                                          |
    |         - Create an Azure Container Registry with prefix prefect                           |
    |         - Create an identity prefect-acr-identity to allow access to the created registry |
    |         - Assign Contributor role to service account                                      |
    |         - Create an ACR registry for image hosting                                        |
    |         - Create an identity for Azure Container Instance to allow access to the registry |
    |                                                                                           |
    |     Updates in Prefect workspace                                                          |
    |                                                                                           |
    |         - Create Azure Container Instance credentials block aci-push-pool-credentials     |
    |                                                                                           |
    _____________________________________________________________________________________________
    Proceed with infrastructure provisioning? [y/n]:
    Creating resource group
    Creating app registration
    Generating secret for app registration
    Creating ACI credentials block
    ACI credentials block 'aci-push-pool-credentials' created in Prefect Cloud
    Assigning Contributor role to service account
    Creating Azure Container Registry
    Creating identity
    Provisioning infrastructure... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
    Infrastructure successfully provisioned for 'my-aci-work-pool' work pool!
    Created work pool 'my-aci-work-pool'!
    ```

    <Tip>
      **Default Docker build namespace**
      After infrastructure provisioning completes, you are logged into your new Azure Container Registry and
      the default Docker build namespace is set to the URL of the registry.
    </Tip>

    While the default namespace is set, any images you build without specifying a registry or username/organization
    are pushed to the registry.

    To use this capability, write your deploy scripts like this:

    ```python example_deploy_script.py
    from prefect import flow
    from prefect.docker import DockerImage


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello {name}! I'm a flow running on an Azure Container Instance!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image=DockerImage(
                name="my-image:latest",
                platform="linux/amd64",
            )
        )
    ```

    This builds an image with the tag `<acr-registry-url>/my-image:latest` and pushes it to the registry.
  </Tab>

  <Tab title="Google Cloud Run">
    ```bash
    prefect work-pool create --type cloud-run:push --provision-infra my-cloud-run-pool
    ```

    The `--provision-infra` flag allows you to select a GCP project to use for your work pool and automatically
    configures it to execute flows through Cloud Run.
    In your GCP project, this command activates the Cloud Run API, creates a service account, and creates a key for the
    service account, (if they don't already exist).
    In your Prefect workspace, this command creates a
    [`GCPCredentials` block](/integrations/prefect-gcp/index#authenticate-using-a-gcp-credentials-block) to store the service account key.

    Here's an abbreviated example output from running the command:

    ```bash
    ____________________________________________________________________________________________________________
    | Provisioning infrastructure for your work pool my-cloud-run-pool will require:                           |
    |                                                                                                          |
    |     Updates in GCP project central-kit-405415 in region us-central1                                      |
    |                                                                                                          |
    |         - Activate the Cloud Run API for your project                                                    |
    |         - Activate the Artifact Registry API for your project                                            |
    |         - Create an Artifact Registry repository named prefect-images                                    |
    |         - Create a service account for managing Cloud Run jobs: prefect-cloud-run                        |
    |             - Service account will be granted the following roles:                                       |
    |                 - Service Account User                                                                   |
    |                 - Cloud Run Developer                                                                    |
    |         - Create a key for service account prefect-cloud-run                                             |
    |                                                                                                          |
    |     Updates in Prefect workspace                                                                         |
    |                                                                                                          |
    |         - Create GCP credentials block my--pool-push-pool-credentials to store the service account key   |
    |                                                                                                          |
    ____________________________________________________________________________________________________________
    Proceed with infrastructure provisioning? [y/n]: y
    Activating Cloud Run API
    Activating Artifact Registry API
    Creating Artifact Registry repository
    Configuring authentication to Artifact Registry
    Setting default Docker build namespace
    Creating service account
    Assigning roles to service account
    Creating service account key
    Creating GCP credentials block
    Provisioning Infrastructure ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
    Infrastructure successfully provisioned!
    Created work pool 'my-cloud-run-pool'!
    ```

    <Tip>
      **Default Docker build namespace**

      After infrastructure provisioning completes, you are logged into your new Artifact Registry repository
      and the default Docker build namespace is set to the URL of the repository.
    </Tip>

    While the default namespace is set, any images you build without specifying a registry or username/organization
    are pushed to the repository.

    To use this capability, write your deploy scripts like this:

    ```python example_deploy_script.py
    from prefect import flow
    from prefect.docker import DockerImage


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello {name}! I'm a flow running on Cloud Run!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="above-ground",
            image=DockerImage(
                name="my-image:latest",
                platform="linux/amd64",
            )
        )
    ```

    This builds an image with the tag `<region>-docker.pkg.dev/<project>/<repository-name>/my-image:latest`
    and pushes it to the repository.
  </Tab>

  <Tab title="Modal">
    ```bash
    prefect work-pool create --type modal:push --provision-infra my-modal-pool
    ```

    Using the `--provision-infra` flag triggers the creation of a `ModalCredentials` block in your Prefect Cloud workspace.
    This block stores your Modal API token, which authenticates with Modal's API. By default, the token for your
    current Modal profile is used for the new `ModalCredentials` block. If Prefect is unable to discover a Modal
    API token for your current profile, you will be prompted to create a new one.
  </Tab>

  <Tab title="Coiled">
    ```bash
    prefect work-pool create --type coiled:push --provision-infra my-coiled-pool
    ```

    Using the `--provision-infra` flag triggers the creation of a `CoiledCredentials` block in your Prefect Cloud workspace.
    This block stores your Coiled API token, which authenticates with Coiled's API.
  </Tab>
</Tabs>

You're ready to create and schedule deployments that use your new push work pool.
Reminder that no worker is required to run flows with a push work pool.

### Use existing resources with automatic infrastructure provisioning

If you already have the necessary infrastructure set up, Prefect detects that at work pool creation and the
infrastructure provisioning for that resource is skipped.

For example, here's how `prefect work-pool create my-work-pool --provision-infra` looks when existing Azure resources are detected:

```bash
Proceed with infrastructure provisioning? [y/n]: y
Creating resource group
Resource group 'prefect-aci-push-pool-rg' already exists in location 'eastus'.
Creating app registration
App registration 'prefect-aci-push-pool-app' already exists.
Generating secret for app registration
Provisioning infrastructure
ACI credentials block 'bb-push-pool-credentials' created
Assigning Contributor role to service account...
Service principal with object ID '4be6fed7-...' already has the 'Contributor' role assigned in
'/subscriptions/.../'
Creating Azure Container Instance
Container instance 'prefect-aci-push-pool-container' already exists.
Creating Azure Container Instance credentials block
Provisioning infrastructure... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Infrastructure successfully provisioned!
Created work pool 'my-work-pool'!
```

## Provision infrastructure for an existing push work pool

If you already have a push work pool set up, but haven't configured the necessary infrastructure, you can use the
`provision-infra` sub-command to provision the infrastructure for that work pool.
For example, you can run the following command if you have a work pool named "my-work-pool".

```bash
prefect work-pool provision-infra my-work-pool
```

Prefect creates the necessary infrastructure for the `my-work-pool` work pool and provides you with a summary
of the changes:

```bash
__________________________________________________________________________________________________________________
| Provisioning infrastructure for your work pool my-work-pool will require:                                      |
|                                                                                                                |
|     Updates in subscription Azure subscription 1                                                               |
|                                                                                                                |
|         - Create a resource group in location eastus                                                           |
|         - Create an app registration in Azure AD prefect-aci-push-pool-app                                     |
|         - Create/use a service principal for app registration                                                  |
|         - Generate a secret for app registration                                                               |
|         - Assign Contributor role to service account                                                           |
|         - Create Azure Container Instance 'aci-push-pool-container' in resource group prefect-aci-push-pool-rg |
|                                                                                                                |
|     Updates in Prefect workspace                                                                               |
|                                                                                                                |
|         - Create Azure Container Instance credentials block aci-push-pool-credentials                          |
|                                                                                                                |
__________________________________________________________________________________________________________________
Proceed with infrastructure provisioning? [y/n]: y
```

This command speeds up your infrastructure setup process.

As with the examples above, you need to have the related cloud CLI library installed and to be authenticated with
your cloud provider.

## Manual infrastructure provisioning

If you prefer to set up your infrastructure manually, exclude the `--provision-infra` flag in the CLI command.
In the examples below, you'll create a push work pool through the Prefect Cloud UI.

<Tabs>
  <Tab title="AWS ECS">
    To push work to ECS, AWS credentials are required.

    Create a user and attach the *AmazonECS\_FullAccess* permissions.

    From that user's page, create credentials and store them somewhere safe for use in the next section.
  </Tab>

  <Tab title="Azure Container Instances">
    To push work to Azure, you need an Azure subscription, resource group, and tenant secret.

    **Create Subscription and Resource Group**

    1. In the Azure portal, create a subscription.
    2. Create a resource group within your subscription.

    **Create App Registration**

    1. In the Azure portal, create an app registration.
    2. In the app registration, create a client secret. Copy the value and store it somewhere safe.

    **Add App Registration to Resource Group**

    1. Navigate to the resource group you created earlier.
    2. Choose the "Access control (IAM)" blade in the left-hand side menu. Click "+ Add" button at the top, then
       "Add role assignment".
    3. Go to the "Privileged administrator roles" tab, click on "Contributor", then click "Next" at the bottom of the page.
    4. Click on "+ Select members". Type the name of the app registration (otherwise it may not autopopulate) and click to add it.
       Then hit "Select" and click "Next". The default permissions associated with a role like "Contributor" may
       not be sufficient for all operations related to Azure Container Instances (ACI). The specific permissions
       required depend on the operations you need to perform (like creating, running, and deleting ACI container groups)
       and your organization's security policies. In some cases, additional permissions or custom roles are necessary.
    5. Click "Review + assign" to finish.
  </Tab>

  <Tab title="Google Cloud Run">
    You need a GCP service account and an API Key to push work to Cloud Run.

    Create a service account by navigating to the service accounts page and clicking *Create*. Name and describe your service account,
    and click *continue* to configure permissions.

    The service account must have two roles at a minimum: *Cloud Run Developer* and *Service Account User*.

        <img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcr-service-account-setup.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6fc561f651b41f62449f14c6f2fa9b57" alt="Configuring service account permissions in GCP" data-og-width="1170" width="1170" data-og-height="1016" height="1016" data-path="v3/img/guides/gcr-service-account-setup.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcr-service-account-setup.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=977c00b438dc21e3ace0936a6d108a0d 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcr-service-account-setup.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=094606b8a086c345335d0eb18e51b112 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcr-service-account-setup.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=073a090abd3201dc842cd87343402367 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcr-service-account-setup.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=909858cefd912995af87a6f726aea9a3 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcr-service-account-setup.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6f986dd3bd338a4c6127796254517a22 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcr-service-account-setup.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=f7de60cf6da1c923d0c951dc1f3d7f4b 2500w" data-optimize="true" data-opv="2" />

    Once you create the Service account, navigate to its *Keys* page to add an API key. Create a JSON type key, download it,
    and store it somewhere safe for use in the next section.
  </Tab>

  <Tab title="Modal">
    You need a Modal API token to push work to Modal.

    Navigate to **Settings** in the Modal UI to create a Modal API token. In the **API Tokens** section of the Settings page,
    click **New Token**.

    Copy the token ID and token secret and store them somewhere safe for use in the next section.
  </Tab>

  <Tab title="Coiled">
    You need a Coiled API token to push work to Coiled.

    In the Coiled UI click on your avatar and select **Profile**.  Then press the **Create API Token** button and copy the result.  You will need it in the next section.
  </Tab>
</Tabs>

### Work pool configuration

The push work pool stores information about what type of infrastructure the flow will run on, what default values to
provide to compute jobs, and other important execution environment parameters. Because the push work pool needs to
integrate securely with your serverless infrastructure, you need to store your credentials in Prefect Cloud by making a block.

### Create a Credentials block

<Tabs>
  <Tab title="AWS ECS">
    Navigate to the blocks page, click create new block, and select AWS Credentials for the type.

    For use in a push work pool, set the region, access key, and access key secret.

    Provide any other optional information and create your block.
  </Tab>

  <Tab title="Azure Container Instances">
    Navigate to the blocks page and click the "+" at the top to create a new block. Find the Azure Container
    Instance Credentials block and click "Add +".

    Locate the client ID and tenant ID on your app registration and use the client secret you saved earlier.
    Make sure the value of the secret, not the secret ID.

    Provide any other optional information and click "Create".
  </Tab>

  <Tab title="Google Cloud Run">
    Navigate to the blocks page, click create new block, and select GCP Credentials for the type.

    For use in a push work pool, this block must have the contents of the JSON key stored in the
    Service Account Info field, as such:

        <img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcp-creds-block-setup.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=93b1d4a0324a6100442e9b231f6c6ad7" alt="Configuring GCP Credentials block for use in cloud run push work pools" data-og-width="2432" width="2432" data-og-height="1296" height="1296" data-path="v3/img/guides/gcp-creds-block-setup.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcp-creds-block-setup.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=c3c441f9c38cfc102a2ca1392f345eb2 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcp-creds-block-setup.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=84aa018ab14e856179191b48cc2faf85 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcp-creds-block-setup.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=c4e71b8a26719cace97fa556cef43fab 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcp-creds-block-setup.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=c1b7852945f82dab21d487937cda4f0b 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcp-creds-block-setup.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=7c98527a3dc845dcdf291fa1a8ff348c 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/gcp-creds-block-setup.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=8742ed514b91c0b80679a1761c3989fd 2500w" data-optimize="true" data-opv="2" />

    Provide any other optional information and create your block.
  </Tab>

  <Tab title="Modal">
    Navigate to the blocks page, click create new block, and select Modal Credentials for the type.

    For use in a push work pool, this block must have the token ID and token secret stored in the Token ID and Token
    Secret fields, respectively.
  </Tab>

  <Tab title="Coiled">
    Navigate to the blocks page, click create new block, and select Coiled Credentials for the type.  Provide the API token from the previous section.
  </Tab>
</Tabs>

### Create a push work pool

Now navigate to the work pools page.
Click **Create** to configure your push work pool by selecting a push option in the infrastructure type step.

<Tabs>
  <Tab title="AWS ECS">
    Each step has several optional fields that are detailed in the
    [work pools documentation](/v3/deploy/infrastructure-concepts/work-pools/).
    Select the block you created under the AWS Credentials field.
    This allows Prefect Cloud to securely interact with your ECS cluster.
  </Tab>

  <Tab title="Azure Container Instances">
    Fill in the subscription ID and resource group name from the resource group you created.
    Add the Azure Container Instance Credentials block you created in the step above.
  </Tab>

  <Tab title="Google Cloud Run">
    Each step has several optional fields that are detailed in
    [Manage infrastructure with work pools](/v3/deploy/infrastructure-concepts/work-pools/).
    Select the block you created under the GCP Credentials field.
    This allows Prefect Cloud to securely interact with your GCP project.
  </Tab>

  <Tab title="Modal">
    Each step has several optional fields that are detailed in the
    [work pools documentation](/v3/deploy/infrastructure-concepts/work-pools/).
    Select the block you created under the Modal Credentials field.
    This allows Prefect Cloud to securely interact with your Modal account.
  </Tab>

  <Tab title="Coiled">
    Each step has several optional fields that are detailed in the
    [work pools documentation](/v3/deploy/infrastructure-concepts/work-pools/).
    Select the block you created under the Coiled Credentials field.
    This allows Prefect Cloud to securely interact with your Coiled account.
  </Tab>
</Tabs>

Create your pool to be ready to deploy flows to your Push work pool.

## Deployment

You need to configure your [deployment](/v3/how-to-guides/deployment_infra/docker) to send flow runs to your push work pool.
For example, if you create a deployment through the interactive command line experience,
choose the work pool you just created. If you are deploying an existing `prefect.yaml` file, the deployment would contain:

```yaml
  work_pool:
    name: my-push-pool
```

Deploying your flow to the `my-push-pool` work pool ensures that runs that are ready for execution are
submitted immediately—without the need for a worker to poll for them.

<Warning>
  **Serverless infrastructure may require a certain image architecture**

  Serverless infrastructure may assume a certain Docker image architecture; for example,
  Google Cloud Run will fail to run images built with `linux/arm64` architecture. If using Prefect to build your image,
  you can change the image architecture through the `platform` keyword (for example, `platform="linux/amd64"`).
</Warning>

## Putting it all together

With your deployment created, navigate to its detail page and create a new flow run.
You'll see the flow start running without polling the work pool, because Prefect Cloud securely connected
to your serverless infrastructure, created a job, ran the job, and reported on its execution.

## Usage Limits

Push work pool usage is unlimited. However push work pools limit flow runs to 24 hours.

## Next steps

Learn more about [work pools](/v3/deploy/infrastructure-concepts/work-pools/) and [workers](/v3/deploy/infrastructure-concepts/workers/).

Learn about installing dependencies at runtime or baking them into your Docker image in the [Deploy to Docker](/v3/how-to-guides/deployment_infra/docker#automatically-build-a-custom-docker-image-with-a-local-dockerfile) guide.


# How to create deployments
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/create-deployments

Learn how to create deployments via the CLI, Python, or Terraform.

export const API = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect API</a>.</p>;

export const deployments = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/deployment",
  api: "https://app.prefect.cloud/api/docs#tag/Deployments",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/deployment"
};

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

There are several ways to create deployments, each catering to different organizational needs.

## Create deployments with static infrastructure

### Create a deployment with `serve`

This is the simplest way to get started with deployments:

```python
from prefect import flow


@flow
def my_flow():
    print("Hello, Prefect!")


if __name__ == "__main__":
    my_flow.serve(name="my-first-deployment", cron="* * * * *")
```

The `serve` method creates a deployment from your flow and immediately begins listening for scheduled runs to execute.
Providing `cron="* * * * *"` to `.serve` associates a schedule with your flow so it will run every minute of every day.

## Create deployments with dynamic infrastructure

For more configuration, you can create a deployment that uses a work pool.
Reasons to create a work-pool based deployment include:

* Wanting to run your flow on dynamically provisioned infrastructure
* Needing more control over the execution environment on a per-flow run basis
* Creating an infrastructure template to use across deployments

Work pools are popular with data platform teams because they allow you to manage infrastructure configuration across an organization.

Prefect offers two options for creating deployments with [dynamic infrastructure](/v3/deploy/infrastructure-concepts/work-pools):

* [Deployments created with the Python SDK](/v3/deploy/infrastructure-concepts/deploy-via-python)
* [Deployments created with a YAML file](/v3/deploy/infrastructure-concepts/prefect-yaml)

### Create a deployment with `deploy`

To define a deployment with a Python script, use the `flow.deploy` method.

Here's an example of a deployment that uses a work pool and bakes the code into a Docker image.

```python
from prefect import flow


@flow
def my_flow():
    print("Hello, Prefect!")

if __name__ == "__main__":
    my_flow.deploy(
        name="my-second-deployment",
        work_pool_name="my-work-pool",
        image="my-image",
        push=False,
        cron="* * * * *",
    )
```

To learn more about the `deploy` method, see [Deploy flows with Python](/v3/deploy/infrastructure-concepts/deploy-via-python).

### Create a deployment with a YAML file

If you'd rather take a declarative approach to defining a deployment through a YAML file, use a [`prefect.yaml` file](/v3/deploy/infrastructure-concepts/prefect-yaml).

Prefect provides an interactive CLI that walks you through creating a `prefect.yaml` file:

```bash
prefect deploy
```

The result is a `prefect.yaml` file for deployment creation.
The file contains `build`, `push`, and `pull` steps for building a Docker image, pushing code to a Docker registry, and pulling code at runtime.
Learn more about creating deployments with a YAML file in [Define deployments with YAML](/v3/deploy/infrastructure-concepts/prefect-yaml).

Prefect also provides [CI/CD options](/v3/deploy/infrastructure-concepts/deploy-ci-cd) for automatically creating YAML-based deployments.

### Create a deployment with Terraform

<TF name="deployments" href={deployments.tf} />

### Create a deployment with the API

<API name="deployments" href={deployments.api} />

<Tip>
  **Choosing between deployment methods**

  For many cases, `serve` is sufficient for scheduling and orchestration.
  The work pool / worker paradigm via `.deploy()` or `prefect deploy` can be great for complex infrastructure requirements and isolated flow run environments.
  You are not locked into one method and can combine approaches as needed.
</Tip>


# How to create schedules
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/create-schedules

Learn how to create schedules for your deployments.

export const deployments = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/deployment",
  api: "https://app.prefect.cloud/api/docs#tag/Deployments",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/deployment"
};

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

There are several ways to create a schedule for a deployment:

* Through the Prefect UI
* With the `cron`, `interval`, or `rrule` parameters if building your deployment with the
  [`serve` method](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes#serve-a-flow) of the `Flow` object or
  [the `serve` utility](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes#serve-multiple-flows-at-once) for managing multiple flows simultaneously
* If using [worker-based deployments](/v3/deploy/infrastructure-concepts/workers/)
  * When you define a deployment with `flow.serve` or `flow.deploy`
  * Through the interactive `prefect deploy` command
  * With the `deployments` -> `schedules` section of the `prefect.yaml` file

### Create schedules in the UI

You can add schedules in the **Schedules** section of a **Deployment** page in the UI.
To add a schedule select the **+ Schedule** button.
Choose **Interval** or **Cron** to create a schedule.

<Note>
  **What about RRule?**
  The UI does not support creating RRule schedules.
  However, the UI will display RRule schedules that you've created through the command line.
</Note>

The new schedule appears on the **Deployment** page where you created it.
New scheduled flow runs are visible in the **Upcoming** tab of the **Deployment** page.

To edit an existing schedule, select **Edit** from the three-dot menu next to a schedule on a **Deployment** page.

### Create schedules in Python

Specify the schedule when you create a deployment in a Python file with `flow.serve()`, `serve`, `flow.deploy()`, or `deploy`.
Just add the keyword argument `cron`, `interval`, or `rrule`.

| Argument    | Description                                                                                                                                                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `interval`  | An interval on which to execute the deployment. Accepts a number or a timedelta object to create a single schedule. If a number is given, it is interpreted as seconds. Also accepts an iterable of numbers or timedelta to create multiple schedules. |
| `cron`      | A cron schedule string of when to execute runs of this deployment. Also accepts an iterable of cron schedule strings to create multiple schedules.                                                                                                     |
| `rrule`     | An rrule schedule string of when to execute runs of this deployment. Also accepts an iterable of rrule schedule strings to create multiple schedules.                                                                                                  |
| `schedules` | A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options such as `timezone`.                                                                                    |
| `schedule`  | A schedule object defining when to execute runs of this deployment. Used to define additional scheduling options such as `timezone`.                                                                                                                   |
| `slug`      | An optional unique identifier for the schedule containing only lowercase letters, numbers, and hyphens. If not provided for a given schedule, the schedule will be unnamed.                                                                            |

The `serve` method below will create a deployment of `my_flow` with a cron schedule that creates runs every minute of every day:

```python
from prefect import flow

from myproject.flows import my_flow

my_flow.serve(name="flowing", cron="* * * * *")
```

If using deployments with [dynamic infrastructure](/v3/deploy/infrastructure-concepts/work-pools), the `deploy` method has the same schedule-based parameters.

When `my_flow` is served with this interval schedule, it will run every 10 minutes beginning at midnight on January, 1, 2026 in the `America/Chicago` timezone:

<CodeGroup>
  ```python prefect >= 3.1.16
  from datetime import timedelta, datetime
  from prefect.schedules import Interval

  from myproject.flows import my_flow

  my_flow.serve(
    name="flowing",
    schedule=Interval(
      timedelta(minutes=10),
      anchor_date=datetime(2026, 1, 1, 0, 0),
      timezone="America/Chicago"
    )
  )
  ```

  ```python prefect < 3.1.16
  from datetime import timedelta, datetime
  from prefect.client.schemas.schedules import IntervalSchedule

  from myproject.flows import my_flow

  my_flow.serve(
    name="flowing",
    schedules=[
      IntervalSchedule(
        interval=timedelta(minutes=10),
        anchor_date=datetime(2026, 1, 1, 0, 0),
        timezone="America/Chicago"
      )
    ]
  )
  ```
</CodeGroup>

<Tip>
  Keyword arguments for schedules are also accepted by the `to_deployment` method that converts a flow to a deployment.
</Tip>

### Create schedules with the CLI

You can create a schedule through the interactive `prefect deploy` command. You will be prompted to choose which type of schedule to create.

You can also create schedules for existing deployments using the `prefect deployment schedule create` command. This command allows you to specify schedule details directly without going through the interactive flow.

<Note>
  By default `prefect deployment schedule create` adds *additional* schedules to your deployment.
  Use the `--replace` flag to remove old schedules and update with the new one.
</Note>

**Examples:**

Create a cron schedule that runs every day at 9 AM:

```bash
prefect deployment schedule create my-deployment --cron "0 9 * * *"
```

Create an interval schedule that runs every 30 minutes:

```bash
prefect deployment schedule create my-deployment --interval 1800
```

Create a schedule with a specific timezone:

```bash
prefect deployment schedule create my-deployment --cron "0 9 * * *" --timezone "America/New_York"
```

Replace all existing schedules with a new one:

```bash
prefect deployment schedule create my-deployment --cron "0 9 * * *" --replace
```

### Create schedules in YAML

If you save the `prefect.yaml` file from the `prefect deploy` command, you will see it has a `schedules` section for your deployment.
Alternatively, you can create a `prefect.yaml` file from a recipe or from scratch and add a `schedules` section to it.

```yaml
deployments:
  ...
  schedules:
    - cron: "0 0 * * *"
      slug: "chicago-schedule"
      timezone: "America/Chicago"
      active: false
    - cron: "0 12 * * *"
      slug: "new-york-schedule"
      timezone: "America/New_York"
      active: true
    - cron: "0 18 * * *"
      slug: "london-schedule"
      timezone: "Europe/London"
      active: true
```

### Create schedules with Terraform

<TF name="schedules" href={deployments.tf} />

## Associate parameters with schedules

Using any of the above methods to create a schedule, you can bind parameters to your schedules.

For example, say you have a flow that sends an email.
Every day at 8:00 AM you want to send a message to one recipient, and at 8:05 AM you want to send a different message to another recipient.

Instead of creating independent deployments with different default parameters and schedules, you can bind parameters to the schedules themselves:

### Schedule parameters in Python

Whether using `.serve` or `.deploy`, you can pass `parameters` to your deployment `schedules`:

{/* pmd-metadata: notest */}

```python send_email_flow.py {13,17-20}
from prefect import flow
from prefect.schedules import Cron

@flow
def send_email(to: str, message: str = "Stop goofing off!"):
    print(f"Sending email to {to} with message: {message}")

send_email.serve(
  name="my-flow",
  schedules=[
    Cron(
      "0 8 * * *",
      slug="jim-email",
      parameters={"to": "jim.halpert@dundermifflin.com"}
    ),
    Cron(
      "5 8 * * *",
      slug="dwight-email",
      parameters={
        "to": "dwight.schrute@dundermifflin.com",
        "message": "Stop goofing off! You're assistant _to_ the regional manager!"
      }
    )
  ]
)
```

Note that our flow has a default `message` parameter, but we've overridden it for the second schedule.

This deployment will schedule runs that:

* Send "Stop goofing off!" to Jim at 8:00 AM every day
* Send "Stop goofing off! You're assistant *to* the regional manager!" to Dwight at 8:05 AM every day

<Tip>
  Use the same pattern to bind parameters to any schedule type in `prefect.schedules`.
  You can provide one schedule via the `schedule` kwarg or multiple schedules via `schedules`.
</Tip>

### Schedule parameters in `prefect.yaml`

You can also provide parameters to schedules in your `prefect.yaml` file.

```yaml prefect.yaml {4-11}
deployments:
  name: send-email
  entrypoint: send_email_flow.py:send_email
  schedules:
    - cron: "0 8 * * *"
      slug: "jim-email"
      parameters:
        to: "jim.halpert@dundermifflin.com"
    - cron: "5 8 * * *"
      slug: "dwight-email"
      parameters:
        to: "dwight.schrute@dundermifflin.com"
        message: "Stop goofing off! You're assistant _to_ the regional manager!"
```

## See also

* [Manage deployment schedules](/v3/how-to-guides/deployments/manage-schedules) - Learn how to pause and resume deployment schedules
* [Schedules concept](/v3/concepts/schedules) - Deep dive into schedule types and options
* [Deployments](/v3/concepts/deployments) - Learn more about deployments


# How to override job configuration for specific deployments
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/customize-job-variables

Override job variables on a deployment to set environment variables, specify a Docker image, allocate resources, and more.

export const deployments = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/deployment",
  api: "https://app.prefect.cloud/api/docs#tag/Deployments",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/deployment"
};

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

There are two ways to deploy flows to work pools: with a [`prefect.yaml` file](/v3/deploy/infrastructure-concepts/prefect-yaml) or using the [Python `deploy` method](/v3/deploy/infrastructure-concepts/deploy-via-python).
In both cases, you can add or override job variables to the work pool's defaults for a given deployment.
You can override both a work pool and a deployment when a flow run is triggered.

This guide explores common patterns for overriding job variables in
both deployment methods.

## Job variables

Job variables are infrastructure-related values that are configurable on a work pool.
You can override job variables on a per-deployment or
per-flow run basis. This allows you to dynamically change infrastructure from the work pool's defaults.

For example, when you create or edit a work pool, you can specify a set of environment variables to set in the
runtime environment of the flow run.

You could set the following value in the `env` field of any work pool:

```json
{
  "EXECUTION_ENV": "staging",
  "MY_NOT_SO_SECRET_CONFIG": "plumbus",
}
```

Rather than hardcoding these values into your work pool in the UI (and making them available to all
deployments associated with that work pool), you can override these values for a specific deployment.

## Override job variables on a deployment

Here's an example repo structure:

```
» tree
.
|── README.md
|── requirements.txt
|── demo_project
|   |── daily_flow.py
```

With a `demo_flow.py` file like:

```python
import os
from prefect import flow, task


@task
def do_something_important(not_so_secret_value: str) -> None:
    print(f"Doing something important with {not_so_secret_value}!")


@flow(log_prints=True)
def some_work():
    environment = os.environ.get("EXECUTION_ENVIRONMENT", "local")
    
    print(f"Coming to you live from {environment}!")
    
    not_so_secret_value = os.environ.get("MY_NOT_SO_SECRET_CONFIG")
    
    if not_so_secret_value is None:
        raise ValueError("You forgot to set MY_NOT_SO_SECRET_CONFIG!")

    do_something_important(not_so_secret_value)
```

### Use a `prefect.yaml` file

Imagine you have the following deployment definition in a `prefect.yaml` file at the
root of your repository:

```yaml
deployments:
- name: demo-deployment
  entrypoint: demo_project/demo_flow.py:some_work
  work_pool:
    name: local
  schedule: null
```

<Note>
  While not the focus of this guide, this deployment definition uses a default "global" `pull` step,
  because one is not explicitly defined on the deployment. For reference, here's what that would look like at
  the top of the `prefect.yaml` file:

  ```yaml
  pull:
  - prefect.deployments.steps.git_clone: &clone_repo
      repository: https://github.com/some-user/prefect-monorepo
      branch: main
  ```
</Note>

#### Hard-coded job variables

To provide the `EXECUTION_ENVIRONMENT` and `MY_NOT_SO_SECRET_CONFIG` environment variables to this deployment,
you can add a `job_variables` section to your deployment definition in the `prefect.yaml` file:

```yaml
deployments:
- name: demo-deployment
  entrypoint: demo_project/demo_flow.py:some_work
  work_pool:
    name: local
    job_variables:
        env:
            EXECUTION_ENVIRONMENT: staging
            MY_NOT_SO_SECRET_CONFIG: plumbus
  schedule: null
```

Then run `prefect deploy -n demo-deployment` to deploy the flow with these job variables.

You should see the job variables in the `Configuration` tab of the deployment in the UI:

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=b3ecc9849ed07d1db9e54180aec304e4" alt="Job variables in the UI" data-og-width="473" width="473" data-og-height="206" height="206" data-path="v3/img/guides/job-variables.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=91569c1fafedd01b7ac2d581cd21bf77 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=92986256d66ddd5d356e4865b68d96fd 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6f0cb3601718a9eea8899eba07f00c6b 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=1b5fd58c79e4534fd3558649f8f31041 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=1345895940ec28a661e40ec3290642d4 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=787e717931dc07609b83a6236a652c24 2500w" data-optimize="true" data-opv="2" />

#### Use existing environment variables

To use environment variables that are already set in your local environment, you can template
these in the `prefect.yaml` file using the `{{ $ENV_VAR_NAME }}` syntax:

```yaml
deployments:
- name: demo-deployment
  entrypoint: demo_project/demo_flow.py:some_work
  work_pool:
    name: local
    job_variables:
        env:
            EXECUTION_ENVIRONMENT: "{{ $EXECUTION_ENVIRONMENT }}"
            MY_NOT_SO_SECRET_CONFIG: "{{ $MY_NOT_SO_SECRET_CONFIG }}"
  schedule: null
```

<Note>
  This assumes that the machine where `prefect deploy` is run would have these environment variables set.

  ```bash
  export EXECUTION_ENVIRONMENT=staging
  export MY_NOT_SO_SECRET_CONFIG=plumbus
  ```
</Note>

Run `prefect deploy -n demo-deployment` to deploy the flow with these job variables,
and you should see them in the UI under the `Configuration` tab.

### Use the `.deploy()` method

If you're using the `.deploy()` method to deploy your flow, the process is similar. But instead of\
`prefect.yaml` defining the job variables, you can pass them as a dictionary to the `job_variables` argument
of the `.deploy()` method.

Add the following block to your `demo_project/daily_flow.py` file from the setup section:

```python
if __name__ == "__main__":
    flow.from_source(
        source="https://github.com/zzstoatzz/prefect-monorepo.git",
        entrypoint="src/demo_project/demo_flow.py:some_work"
    ).deploy(
        name="demo-deployment",
        work_pool_name="local", 
        job_variables={
            "env": {
                "EXECUTION_ENVIRONMENT": os.environ.get("EXECUTION_ENVIRONMENT", "local"),
                "MY_NOT_SO_SECRET_CONFIG": os.environ.get("MY_NOT_SO_SECRET_CONFIG")
            }
        }
    )
```

<Note>
  The above example works assuming a couple things:

  * the machine where this script is run would have these environment variables set.

  ```bash
  export EXECUTION_ENVIRONMENT=staging
  export MY_NOT_SO_SECRET_CONFIG=plumbus
  ```

  * `demo_project/daily_flow.py` *already exists* in the repository at the specified path
</Note>

Run the script to deploy the flow with the specified job variables.

```bash
python demo_project/daily_flow.py
```

The job variables should be visible in the UI under the `Configuration` tab.

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=b3ecc9849ed07d1db9e54180aec304e4" alt="Job variables in the UI" data-og-width="473" width="473" data-og-height="206" height="206" data-path="v3/img/guides/job-variables.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=91569c1fafedd01b7ac2d581cd21bf77 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=92986256d66ddd5d356e4865b68d96fd 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=6f0cb3601718a9eea8899eba07f00c6b 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=1b5fd58c79e4534fd3558649f8f31041 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=1345895940ec28a661e40ec3290642d4 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/job-variables.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=787e717931dc07609b83a6236a652c24 2500w" data-optimize="true" data-opv="2" />

## Override job variables on a flow run

When running flows, you can pass in job variables that override any values set on the work pool or deployment.
Any interface that runs deployments can accept job variables.

### Use the custom run form in the UI

Custom runs allow you to pass in a dictionary of variables into your flow run infrastructure. Using the same
`env` example from above, you could do the following:

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/deployment-job-variables.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=17edf6009b61e918e00e22f1a7eeee04" alt="Job variables through custom run" data-og-width="1706" width="1706" data-og-height="997" height="997" data-path="v3/img/ui/deployment-job-variables.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/deployment-job-variables.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=33a71fbd969a167370632458233cf731 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/deployment-job-variables.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=d375f2d8cca8bf71f6763f64a57fcaa0 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/deployment-job-variables.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=8cc216884c1cac68182749f165fbf61a 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/deployment-job-variables.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=d1e2edf85292072f923779f28b4acb52 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/deployment-job-variables.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c95a4260e3d37a9f4474cb6ab1e9e19f 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/deployment-job-variables.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=6e1dc83da40330f6d26170fb0ad30792 2500w" data-optimize="true" data-opv="2" />

### Use the CLI

Similarly, runs kicked off through the CLI accept job variables with the `-jv` or `--job-variable` flag.

```bash
prefect deployment run \
  --id "fb8e3073-c449-474b-b993-851fe5e80e53" \
  --job-variable MY_NEW_ENV_VAR=42 \
  --job-variable HELLO=THERE
```

### Use job variables in Terraform

<TF name="job variables" href={deployments.tf} />

### Use job variables in automations

Additionally, runs kicked off through automation actions can use job variables, including ones rendered from Jinja
templates.

<img src="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action-job-variable.png?fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=9d5df018b5b779875fdb8cba644b2562" alt="Job variables through automation action" data-og-width="1705" width="1705" data-og-height="642" height="642" data-path="v3/img/ui/automations-action-job-variable.png" srcset="https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action-job-variable.png?w=280&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=683e581ec64629ed0a068aaa8195b005 280w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action-job-variable.png?w=560&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=1af86bcbc49a19f81837378757dda354 560w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action-job-variable.png?w=840&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=3bda51f8e6ea6753fe61a41918d26067 840w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action-job-variable.png?w=1100&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=a26e7577f2504e99e3afe4e4678a7802 1100w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action-job-variable.png?w=1650&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=f0e2d11fd53ddad91a98a735a00b9a89 1650w, https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automations-action-job-variable.png?w=2500&fit=max&auto=format&n=ZU4EjeonScNdwFxn&q=85&s=8b2e068217dc8a5812a6c19a300a3322 2500w" data-optimize="true" data-opv="2" />


# How to deploy flows with Python
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/deploy-via-python

Learn how to use the Python SDK to deploy flows to run in work pools.

As an alternative to defining deployments in a `prefect.yaml` file, you can use the Python SDK to create deployments with [dynamic infrastructure](/v3/concepts/work-pools).
This can be more flexible if you have to programmatically gather configuration at deployment time.

## When to use `flow.deploy` instead of `flow.serve`

The `flow.serve` method is one [simple way to create a deployment with the Python SDK](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes#serve-a-flow). It's ideal when you have readily available, static infrastructure for your flow runs and you don't need the dynamic dispatch of infrastructure per flow run offered by work pools.

However, you might want to consider using `flow.deploy` to associate your flow with a work pool that enables dynamic dispatch of infrastructure per flow run for the following reasons:

1. **Cost optimization:** Dynamic infrastructure can help reduce costs by scaling resources up or down based on demand.
2. **Resource scarcity:** If you have limited persistent infrastructure, dynamic provisioning can help manage resource allocation more efficiently.
3. **Varying workloads:** For workflows with inconsistent resource needs, dynamic infrastructure can adapt to changing requirements.
4. **Cloud-native deployments:** When working with cloud providers that offer serverless or auto-scaling options.

Let's explore how to create a deployment using the Python SDK and leverage dynamic infrastructure through work pools.

## Prerequisites

Before deploying your flow using `flow.deploy`, ensure you have the following:

1. **A running Prefect server or Prefect Cloud workspace:** You can either run a Prefect server locally or use a Prefect Cloud workspace.
   To start a local server, run `prefect server start`. To use Prefect Cloud, sign up for an account at [app.prefect.cloud](https://app.prefect.cloud)
   and follow the [Connect to Prefect Cloud](/v3/manage/cloud/connect-to-cloud/) guide.

2. **A Prefect flow:** You should have a flow defined in your Python script. If you haven't created a flow yet, refer to the
   [Write Workflows](/v3/how-to-guides/workflows/write-and-run) guide.

3. **A work pool:** You need a work pool to manage the infrastructure for running your flow. If you haven't created a work pool, you can do so through
   the Prefect UI or using the Prefect CLI. For more information, see the [Work Pools](/v3/concepts/work-pools/) guide.

   For examples in this guide, we'll use a Docker work pool created by running:

   ```bash
   prefect work-pool create --type docker my-work-pool
   ```

4. **Docker:** Docker will be used to build and store the image containing your flow code. You can download and install
   Docker from the [official Docker website](https://www.docker.com/get-started/). If you don't want to use Docker, you
   can see other options in the [Use remote code storage](#use-remote-code-storage) section.

5. **(Optional) A Docker registry:** While not strictly necessary for local development, having an account with a Docker registry (such as
   Docker Hub) is recommended for storing and sharing your Docker images.

With these prerequisites in place, you're ready to deploy your flow using `flow.deploy`.

## Deploy a flow with `flow.deploy`

To deploy a flow using `flow.deploy` and Docker, follow these steps:

<Steps>
  <Step title="Write a flow">
    Ensure your flow is defined in a Python file. Let's use a simple example:

    ```python example.py
    from prefect import flow


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello, {name}!")
    ```
  </Step>

  <Step title="Add deployment configuration">
    Add a call to `flow.deploy` to tell Prefect how to deploy your flow.

    ```python example.py
    from prefect import flow


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello, {name}!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image="my-registry.com/my-docker-image:my-tag",
            push=False # switch to True to push to your image registry
        )
    ```
  </Step>

  <Step title="Deploy!">
    Run your script to deploy your flow.

    ```bash
    python example.py
    ```

    Running this script will:

    1. Build a Docker image containing your flow code and dependencies.
    2. Create a deployment associated with the specified work pool and image.
  </Step>
</Steps>

Building a Docker image for our flow allows us to have a consistent environment for our flow to run in. Workers for our work pool will use the image to run our flow.
In this example, we set `push=False` to skip pushing the image to a registry. This is useful for local development, and you can push your image to a registry such as Docker Hub in a production environment.

<Note>
  **Where's the Dockerfile?**

  In the above example, we didn't specify a Dockerfile. By default, Prefect will generate a Dockerfile for us that copies the flow code into an image and installs
  any additional dependencies.

  If you want to write and use your own Dockerfile, you can do so by passing a `dockerfile` parameter to `flow.deploy`.
</Note>

### Trigger a run

Now that we have our flow deployed, we can trigger a run via either the Prefect CLI or UI.

First, we need to start a worker to run our flow:

```bash
prefect worker start --pool my-work-pool
```

Then, we can trigger a run of our flow using the Prefect CLI:

```bash
prefect deployment run 'my-flow/my-deployment'
```

After a few seconds, you should see logs from your worker showing that the flow run has started and see the state update in the UI.

## Deploy with a schedule

To deploy a flow with a schedule, you can use one of the following options:

* `interval`

  Defines the interval at which the flow should run. Accepts an integer or float value representing the number of seconds between runs or a `datetime.timedelta` object.

  <Expandable title="Example">
    ```python interval.py
    from datetime import timedelta
    from prefect import flow


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello, {name}!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image="my-registry.com/my-docker-image:my-tag",
            push=False,
            # Run once a minute
            interval=timedelta(minutes=1)
        )
    ```
  </Expandable>

* `cron`

  Defines when a flow should run using a cron string.

  <Expandable title="Example">
    ```python cron.py
    from prefect import flow


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello, {name}!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image="my-registry.com/my-docker-image:my-tag",
            push=False,
            # Run once a day at midnight
            cron="0 0 * * *"
        )
    ```
  </Expandable>

* `rrule`

  Defines a complex schedule using an `rrule` string.

  <Expandable title="Example">
    ```python rrule.py
    from prefect import flow


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello, {name}!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image="my-registry.com/my-docker-image:my-tag",
            push=False,
            # Run every weekday at 9 AM
            rrule="FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0"
        )
    ```
  </Expandable>

* `schedules`

  Defines multiple schedules for a deployment. This option provides flexibility for:

  * Setting up various recurring schedules
  * Implementing complex scheduling logic
  * Applying timezone offsets to schedules

  <Expandable title="Example">
    ```python schedules.py
    from datetime import datetime, timedelta
    from prefect import flow
    from prefect.schedules import Interval


    @flow(log_prints=True)
    def my_flow(name: str = "world"):
        print(f"Hello, {name}!")


    if __name__ == "__main__":
        my_flow.deploy(
            name="my-deployment",
            work_pool_name="my-work-pool",
            image="my-registry.com/my-docker-image:my-tag",
            push=False,
            # Run every 10 minutes starting from January 1, 2023
            # at 00:00 Central Time
            schedules=[
                Interval(
                    timedelta(minutes=10),
                    anchor_date=datetime(2023, 1, 1, 0, 0),
                    timezone="America/Chicago"
                )
            ]
        )
    ```
  </Expandable>

  Learn more about schedules [here](/v3/how-to-guides/deployments/create-schedules).

## Use remote code storage

In addition to storing your  code in a Docker image, Prefect also supports deploying your code to remote storage. This approach allows you to
store your flow code in a remote location, such as a Git repository or cloud storage service.

Using remote storage for your code has several advantages:

1. Faster iterations: You can update your flow code without rebuilding Docker images.
2. Reduced storage requirements: You don't need to store large Docker images for each code version.
3. Flexibility: You can use different storage backends based on your needs and infrastructure.

Using an existing remote Git repository like GitHub, GitLab, or Bitbucket works really well as remote code storage because:

1. Your code is already there.
2. You can deploy to multiple environments via branches and tags.
3. You can roll back to previous versions of your flows.

To deploy using remote storage, you'll need to specify where your code is stored by using `flow.from_source` to first load your flow code from a remote location.

Here's an example of loading a flow from a Git repository and deploying it:

```python git-deploy.py
from prefect import flow


if __name__ == "__main__":
    flow.from_source(
        source="https://github.com/username/repository.git",
        entrypoint="path/to/your/flow.py:your_flow_function"
    ).deploy(
        name="my-deployment",
        work_pool_name="my-work-pool",
    )
```

The `source` parameter can accept a variety of remote storage options including:

* Git repositories
* S3 buckets (using the `s3://` scheme)
* Google Cloud Storage buckets (using the `gs://` scheme)
* Azure Blob Storage (using the `az://` scheme)

The `entrypoint` parameter is the path to the flow function within your repository combined with the name of the flow function.

Learn more about remote code storage [here](/v3/deploy/infrastructure-concepts/store-flow-code/).

## Set default parameters

You can set default parameters for a deployment using the `parameters` keyword argument in `flow.deploy`.

```python default-parameters.py
from prefect import flow


@flow
def my_flow(name: str = "world"):
    print(f"Hello, {name}!")


if __name__ == "__main__":
    my_flow.deploy(
        name="my-deployment",
        work_pool_name="my-work-pool",
        # Will print "Hello, Marvin!" by default instead of "Hello, world!"
        parameters={"name": "Marvin"},
        image="my-registry.com/my-docker-image:my-tag",
        push=False,
    )
```

Note these parameters can still be overridden on a per-deployment basis.

## Set job variables

You can set default job variables for a deployment using the `job_variables` keyword argument in `flow.deploy`.
The job variables provided will override the values set on the work pool.

```python job-variables.py
import os
from prefect import flow


@flow
def my_flow():
    name = os.getenv("NAME", "world")
    print(f"Hello, {name}!")


if __name__ == "__main__":
    my_flow.deploy(
        name="my-deployment",
        work_pool_name="my-work-pool",
        # Will print "Hello, Marvin!" by default instead of "Hello, world!"
        job_variables={"env": {"NAME": "Marvin"}},
        image="my-registry.com/my-docker-image:my-tag",
        push=False,
    )
```

Job variables can be used to customize environment variables, resources limits, and other infrastructure options, allowing fine-grained control over your infrastructure on a per-deployment or per-flow-run basis.
Any variable defined in the base job template of the associated work pool can be overridden by a job variable.

You can learn more about job variables [here](/v3/how-to-guides/deployments/customize-job-variables).

## Deploy multiple flows

To deploy multiple flows at once, use the `deploy` function.

```python multi-deploy.py
from prefect import flow, deploy


@flow
def my_flow_1():
    print("I'm number one!")


@flow
def my_flow_2():
    print("Always second...")


if __name__ == "__main__":
    deploy(
        # Use the `to_deployment` method to specify configuration
        #specific to each deployment
        my_flow_1.to_deployment("my-deployment-1"),
        my_flow_2.to_deployment("my-deployment-2"),

        # Specify shared configuration for both deployments
        image="my-registry.com/my-docker-image:my-tag",
        push=False,
        work_pool_name="my-work-pool",
    )
```

When we run the above script, it will build a single Docker image for both deployments.
This approach offers the following benefits:

* Saves time and resources by avoiding redundant image builds.
* Simplifies management by maintaining a single image for multiple flows.

## Further reading

* [Work Pools](/v3/concepts/work-pools/)
* [Store Flow Code](/v3/deploy/infrastructure-concepts/store-flow-code/)
* [Customize Infrastructure](/v3/how-to-guides/deployments/customize-job-variables)
* [Schedules](/v3/how-to-guides/deployments/create-schedules)
* [Write Workflows](/v3/how-to-guides/workflows/write-and-run)


# Manage Deployment schedules
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/manage-schedules

Learn how to pause and resume deployment schedules using the Prefect CLI.

You can pause and resume deployment schedules individually or in bulk.
This can be useful for maintenance windows, migration scenarios, or organizational changes.

## Prerequisites

To manage deployment schedules, you need:

* A Prefect server or [Prefect Cloud](/v3/get-started/quickstart) workspace
* One or more [deployments](/v3/how-to-guides/deployments/create-deployments) with [schedules](/v3/how-to-guides/deployments/create-schedules)
* [Prefect installed](/v3/get-started/install)

## Manage specific schedules

To pause or resume individual deployment schedules, you need the deployment name and schedule ID.

### List schedules for a deployment

First, list the schedules to get the schedule ID:

```bash
prefect deployment schedule ls my-flow/my-deployment
```

### Pause a specific schedule

```bash
prefect deployment schedule pause my-flow/my-deployment <schedule-id>
```

### Resume a specific schedule

```bash
prefect deployment schedule resume my-flow/my-deployment <schedule-id>
```

## Manage schedules in bulk

When you have many deployments with active schedules, you can pause or resume all of them at once using the `--all` flag.

### Pause all schedules

Use the `--all` flag with the `pause` command to pause all active schedules across all deployments:

```bash
prefect deployment schedule pause --all
```

This command pauses all active schedules across deployments in the current workspace. In interactive mode, you'll be asked to confirm.

Example output:

```
Paused schedule for deployment my-flow/daily-sync
Paused schedule for deployment data-pipeline/hourly-update
Paused schedule for deployment ml-model/weekly-training
Paused 3 deployment schedule(s).
```

### Resume all schedules

Similarly, use the `--all` flag with the `resume` command to resume all paused schedules:

```bash
prefect deployment schedule resume --all
```

This command resumes all paused schedules across deployments in the current workspace. In interactive mode, you'll be asked to confirm.

Example output:

```
Resumed schedule for deployment my-flow/daily-sync
Resumed schedule for deployment data-pipeline/hourly-update
Resumed schedule for deployment ml-model/weekly-training
Resumed 3 deployment schedule(s).
```

### Skip confirmation prompt

To skip the interactive confirmation (useful for CI/CD pipelines or scripts), use the `--no-prompt` flag:

```bash
prefect --no-prompt deployment schedule pause --all
prefect --no-prompt deployment schedule resume --all
```

## Use cases

### Maintenance windows

Pause all schedules during system maintenance:

```bash
# Before maintenance
prefect deployment schedule pause --all

# Perform maintenance tasks...

# After maintenance
prefect deployment schedule resume --all
```

### Development environment management

Quickly pause all schedules in a development environment:

```bash
# Pause all dev schedules
prefect --profile dev deployment schedule pause --all

# Resume when ready
prefect --profile dev deployment schedule resume --all
```

## Important notes

<Warning>
  **Use caution with bulk operations**

  The `--all` flag affects all deployment schedules in your workspace.
  In interactive mode, you'll be prompted to confirm the operation showing the exact number of schedules that will be affected.
  Always verify you're in the correct workspace/profile before running bulk operations.
</Warning>

## See also

* [Create schedules](/v3/how-to-guides/deployments/create-schedules) - Learn how to create schedules for your deployments
* [Run deployments](/v3/how-to-guides/deployments/run-deployments) - Learn how to trigger deployment runs manually
* [Deployment concepts](/v3/concepts/deployments) - Understand deployments and their schedules


# How to define deployments with YAML
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/prefect-yaml

Use YAML to schedule and trigger flow runs and manage your code and deployments.

The `prefect.yaml` file is a YAML file describing base settings for your deployments, procedural steps for preparing deployments,
and instructions for preparing the execution environment for a deployment run.

Initialize your deployment configuration, which creates the `prefect.yaml` file, with the CLI command `prefect init`
in any directory or repository that stores your flow code.

<Tip>
  **Deployment configuration recipes**

  Prefect ships with many off-the-shelf "recipes" that allow you to get started with more structure within
  your `prefect.yaml` file. Run `prefect init` to be prompted with available recipes in your installation.
  You can provide a recipe name in your initialization command with the `--recipe` flag, otherwise Prefect will attempt to
  guess an appropriate recipe based on the structure of your working directory (for example if you initialize within a `git`
  repository, Prefect will use the `git` recipe).
</Tip>

The `prefect.yaml` file contains:

* deployment configuration for deployments created from this file
* default instructions for how to build and push any necessary code artifacts (such as Docker images)
* default instructions for pulling a deployment in remote  execution environments (for example, cloning a GitHub repository).

You can override any deployment configuration through options available on the `prefect deploy` CLI command when creating a deployment.

<Tip>
  **`prefect.yaml` file flexibility**

  In older versions of Prefect, this file must be in the root of your repository or project directory and named `prefect.yaml`.
  With Prefect 3, this file can be located in a directory outside the project or a subdirectory inside the project.
  It can be named differently if the filename ends in `.yaml`. You can have multiple `prefect.yaml` files with the same name
  in different directories.

  By default, `prefect deploy` uses a `prefect.yaml` file in the project's root directory. To use a custom deployment
  configuration file, supply the new  `--prefect-file` CLI argument when running the `deploy` command from the root of your
  project directory:

  `prefect deploy --prefect-file path/to/my_file.yaml`
</Tip>

The base structure for `prefect.yaml` looks like this:

```yaml
# generic metadata
prefect-version: null
name: null

# preparation steps
build: null
push: null

# runtime steps
pull: null

# deployment configurations
deployments:
- # base metadata
  name: null
  version: null
  tags: []
  description: null
  schedule: null

  # flow-specific fields
  entrypoint: null
  parameters: {}

  # infra-specific fields
  work_pool:
    name: null
    work_queue_name: null
    job_variables: {}
```

The metadata fields are always pre-populated for you. These fields are for bookkeeping purposes only. The other sections are
pre-populated based on recipe; if no recipe is provided, Prefect attempts to guess an appropriate one based on local configuration.

You can create deployments with the CLI command `prefect deploy` without altering the `deployments` section of your
`prefect.yaml` file. The `prefect deploy` command helps in deployment creation through interactive prompts. The `prefect.yaml`
file facilitates version-controlling your deployment configuration and managing multiple deployments.

## Deployment actions

Deployment actions defined in your `prefect.yaml` file control the lifecycle of the creation and execution of your deployments.
The three actions available are `build`, `push`, and `pull`.
`pull` is the only required deployment action. It defines how Prefect pulls your deployment in remote execution
environments.

Each action is defined as a list of steps executed in sequence. Each step has the following format:

```yaml
section:
- prefect_package.path.to.importable.step:
  id: "step-id" # optional
  requires: "pip-installable-package-spec" # optional
  kwarg1: value
  kwarg2: more-values
```

Every step optionally provides a `requires` field. Prefect uses this to auto-install if the step is not
found in the current environment. Each step can specify an `id` to reference outputs in
future steps. The additional fields map directly to Python keyword arguments to the step function. Within a given section,
steps always run in their order within the `prefect.yaml` file.

<Tip>
  **Deployment instruction overrides**

  You can override `build`, `push`, and `pull` sections on a per-deployment basis; define `build`, `push`, and `pull`
  fields within a deployment definition in the `prefect.yaml` file.

  The `prefect deploy` command uses any `build`, `push`, or `pull` instructions from the deployment's definition in the
  `prefect.yaml` file.

  This capability is useful for multiple deployments that require different deployment instructions.
</Tip>

### The build action

Use the build section of `prefect.yaml` to specify setup steps or dependencies,
(like creating a Docker image), required to run your deployments.

If you initialize with the Docker recipe, you are prompted to provide
required information, such as image name and tag:

```bash
prefect init --recipe docker
>> image_name: < insert image name here >
>> tag: < insert image tag here >
```

<Tip>
  **Use `--field` to avoid the interactive experience**

  We recommend that you only initialize a recipe when first creating your deployment structure. Then store
  your configuration files within version control.
  Sometimes you may need to initialize programmatically and avoid the interactive prompts.
  To do this, provide all required fields for your recipe using the `--field` flag:

  ```bash
  prefect init --recipe docker \
      --field image_name=my-repo/my-image \
      --field tag=my-tag
  ```

  ```yaml
  build:
  - prefect_docker.deployments.steps.build_docker_image:
    requires: prefect-docker>=0.3.0
    image_name: my-repo/my-image
    tag: my-tag
    dockerfile: auto
  ```
</Tip>

Once you confirm that these fields are set to their desired values, this step automatically builds a Docker image with
the provided name and tag and pushes it to the repository referenced by the image name.
This step produces optional fields for future steps, or within `prefect.yaml` as template values.

We recommend using a templated `{{ image }}` within `prefect.yaml` (specifically in the work pool's `job_variables` section).
By avoiding hardcoded values, the build step and deployment specification won't have mismatched values.

<Note>
  **Some steps require Prefect integrations**

  In the build step example above, you relied on the `prefect-docker` package; in cases that deal with external services,
  additional required packages are auto-installed for you.
</Note>

**Pass output to downstream steps**

Each deployment action can be composed of multiple steps. For example, to build a Docker image tagged with the
current commit hash, use the `run_shell_script` step and feed the output into the `build_docker_image` step:

```yaml
build:
- prefect.deployments.steps.run_shell_script:
    id: get-commit-hash
    script: git rev-parse --short HEAD
    stream_output: false
- prefect_docker.deployments.steps.build_docker_image:
    requires: prefect-docker
    image_name: my-image
    image_tag: "{{ get-commit-hash.stdout }}"
    dockerfile: auto
```

The `id` field is used in the `run_shell_script` step to reference its output in the next step.

### The push action

The push section is most critical for situations where code is not stored on persistent filesystems or in version control.
In this scenario, code is often pushed and pulled from a Cloud storage bucket (for example, S3, GCS, Azure Blobs).
The push section allows users to specify and customize the logic for pushing this code repository to arbitrary remote locations.

For example, a user who stores their code in an S3 bucket and relies on default worker settings for its runtime environment
could use the `s3` recipe:

```bash
prefect init --recipe s3
>> bucket: < insert bucket name here >
```

In your newly created`prefect.yaml` file, you should find that the `push` and `pull` sections have been templated out
as follows:

```yaml
push:
- prefect_aws.deployments.steps.push_to_s3:
    id: push-code
    requires: prefect-aws>=0.3.0
    bucket: my-bucket
    folder: project-name
    credentials: null

pull:
- prefect_aws.deployments.steps.pull_from_s3:
    requires: prefect-aws>=0.3.0
    bucket: my-bucket
    folder: "{{ push-code.folder }}"
    credentials: null
```

The bucket is populated with the provided value (which also could have been provided with the `--field` flag); note that the
`folder` property of the `pull` step is a template - the `push_to_s3` step outputs both a `bucket` value as well as a `folder`
value for the template downstream steps. This helps you keep your steps consistent across edits.

As discussed above, if you use [blocks](/v3/concepts/blocks/), you can template the credentials section with
a block reference for secure and dynamic credentials access:

```yaml
push:
- prefect_aws.deployments.steps.push_to_s3:
    requires: prefect-aws>=0.3.0
    bucket: my-bucket
    folder: project-name
    credentials: "{{ prefect.blocks.aws-credentials.dev-credentials }}"
```

Anytime you run `prefect deploy`, this `push` section executes upon successful completion of your `build` section.

### The pull action

The pull section is the most important section within the `prefect.yaml` file. It contains instructions for preparing your
flows for a deployment run. These instructions execute each time a deployment in this folder is run through a worker.

There are three main types of steps that typically show up in a `pull` section:

* `set_working_directory`: this step sets the working directory for the process prior to importing your flow
* `git_clone`: this step clones the provided repository on the provided branch
* `pull_from_{cloud}`: this step pulls the working directory from a Cloud storage location (for example, S3)

<Tip>
  **Use block and variable references**

  All [block and variable references](#templating-options) within your pull step will remain unresolved until runtime and
  are pulled each time your deployment runs. This avoids storing sensitive information insecurely; it
  also allows you to manage certain types of configuration from the API and UI without having to rebuild your deployment every time.
</Tip>

Below is an example of how to use an existing `GitHubCredentials` block to clone a private GitHub repository:

```yaml
pull:
- prefect.deployments.steps.git_clone:
    repository: https://github.com/org/repo.git
    credentials: "{{ prefect.blocks.github-credentials.my-credentials }}"
```

Alternatively, you can specify a `BitBucketCredentials` or `GitLabCredentials` block to clone from Bitbucket or GitLab. In
lieu of a credentials block, you can also provide a GitHub, GitLab, or Bitbucket token directly to the 'access\_token\` field.
Use a Secret block to do this securely:

```yaml
pull:
- prefect.deployments.steps.git_clone:
    repository: https://bitbucket.org/org/repo.git
    access_token: "{{ prefect.blocks.secret.bitbucket-token }}"
```

## Utility steps

Use utility steps within a build, push, or pull action to assist in managing the deployment lifecycle:

* `run_shell_script` allows for the execution of one or more shell commands in a subprocess, and returns the standard output
  and standard error of the script. This step is useful for scripts that require execution in a specific environment, or those
  which have specific input and output requirements. Note that setting `stream_output: true` for `run_shell_script` writes the
  output and error to stdout in the execution environment, which will not be sent to the Prefect API.

Here is an example of retrieving the short Git commit hash of the current repository to use as a Docker image tag:

```yaml
build:
- prefect.deployments.steps.run_shell_script:
    id: get-commit-hash
    script: git rev-parse --short HEAD
    stream_output: false
- prefect_docker.deployments.steps.build_docker_image:
    requires: prefect-docker>=0.3.0
    image_name: my-image
    tag: "{{ get-commit-hash.stdout }}"
    dockerfile: auto
```

<Warning>
  **Provided environment variables are not expanded by default**

  To expand environment variables in your shell script, set `expand_env_vars: true` in your `run_shell_script` step. For example:

  ```yaml
  - prefect.deployments.steps.run_shell_script:
      id: get-user
      script: echo $USER
      stream_output: true
      expand_env_vars: true
  ```

  Without `expand_env_vars: true`, the above step returns a literal string `$USER` instead of the current user.
</Warning>

* `pip_install_requirements` installs dependencies from a `requirements.txt` file within a specified directory.

Here is an example of installing dependencies from a `requirements.txt` file after cloning:

```yaml
pull:
- prefect.deployments.steps.git_clone:
    id: clone-step # needed to be referenced in subsequent steps
    repository: https://github.com/org/repo.git
- prefect.deployments.steps.pip_install_requirements:
    directory: "{{ clone-step.directory }}" # `clone-step` is a user-provided `id` field
    requirements_file: requirements.txt
```

Here is an example that retrieves an access token from a third party key vault and uses it in a private clone step:

```yaml
pull:
- prefect.deployments.steps.run_shell_script:
    id: get-access-token
    script: az keyvault secret show --name <secret name> --vault-name <secret vault> --query "value" --output tsv
    stream_output: false
- prefect.deployments.steps.git_clone:
    repository: https://bitbucket.org/samples/deployments.git
    branch: master
    access_token: "{{ get-access-token.stdout }}"
```

You can also run custom steps by packaging them. In the example below, `retrieve_secrets` is a custom python module packaged
into the default working directory of a Docker image (which is /opt/prefect by default).
`main` is the function entry point, which returns an access token (for example, `return {"access_token": access_token}`) like the
preceding example, but utilizing the Azure Python SDK for retrieval.

```yaml
- retrieve_secrets.main:
    id: get-access-token
- prefect.deployments.steps.git_clone:
    repository: https://bitbucket.org/samples/deployments.git
    branch: master
    access_token: '{{ get-access-token.access_token }}'
```

## Templating options

Values that you place within your `prefect.yaml` file can reference dynamic values in several different ways:

* **step outputs**: every step of both `build` and `push` produce named fields such as `image_name`; you can reference these
  fields within `prefect.yaml` and `prefect deploy` will populate them with each call. References must be enclosed in double
  brackets and in `"{{ field_name }}"` format
* **blocks**: you can reference [Prefect blocks](/v3/concepts/blocks) with the
  `{{ prefect.blocks.block_type.block_slug }}` syntax. It is highly recommended that you use block references for any sensitive
  information (such as a GitHub access token or any credentials) to avoid hardcoding these values in plaintext
* **variables**: you can reference [Prefect variables](/v3/concepts/variables) with the
  `{{ prefect.variables.variable_name }}` syntax. Use variables to reference non-sensitive, reusable pieces of information
  such as a default image name or a default work pool name.
* **environment variables**: you can also reference environment variables with the special syntax `{{ $MY_ENV_VAR }}`.
  This is especially useful for referencing environment variables that are set at runtime.

Here's a `prefect.yaml` file as an example:

```yaml
build:
- prefect_docker.deployments.steps.build_docker_image:
    id: build-image
    requires: prefect-docker>=0.6.0
    image_name: my-repo/my-image
    tag: my-tag
    dockerfile: auto

push:
- prefect_docker.deployments.steps.push_docker_image:
    requires: prefect-docker>=0.6.0
    image_name: my-repo/my-image
    tag: my-tag
    credentials: "{{ prefect.blocks.docker-registry-credentials.dev-registry }}"

deployments:
- # base metadata
  name: null
  version: "{{ build-image.tag }}"
  tags:
  - "{{ $my_deployment_tag }}"
  - "{{ prefect.variables.some_common_tag }}"
  description: null
  schedule: null
  concurrency_limit: null

  # flow-specific fields
  entrypoint: null
  parameters: {}

  # infra-specific fields
  work_pool:
    name: "my-k8s-work-pool"
    work_queue_name: null
    job_variables:
      image: "{{ build-image.image }}"
      cluster_config: "{{ prefect.blocks.kubernetes-cluster-config.my-favorite-config }}"
```

So long as your `build` steps produce fields called `image_name` and `tag`, every time you deploy a new version of our deployment,
the `{{ build-image.image }}` variable is dynamically populated with the relevant values.

<Note>
  **Docker step**

  The most commonly used build step is `prefect_docker.deployments.steps.build_docker_image` which produces both the `image_name` and `tag` fields.
</Note>

A `prefect.yaml` file can have multiple deployment configurations that control the behavior of several deployments.
You can manage these deployments independently of one another, allowing you to deploy the same flow with different
configurations in the same codebase.

## Work with multiple deployments with prefect.yaml

Prefect supports multiple deployment declarations within the `prefect.yaml` file. This method of declaring multiple
deployments supports version control for all deployments through a single command.

Add new deployment declarations to the `prefect.yaml` file with a new entry to the `deployments` list.
Each deployment declaration must have a unique `name` field to select deployment declarations when using the
`prefect deploy` command.

<Warning>
  When using a `prefect.yaml` file that is in another directory or differently named, the value for
  the deployment `entrypoint` must be relative to the root directory of the project.
</Warning>

For example, consider the following `prefect.yaml` file:

```yaml
build: ...
push: ...
pull: ...

deployments:
  - name: deployment-1
    entrypoint: flows/hello.py:my_flow
    parameters:
        number: 42,
        message: Don't panic!
    work_pool:
        name: my-process-work-pool
        work_queue_name: primary-queue

  - name: deployment-2
    entrypoint: flows/goodbye.py:my_other_flow
    work_pool:
        name: my-process-work-pool
        work_queue_name: secondary-queue

  - name: deployment-3
    entrypoint: flows/hello.py:yet_another_flow
    work_pool:
        name: my-docker-work-pool
        work_queue_name: tertiary-queue
```

This file has three deployment declarations, each referencing a different flow. Each deployment declaration has a unique `name`
field and can be deployed individually with the `--name` flag when deploying.

For example, to deploy `deployment-1`, run:

```bash
prefect deploy --name deployment-1
```

To deploy multiple deployments, provide multiple `--name` flags:

```bash
prefect deploy --name deployment-1 --name deployment-2
```

To deploy multiple deployments with the same name, prefix the deployment name with its flow name:

```bash
prefect deploy --name my_flow/deployment-1 --name my_other_flow/deployment-1
```

To deploy all deployments, use the `--all` flag:

```bash
prefect deploy --all
```

To deploy deployments that match a pattern, run:

```bash
prefect deploy -n my-flow/* -n *dev/my-deployment -n dep*prod
```

The above command deploys:

* all deployments from the flow `my-flow`
* all flows ending in `dev` with a deployment named
  `my-deployment`
* all deployments starting with `dep` and ending in `prod`.

### Non-interactive deployment

For CI/CD pipelines and automated environments, use the `--no-prompt` flag to skip interactive prompts:

```bash
prefect --no-prompt deploy --name my-deployment
```

This prevents the command from hanging on prompts and will fail clearly if required information is missing.

<Note>
  **CLI Options When deploying multiple deployments**

  When deploying more than one deployment with a single `prefect deploy` command, any additional attributes provided are ignored.

  To provide overrides to a deployment through the CLI, you must deploy that deployment individually.
</Note>

### Reuse configuration across deployments

Because a `prefect.yaml` file is a standard YAML file, you can use [YAML aliases](https://yaml.org/spec/1.2.2/#71-alias-nodes)
to reuse configuration across deployments.

This capability allows multiple deployments to share the work pool configuration, deployment actions, or other
configurations.

Declare a YAML alias with the `&{alias_name}` syntax and insert that alias elsewhere in the file with the `*{alias_name}`
syntax. When aliasing YAML maps, you can override specific fields of the aliased map with the `<<: *{alias_name}` syntax and
adding additional fields below.

We recommend adding a `definitions` section to your `prefect.yaml` file at the same level as the `deployments` section to store your
aliases.

For example:

```yaml
build: ...
push: ...
pull: ...

definitions:
    work_pools:
        my_docker_work_pool: &my_docker_work_pool
            name: my-docker-work-pool
            work_queue_name: default
            job_variables:
                image: "{{ build-image.image }}"
    schedules:
        every_ten_minutes: &every_10_minutes
            interval: 600
    actions:
        docker_build: &docker_build
            - prefect_docker.deployments.steps.build_docker_image: &docker_build_config
                id: build-image
                requires: prefect-docker>=0.3.0
                image_name: my-example-image
                tag: dev
                dockerfile: auto

        docker_push: &docker_push
            - prefect_docker.deployments.steps.push_docker_image: &docker_push_config
                requires: prefect-docker>=0.6.0
                image_name: my-example-image
                tag: dev
                credentials: "{{ prefect.blocks.docker-registry-credentials.dev-registry }}"

deployments:
  - name: deployment-1
    entrypoint: flows/hello.py:my_flow
    schedule: *every_10_minutes
    parameters:
        number: 42,
        message: Don't panic!
    work_pool: *my_docker_work_pool
    build: *docker_build # Uses the full docker_build action with no overrides
    push: *docker_push

  - name: deployment-2
    entrypoint: flows/goodbye.py:my_other_flow
    work_pool: *my_docker_work_pool
    build:
        - prefect_docker.deployments.steps.build_docker_image:
            <<: *docker_build_config # Uses the docker_build_config alias and overrides the dockerfile field
            dockerfile: Dockerfile.custom
    push: *docker_push

  - name: deployment-3
    entrypoint: flows/hello.py:yet_another_flow
    schedule: *every_10_minutes
    work_pool:
        name: my-process-work-pool
        work_queue_name: primary-queue

```

In the above example, YAML aliases reuse work pool, schedule, and build configuration across multiple deployments:

* `deployment-1` and `deployment-2` use the same work pool configuration
* `deployment-1` and `deployment-3` use the same schedule
* `deployment-1` and `deployment-2` use the same build deployment action, but `deployment-2` overrides the `dockerfile` field to use a custom Dockerfile

## Deployment declaration reference

### Deployment fields

These are fields you can add to each deployment declaration.

| Property                                                | Description                                                                                                                                                                                                                         |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                                  | The name to give to the created deployment. Used with the `prefect deploy` command to create or update specific deployments.                                                                                                        |
| `version`                                               | An optional version for the deployment.                                                                                                                                                                                             |
| `tags`                                                  | A list of strings to assign to the deployment as tags.                                                                                                                                                                              |
| <span class="no-wrap">`description`</span>              | An optional description for the deployment.                                                                                                                                                                                         |
| `schedule`                                              | An optional [schedule](/v3/how-to-guides/deployments/create-schedules) to assign to the deployment. Fields for this section are documented in the [Schedule Fields](#schedule-fields) section.                                      |
| `concurrency_limit`                                     | An optional [deployment concurrency limit](/v3/deploy/index#concurrency-limiting). Fields for this section are documented in the [Concurrency Limit Fields](#concurrency-limit-fields) section.                                     |
| `triggers`                                              | An optional array of [triggers](/v3/how-to-guides/automations/creating-deployment-triggers) to assign to the deployment                                                                                                             |
| `entrypoint`                                            | Required path to the `.py` file containing the flow you want to deploy (relative to the root directory of your development folder) combined with the name of the flow function. In the format `path/to/file.py:flow_function_name`. |
| `parameters`                                            | Optional default values to provide for the parameters of the deployed flow. Should be an object with key/value pairs.                                                                                                               |
| <span class="no-wrap">`enforce_parameter_schema`</span> | Boolean flag that determines whether the API should validate the parameters passed to a flow run against the parameter schema generated for the deployed flow.                                                                      |
| `work_pool`                                             | Information of where to schedule flow runs for the deployment. Fields for this section are documented in the [Work Pool Fields](#work-pool-fields) section.                                                                         |

### Schedule fields

These are fields you can add to a deployment declaration's `schedule` section.

| Property                                   | Description                                                                                                                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `interval`                                 | Number of seconds indicating the time between flow runs. Cannot use them in conjunction with `cron` or `rrule`.                                                                                                          |
| <span class="no-wrap">`anchor_date`</span> | Datetime string indicating the starting or "anchor" date to begin the schedule. If no `anchor_date` is supplied, the current UTC time is used. Can only use with `interval`.                                             |
| `timezone`                                 | String name of a time zone, used to enforce localization behaviors like DST boundaries. See the [IANA Time Zone Database](https://www.iana.org/time-zones) for valid time zones.                                         |
| `cron`                                     | A valid cron string. Cannot use in conjunction with `interval` or `rrule`.                                                                                                                                               |
| `day_or`                                   | Boolean indicating how croniter handles day and day\_of\_week entries. Must use with `cron`. Defaults to `True`.                                                                                                         |
| `rrule`                                    | String representation of an RRule schedule. See the [`rrulestr` examples](https://dateutil.readthedocs.io/en/stable/rrule.html#rrulestr-examples) for syntax. Cannot used them in conjunction with `interval` or `cron`. |

### Concurrency limit fields

These are fields you can add to a deployment declaration's `concurrency_limit` section.

| Property             | Description                                                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`              | The maximum number of concurrent flow runs for the deployment.                                                                         |
| `collision_strategy` | Configure the behavior for runs once the concurrency limit is reached. Options are `ENQUEUE`, and `CANCEL_NEW`. Defaults to `ENQUEUE`. |

### Work pool fields

These are fields you can add to a deployment declaration's `work_pool` section.

| Property                                       | Description                                                                                                                                                                                                  |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                                         | The name of the work pool to schedule flow runs in for the deployment.                                                                                                                                       |
| <span class="no-wrap">`work_queue_name`</span> | The name of the work queue within the specified work pool to schedule flow runs in for the deployment. If not provided, the default queue for the specified work pool is used.                               |
| `job_variables`                                | Values used to override the default values in the specified work pool's [base job template](/v3/concepts/work-pools/#base-job-template). Maps directly to a created deployments `infra_overrides` attribute. |

### Deployment mechanics

Anytime you run `prefect deploy` in a directory that contains a `prefect.yaml` file, the following actions take place in order:

* The `prefect.yaml` file load. First, the `build` section loads and all variable and block references resolve. The steps then run in the order provided.
* Next, the `push` section loads and all variable and block references resolve; the steps within this section then run in the order provided.
* Next, the `pull` section is templated with any step outputs but *is not run*. Block references are *not* hydrated for security purposes: they are always resolved at runtime.
* Next, all variable and block references resolve with the deployment declaration. All flags provided through the `prefect deploy` CLI are then overlaid on the values loaded from the file.
* The final step occurs when the fully realized deployment specification is registered with the Prefect API.

<Tip>
  **Deployment instruction overrides**

  The `build`, `push`, and `pull` sections in deployment definitions take precedence over the corresponding sections above them in
  `prefect.yaml`.
</Tip>

Each time a step runs, the following actions take place in order:

* The step's inputs and block / variable references resolve.
* The step's function is imported; if it cannot be found, the special `requires` keyword installs the necessary packages.
* The step's function is called with the resolved inputs.
* The step's output is returned and used to resolve inputs for subsequent steps.

## Update a deployment

To update a deployment, make any desired changes to the `prefect.yaml` file, and run `prefect deploy`. Running just this command will prompt you to select a deployment interactively, or you may specify the deployment to update with `--name your-deployment`.

## Further reading

Now that you are familiar with creating deployments, you can explore infrastructure options for running your deployments:

* [Managed work pools](/v3/how-to-guides/deployment_infra/managed/)
* [Push work pools](/v3/how-to-guides/deployment_infra/serverless/)
* [Kubernetes work pools](/v3/how-to-guides/deployment_infra/kubernetes/)


# Trigger ad-hoc deployment runs
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/run-deployments

Learn how to trigger deployment runs using the Prefect CLI and Python SDK.

[Deployments](/v3/concepts/deployments) are server-side representations of flows that can be executed:

* on a [schedule](/v3/how-to-guides/deployments/create-schedules)
* when [triggered by events](/v3/how-to-guides/automations/creating-deployment-triggers)
* programmatically, on demand

This guide covers how to trigger deployments on demand.

## Prerequisites

In order to run a deployment, you need to have:

* [created a deployment](/v3/how-to-guides/deployments/create-deployments)
* started a process ([`serve`](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes) or a [worker](/v3/concepts/workers)) listening for scheduled runs of that deployment

## Run a deployment from the CLI

The simplest way to trigger a deployment run is using the Prefect CLI:

```bash
prefect deployment run my-flow/my-deployment
```

### CLI options

Add parameters and customize the run, including setting a custom flow run name using the new --flow-run-name option:

```bash
# Pass parameters
prefect deployment run my-flow/my-deployment \
  --param my_param=42 \
  --param another_param="hello"

# Schedule for later
prefect deployment run my-flow/my-deployment --start-in "2 hours"

# Watch the run until completion
prefect deployment run my-flow/my-deployment --watch

# Set custom run name
Use `--flow-run-name` to set a static or templated name for the flow run.

prefect deployment run my-flow/my-deployment --flow-run-name "custom-run-name"

# Set a custom flow run name using templating
prefect deployment run my-flow/my-deployment \
  --param customer_id=1234 \
  --param run_date="2025-07-14" \
  --flow-run-name "customer-{customer_id}-run-{run_date}"

> Note: You can use `{parameter}` syntax to template the flow run name.
> The values will be substituted from the `--param` values.

# Add tags to the run
prefect deployment run my-flow/my-deployment --tag production --tag critical
```

## Run a deployment from Python

Use the `run_deployment` function for programmatic control:

{/* pmd-metadata: notest */}

```python
from prefect.deployments import run_deployment

# Basic usage
flow_run = run_deployment(
    name="my-flow/my-deployment"
)

# With parameters
flow_run = run_deployment(
    name="my-flow/my-deployment",
    parameters={
        "my_param": 42,
        "another_param": "hello"
    }
)

# With job variables (environment variables, etc.)
flow_run = run_deployment(
    name="my-flow/my-deployment",
    parameters={"my_param": 42},
    job_variables={"env": {"MY_ENV_VAR": "production"}}
)

# Don't wait for completion
flow_run = run_deployment(
    name="my-flow/my-deployment",
    timeout=0  # returns immediately
)

# Wait with custom timeout (seconds)
flow_run = run_deployment(
    name="my-flow/my-deployment",
    timeout=300  # wait up to 5 minutes
)

# Schedule for later
from datetime import datetime, timedelta

flow_run = run_deployment(
    name="my-flow/my-deployment",
    scheduled_time=datetime.now() + timedelta(hours=2)
)

# With custom tags
flow_run = run_deployment(
    name="my-flow/my-deployment",
    tags=["production", "critical"]
)
```

<Note>
  By default, deployments triggered via `run_deployment` *from within another flow* will be treated as a subflow of the parent flow in the UI. To disable this, set `as_subflow=False`.
</Note>

### Async usage

In an async context, you can use the `run_deployment` function as a coroutine:

{/* pmd-metadata: notest */}

```python
import asyncio
from prefect.deployments import run_deployment

async def trigger_deployment():
    flow_run = await run_deployment(
        name="my-flow/my-deployment",
        parameters={"my_param": 42}
    )
    return flow_run

# Run it
flow_run = asyncio.run(trigger_deployment())
```

## Further reading

* Learn about [deployment schedules](/v3/how-to-guides/deployments/create-schedules)
* Explore [deployment triggers and automations](/v3/how-to-guides/automations/creating-deployment-triggers)
* Understand [work pools and workers](/v3/concepts/work-pools)


# How to retrieve code from storage
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/store-flow-code

Learn about code storage as it relates to execution of deployments

When a deployment runs, the execution environment needs access to the flow code.
Flow code is not stored directly in Prefect server or Prefect Cloud; instead, it must be made available to the execution environment. There are two main ways to achieve this:

1. **Include source code directly in your runtime:** Often, this means [building your code into a Docker image](/v3/how-to-guides/deployment_infra/docker/#automatically-build-a-custom-docker-image-with-a-local-dockerfile).
2. **Retrieve code from storage at runtime:** The [worker](/v3/concepts/workers/) pulls code from a specified location before starting the flow run.

This page focuses on the second approach: retrieving code from a storage location at runtime.

You have several options for where your code can be stored and pulled from:

* Local filesystem
* Git-based storage (GitHub, GitLab, Bitbucket)
* Blob storage (AWS S3, Azure Blob Storage, GCP GCS)

The ideal choice depends on your team's needs and tools.

In the examples below, we show how to create a deployment configured to run on [dynamic infrastructure](/v3/concepts/work-pools) for each of these storage options.

## Deployment creation options

As detailed in the [Deployment overview](/v3/deploy), you can create a deployment in one of two main ways:

* [Python code with the `flow.deploy` method](/v3/how-to-guides/deployments/deploy-via-python)

  * When using `.deploy`, specify a storage location for your flow with the `flow.from_source` method.

  * The `source` is either a URL to a git repository or a storage object. For example:
    * A local directory: `source=Path(__file__).parent` or `source="/path/to/file"`
    * A URL to a git repository: `source="https://github.com/org/my-repo.git"`
    * A storage object: `source=GitRepository(url="https://github.com/org/my-repo.git")`

  * The `entrypoint` is the path to the file the flow is located in and the function name, separated by a colon.

* [YAML specification defined in a `prefect.yaml` file](/v3/how-to-guides/deployments/prefect-yaml)

  * To create a `prefect.yaml` file interactively, run `prefect deploy` from the CLI and follow the prompts.

  * The `prefect.yaml` file may define a `pull` section that specifies the storage location for your flow. For example:
    * Set the working directory:
    ```yaml
    pull:
        - prefect.deployments.steps.set_working_directory:
            directory: /path/to/directory
    ```
    * Clone a git repository:
    ```yaml
    pull:
        - prefect.deployments.steps.git_clone:
            repository: https://github.com/org/my-repo.git
    ```
    * Pull from blob storage:
    ```yaml
    pull:
        - prefect.deployments.steps.pull_from_blob_storage:
            container: my-container
            folder: my-folder
    ```

Whether you use `from_source` or `prefect.yaml` to specify the storage location for your flow code, the resulting deployment will have a set of `pull` steps that your worker will use to retrieve the flow code at runtime.

## Store code locally

If using a Process work pool, you can use one of the remote code storage options shown above, or you can store your flow code in a local folder.

Here is an example of how to create a deployment with flow code stored locally:

<CodeGroup>
  ```python local_process_deploy_local_code.py
  from prefect import flow
  from pathlib import Path


  @flow(log_prints=True)
  def my_flow(name: str = "World"):
      print(f"Hello {name}!")


  if __name__ == "__main__":
      my_flow.from_source(
          source=str(Path(__file__).parent),  # code stored in local directory
          entrypoint="local_process_deploy_local_code.py:my_flow",
      ).deploy(
          name="local-process-deploy-local-code",
          work_pool_name="my-process-pool",
      )
  ```

  ```yaml prefect.yaml
  pull:
  - prefect.deployments.steps.set_working_directory:
      directory: /my_directory

  deployments:
  - name: local-process-deploy-local-code
    entrypoint: local_process_deploy_local_code.py:my_flow
    work_pool:
      name: my-process-pool
  ```
</CodeGroup>

## Git-based storage

Git-based version control platforms provide redundancy, version control, and collaboration capabilities. Prefect supports:

* [GitHub](https://github.com/)
* [GitLab](https://www.gitlab.com)
* [Bitbucket](https://bitbucket.org/)

For a public repository, you can use the repository URL directly.

If you are using a private repository and are authenticated in your environment at deployment creation and deployment execution, you can use the repository URL directly.

Alternatively, for a private repository, you can create a `Secret` block or `git`-platform-specific credentials [block](/v3/develop/blocks/) to store your credentials:

* [`GitHubCredentials`](https://docs.prefect.io/integrations/prefect-github/)
* [`BitBucketCredentials`](https://docs.prefect.io/integrations/prefect-bitbucket/)
* [`GitLabCredentials`](https://docs.prefect.io/integrations/prefect-gitlab/)

Then you can reference this block in the Python `deploy` method or the `prefect.yaml` file pull step.

If using the Python `deploy` method with a private repository that references a block, provide a [`GitRepository`](https://reference.prefect.io/prefect/flows/#prefect.runner.storage.GitRepository) object instead of a URL, as shown below.

<Tabs>
  <Tab title="GitHub">
    <CodeGroup>
      ```python gh_public_repo.py
      from prefect import flow

      if __name__ == "__main__":
          flow.from_source(
              source="https://github.com/org/my-public-repo.git",
              entrypoint="gh_public_repo.py:my_flow",
          ).deploy(
              name="my-github-deployment",
              work_pool_name="my_pool",
          )
      ```

      ```python gh_private_repo_credentials_block.py
      from prefect import flow
      from prefect.runner.storage import GitRepository
      from prefect_github import GitHubCredentials


      if __name__ == "__main__":

          github_repo = GitRepository(
              url="https://github.com/org/my-private-repo.git",
              credentials=GitHubCredentials.load("my-github-credentials-block"),
          )

          flow.from_source(
              source=github_repo,
              entrypoint="gh_private_repo_credentials_block.py:my_flow",
          ).deploy(
              name="private-github-deploy",
              work_pool_name="my_pool",
          )
      ```

      ```python gh_private_repo_secret_block.py
      from prefect import flow
      from prefect.runner.storage import GitRepository
      from prefect.blocks.system import Secret


      if __name__ == "__main__":

          github_repo = GitRepository(
              url="https://github.com/org/my-private-repo.git",
              credentials={
                  "access_token": Secret.load("my-secret-block-with-my-gh-credentials")
              },
          )

          flow.from_source(
              source=github_repo,
              entrypoint="gh_private_repo_secret_block.py:my_flow",
          ).deploy(
              name="private-github-deploy",
              work_pool_name="my_pool",
          )
      ```

      ```yaml prefect.yaml
      # relevant section of the file:
      pull:
          - prefect.deployments.steps.git_clone:
              repository: https://gitlab.com/org/my-repo.git
              # Uncomment the following line if using a credentials block
              # credentials: "{{ prefect.blocks.github-credentials.my-github-credentials-block }}"
              # Uncomment the following line if using a Secret block
              # access_token: "{{ prefect.blocks.secret.my-block-name }}"
      ```
    </CodeGroup>

    For accessing a private repository, we suggest creating a [Personal Access Tokens (PATs)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
    We recommend using HTTPS with [fine-grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to limit access by repository.

    <Warning>
      **Personal Access Token Permissions**

      When using a fine-grained token, ensure to add permissions to the token prior to saving. Per least privilege, we recommend granting the token the ability to read **Contents** and **Metadata** for your repository.
    </Warning>

    If using a `Secret` block, you can create it through code or the UI ahead of time and reference it at deployment creation as shown above.

    If using a `GitHubCredentials` block to store your credentials, you can create it ahead of time and reference it at deployment creation.

    1. Install `prefect-github` with `pip install -U prefect-github`
    2. Register all block types defined in `prefect-github` with `prefect block register -m prefect_github`
    3. Create a `GitHubCredentials` block through code or the Prefect UI and reference it at deployment creation as shown above.
  </Tab>

  <Tab title="Bitbucket">
    <CodeGroup>
      ```python bb_public_repo.py
      from prefect import flow


      if __name__ == "__main__":
          flow.from_source(
              source="https://bitbucket.com/org/my-public-repo.git",
              entrypoint="bb_public_repo.py:my_flow",
          ).deploy(
              name="my-bitbucket-deployment",
              work_pool_name="my_pool",
          )
      ```

      ```python bb_private_repo_credentials_block.py

      from prefect import flow
      from prefect.runner.storage import GitRepository
      from prefect_bitbucket import BitBucketCredentials

      if __name__ == "__main__":

          github_repo = GitRepository(
              url="https://bitbucket.com/org/my-private-repo.git",
              credentials=BitBucketCredentials.load("my-bitbucket-credentials-block")
          )

          flow.from_source(
              source=source,
              entrypoint="bb_private_repo_credentials_block.py:my_flow",
          ).deploy(
              name="private-bitbucket-deploy",
              work_pool_name="my_pool",
          )
      ```

      ```python bb_private_repo_secret_block.py

      from prefect import flow
      from prefect.runner.storage import GitRepository
      from prefect.blocks.system import Secret


      if __name__ == "__main__":
          github_repo=GitRepository(
              url="https://bitbucket.com/org/my-private-repo.git",
              credentials={
                  "access_token": Secret.load("my-secret-block-with-my-bb-credentials")
              },
          )
          
          flow.from_source(
              source=github_repo,
              entrypoint="bb_private_repo_secret_block.py:my_flow",
          ).deploy(
              name="private-bitbucket-deploy",
              work_pool_name="my_pool",
          )
      ```

      ```yaml prefect.yaml
      # relevant section of the file:
      pull:
          - prefect.deployments.steps.git_clone:
              repository: https://bitbucket.org/org/my-private-repo.git
              # Uncomment the following line if using a credentials block
              # credentials: "{{ prefect.blocks.bitbucket-credentials.my-bitbucket-credentials-block }}"
              # Uncomment the following line if using a Secret block
              # access_token: "{{ prefect.blocks.secret.my-block-name }}"
      ```
    </CodeGroup>

    For accessing a private repository, we recommend using HTTPS with Repository, Project, or Workspace [Access Tokens](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/).

    [Create a token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository-access-token/) with **read** access to the repository.

    Bitbucket requires you prepend the token string with `x-token-auth:` The full string looks like this: `x-token-auth:abc_123_this_is_a_token`.

    If using a `Secret` block, you can create it through code or the UI ahead of time and reference it at deployment creation as shown above.

    If using a `BitBucketCredentials` block to store your credentials, you can create it ahead of time and reference it at deployment creation.

    1. Install `prefect-bitbucket` with `pip install -U prefect-bitbucket`
    2. Register all block types defined in `prefect-bitbucket` with `prefect block register -m prefect_bitbucket`
    3. Create a `BitBucketCredentials` block in code or the Prefect UI and reference at deployment creation as shown above.
  </Tab>

  <Tab title="GitLab">
    <CodeGroup>
      ```python gl_public_repo.py
      from prefect import flow


      if __name__ == "__main__":
          gitlab_repo = "https://gitlab.com/org/my-public-repo.git"

          flow.from_source(
              source=gitlab_repo,
              entrypoint="gl_public_repo.py:my_flow"
          ).deploy(
              name="my-gitlab-deployment",
              work_pool_name="my_pool",
          )
      ```

      ```python gl_private_repo_credentials_block.py

      from prefect import flow
      from prefect.runner.storage import GitRepository
      from prefect_gitlab import GitLabCredentials


      if __name__ == "__main__":

          gitlab_repo = GitRepository(
              url="https://gitlab.com/org/my-private-repo.git",
              credentials=GitLabCredentials.load("my-gitlab-credentials-block")
          )
          
          flow.from_source(
              source=gitlab_repo,
              entrypoint="gl_private_repo_credentials_block.py:my_flow",
          ).deploy(
              name="private-gitlab-deploy",
              work_pool_name="my_pool",
          )
      ```

      ```python gl_private_repo_secret_block.py    

      from prefect import flow
      from prefect.runner.storage import GitRepository
      from prefect.blocks.system import Secret


      if __name__ == "__main__":
          gitlab_repo = GitRepository(
              url="https://gitlab.com/org/my-private-repo.git",
              credentials={
                  "access_token": Secret.load("my-secret-block-with-my-gl-credentials")
              },
          )

          flow.from_source(   
              source=gitlab_repo,
              entrypoint="gl_private_repo_secret_block.py:my_flow",
          ).deploy(
              name="private-gitlab-deploy",
              work_pool_name="my_pool",
          )
      ```

      ```yaml prefect.yaml
      # relevant section of the file:
      pull:
          - prefect.deployments.steps.git_clone:
              repository: https://gitlab.com/org/my-private-repo.git
              # Uncomment the following line if using a credentials block
              # credentials: "{{ prefect.blocks.gitlab-credentials.my-gitlab-credentials-block }}"
              # Uncomment the following line if using a Secret block
              # access_token: "{{ prefect.blocks.secret.my-block-name }}"
      ```
    </CodeGroup>

    For accessing a private repository, we recommend using HTTPS with [Project Access Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html).

    [Create a token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with the **read\_repository** scope.

    If using a `Secret` block, you can create it through code or the UI ahead of time and reference it at deployment creation as shown above.

    If using a `GitLabCredentials` block to store your credentials, you can create it ahead of time and reference it at deployment creation.

    1. Install `prefect-gitlab` with `pip install -U prefect-gitlab`
    2. Register all block types defined in `prefect-gitlab` with `prefect block register -m prefect_gitlab`
    3. Create a `GitLabCredentials` block in code or the Prefect UI and reference it at deployment creation as shown above.
  </Tab>
</Tabs>

Note that you can specify a `branch` if creating a `GitRepository` object.
The default is `"main"`.

<Warning>
  **Push your code**

  When you make a change to your code, Prefect does not push your code to your `git`-based version control platform.
  This is intentional to avoid confusion about the `git` history and push process.
</Warning>

### Prefect Cloud GitHub Integration

<span class="badge cloud" /> If you're using Prefect Cloud you can use the Prefect Cloud GitHub App
to authenticate to GitHub at runtime and access private repositories without creating a block and storing long
lived credentials.

1. [Install the Prefect Cloud GitHub App](https://github.com/apps/prefect-cloud/installations/new?) and select the
   repositories you want to be able to access.

2. Add the following pull steps to your `prefect.yaml` file. Make sure to replace `owner/repository` with the name of your repository:

```yaml
pull:
    - prefect.deployments.steps.run_shell_script:
        id: get-github-token
        script: uv tool run prefect-cloud github token owner/repository
    - prefect.deployments.steps.git_clone:
        id: git-clone
        repository: https://x-access-token:{{ get-github-token.stdout }}@github.com/owner/repository.git
```

## Docker-based storage

Another popular flow code storage option is to include it in a Docker image.
All work pool options except **Process** and **Prefect Managed** allow you to bake your code into a Docker image.

To create a deployment with Docker-based flow code storage use the Python `deploy` method or create a `prefect.yaml` file.

<Note>
  If you use the Python `deploy` method to store the flow code in a Docker image, you don't need to use the `from_source` method.
</Note>

The `prefect.yaml` file below was generated by running `prefect deploy` from the CLI (a few lines of metadata were excluded from the top of the file output for brevity).

Note that the `build` section is necessary if baking your flow code into a Docker image.

<CodeGroup>
  ```python docker_deploy.py
  from prefect import flow


  @flow
  def my_flow():
      print("Hello from inside a Docker container!")

  if __name__ == "__main__":
      my_flow.deploy(
          name="my-docker-deploy",
          work_pool_name="my_pool",
          image="my-docker-image:latest",
          push=False
      )
  ```

  ```yaml prefect.yaml
  # build section allows you to manage and build docker images
  build:
  - prefect_docker.deployments.steps.build_docker_image:
      requires: prefect-docker>=0.6.1
      id: build-image
      dockerfile: auto
      image_name: my-registry/my-image
      tag: latest

  # push section allows you to manage if and how this project is uploaded to remote locations
  push: null

  # pull section allows you to provide instructions for cloning this project in remote locations
  pull:
  - prefect.deployments.steps.set_working_directory:
      directory: /opt/prefect/my_directory


  # the deployments section allows you to provide configuration for deploying flows
  deployments:
  - name: my-docker-deployment
    entrypoint: my_file.py:my_flow
    work_pool:
      name: my_pool
      job_variables:
        image: '{{ build-image.image }}'

  ```
</CodeGroup>

By default, `.deploy` will build a Docker image that includes your flow code and any `pip` packages specified in a `requirements.txt` file.

In the examples above, we elected not to push the resulting image to a remote registry.

To push the image to a remote registry, pass `push=True` in the Python `deploy` method or add a `push_docker_image` step to the `push` section of the `prefect.yaml` file.

### Custom Docker image

If an `image` is not specified by one of the methods above, deployment flow runs associated with a Docker work pool will use the base Prefect image (e.g. `prefecthq/prefect:3-latest`) when executing.
Alternatively, you can create a custom Docker image outside of Prefect by running `docker build` && `docker push` elsewhere (e.g. in your CI/CD pipeline) and then reference the resulting `image` in the `job_variables` section of your deployment definition, or set the `image` as a default directly on the work pool.

For more information, see [this discussion of custom Docker images](/v3/how-to-guides/deployment_infra/docker/#automatically-build-a-custom-docker-image-with-a-local-dockerfile).

## Blob storage

Another option for flow code storage is any [fsspec](https://filesystem-spec.readthedocs.io/en/latest/)-supported storage location, such as AWS S3, Azure Blob Storage, or GCP GCS.

If the storage location is publicly available, or if you are authenticated in the environment where you are creating and running your deployment, you can reference the storage location directly.
You don't need to pass credentials explicitly.

To pass credentials explicitly to authenticate to your storage location, you can use either of the following block types:

* Prefect integration library storage blocks, such as the `prefect-aws` library's `S3Bucket` block, which can use a `AWSCredentials` block when it is created.
* `Secret` blocks

<Note>
  If you use a storage block such as the `S3Bucket` block, you need to have the `prefect-aws` library available in the environment where your flow code runs.

  You can do any of the following to make the library available:

  1. Install the library into the execution environment directly
  2. Specify the library in the work pool's Base Job Template in the **Environment Variables** section like this:`{"EXTRA_PIP_PACKAGES":"prefect-aws"}`
  3. Specify the library in the environment variables of the `deploy` method as shown in the examples below
  4. Specify the library in a `requirements.txt` file and reference the file in the `pull` step of the `prefect.yaml` file like this:

  ```yaml
      - prefect.deployments.steps.pip_install_requirements:
          directory: "{{ pull_code.directory }}" 
          requirements_file: requirements.txt
  ```
</Note>

The examples below show how to create a deployment with flow code in a cloud provider storage location.
For each example, we show how to access code that is publicly available.
The `prefect.yaml` example includes an additional line to reference a credentials block if authenticating to a private storage location through that option.

We also include Python code that shows how to use an existing storage block and an example of that creates, but doesn't save, a storage block that references an existing nested credentials block.

<Tabs>
  <Tab title="AWS S3 bucket">
    <CodeGroup>
      ```python s3_no_block.py
      from prefect import flow


      if __name__ == "__main__":
          flow.from_source(
              source="s3://my-bucket/my-folder",
              entrypoint="my_file.py:my_flow",
          ).deploy(
              name="my-aws-s3-deployment",
              work_pool_name="my-work-pool"
          )
      ```

      ```python s3_block.py

      from prefect import flow
      from prefect_aws.s3 import S3Bucket

      if __name__ == "__main__":
          s3_bucket_block = S3Bucket.load("my-code-storage-block")

          # or:
          # s3_bucket_block = S3Bucket(
          #     bucket="my-bucket",
          #     folder="my-folder",
          #     credentials=AWSCredentials.load("my-credentials-block")
          # )

          flow.from_source(
              source=s3_bucket_block, 
              entrypoint="my_file.py:my_flow"
          ).deploy(
              name="my-aws-s3-deployment", 
              work_pool_name="my-work-pool"
              job_variables={"env": {"EXTRA_PIP_PACKAGES": "prefect-aws"} }, 
          )
      ```

      ```yaml prefect.yaml
      build: null

      push:
      - prefect_aws.deployments.steps.push_to_s3:
          id: push_code
          requires: prefect-aws>=0.5
          bucket: my-bucket
          folder: my-folder
          credentials: "{{ prefect.blocks.aws-credentials.my-credentials-block }}" # if explicit authentication is required

      pull:
      - prefect_aws.deployments.steps.pull_from_s3:
          id: pull_code
          requires: prefect-aws>=0.5
          bucket: '{{ push_code.bucket }}'
          folder: '{{ push_code.folder }}'
          credentials: "{{ prefect.blocks.aws-credentials.my-credentials-block }}" # if explicit authentication is required 

      deployments:
      - name: my-aws-deployment
        version: null
        tags: []
        concurrency_limit: null
        description: null
        entrypoint: my_file.py:my_flow
        parameters: {}
        work_pool:
          name: my-work-pool
          work_queue_name: null
          job_variables: {}
        enforce_parameter_schema: true
        schedules: []
      ```
    </CodeGroup>

    To create an `AwsCredentials` block:

    1. Install the [prefect-aws](/integrations/prefect-aws) library with `pip install -U prefect-aws`
    2. Register the blocks in prefect-aws with `prefect block register -m prefect_aws`
    3. Create a user with a role with read and write permissions to access the bucket. If using the UI, create an access key pair with *IAM -> Users -> Security credentials -> Access keys -> Create access key*. Choose *Use case -> Other* and then copy the *Access key* and *Secret access key* values.
    4. Create an [`AWSCredentials` block](/integrations/prefect-aws/index#save-credentials-to-an-aws-credentials-block) in code or the Prefect UI. In addition to the block name, most users will fill in the *AWS Access Key ID* and *AWS Access Key Secret* fields.
    5. Reference the block as shown above.
  </Tab>

  <Tab title="Azure Blob Storage container">
    <CodeGroup>
      ```python azure_no_block.py
      from prefect import flow


      if __name__ == "__main__":
          flow.from_source(
              source="az://mycontainer/myfolder",
              entrypoint="my_file.py:my_flow",
          ).deploy(
              name="my-azure-deployment",
              work_pool_name="my-work-pool",
              job_variables={"env": {"EXTRA_PIP_PACKAGES": "prefect-azure"} }, 
          )
      ```

      ```python azure_block.py
      from prefect import flow
      from prefect_azure import AzureBlobCredentials, AzureBlobStorage


      if __name__ == "__main__":

          azure_blob_storage_block = AzureBlobStorage.load("my-code-storage-block")

          # or 
          # azure_blob_storage_block = AzureBlobStorage(   
          #     container="my-prefect-azure-container",
          #     folder="my-folder",
          #     credentials=AzureBlobCredentials.load("my-credentials-block")
          # )

          flow.from_source(source=azure_blob_storage_block, entrypoint="my_file.py:my_flow").deploy(
              name="my-azure-deployment", work_pool_name="my-work-pool"
          )
      ```

      ```yaml prefect.yaml
      build: null

      push:
      - prefect_azure.deployments.steps.push_to_azure_blob_storage:
          id: push_code
          requires: prefect-azure>=0.4
          container: my-prefect-azure-container
          folder: my-folder
          credentials: "{{ prefect.blocks.azure-blob-storage-credentials.my-credentials-block }}" 
          # if explicit authentication is required

      pull:
      - prefect_azure.deployments.steps.pull_from_azure_blob_storage:
          id: pull_code
          requires: prefect-azure>=0.4
          container: '{{ push_code.container }}'
          folder: '{{ push_code.folder }}'
          credentials: "{{ prefect.blocks.azure-blob-storage-credentials.my-credentials-block }}" # if explicit authentication is required

      deployments:
      - name: my-azure-deployment
        version: null
        tags: []
        concurrency_limit: null
        description: null
        entrypoint: my_file.py:my_flow
        parameters: {}
        work_pool:
          name: my-work-pool
          work_queue_name: null
          job_variables: {}
        enforce_parameter_schema: true
        schedules: []
      ```
    </CodeGroup>

    To create an `AzureBlobCredentials` block:

    1. Install the [prefect-azure](/integrations/prefect-azure/) library with `pip install -U prefect-azure`
    2. Register the blocks in prefect-azure with `prefect block register -m prefect_azure`
    3. Create an access key for a role with sufficient (read and write) permissions to access the blob.
       You can create a connection string containing all required information in the UI under *Storage Account -> Access keys*.
    4. Create an Azure Blob Storage Credentials block in code or the Prefect UI. Enter a name for the block and paste the
       connection string into the *Connection String* field.
    5. Reference the block as shown above.
  </Tab>

  <Tab title="GCP GCS bucket">
    <CodeGroup>
      ```python gcs_no_block.py
      from prefect import flow


      if __name__ == "__main__":
          flow.from_source(
              source="gs://my-bucket/my-folder",  
              entrypoint="my_file.py:my_flow",
          ).deploy(
              name="my-gcs-deployment",
              work_pool_name="my-work-pool"
          )
      ```

      ```python gcs_block.py
      from prefect import flow
      from prefect_gcp import GcpCredentials, GCSBucket


      if __name__ == "__main__":

          gcs_bucket_block = GCSBucket.load("my-code-storage-block")

          # or 
          # gcs_bucket_block = GCSBucket(
          #     bucket="my-bucket",
          #     folder="my-folder",
          #     credentials=GcpCredentials.load("my-credentials-block")
          # )

          flow.from_source(
              source=gcs_bucket_block,
              entrypoint="my_file.py:my_flow",
          ).deploy(
              name="my-gcs-deployment",
              work_pool_name="my_pool",
              job_variables={"env": {"EXTRA_PIP_PACKAGES": "prefect-gcp"} }, 
          )
      ```

      ```yaml prefect.yaml
      build: null

      push:
      - prefect_gcp.deployment.steps.push_to_gcs:
          id: push_code
          requires: prefect-gcp>=0.6
          bucket: my-bucket
          folder: my-folder
          credentials: "{{ prefect.blocks.gcp-credentials.my-credentials-block }}" # if explicit authentication is required 

      pull:
      - prefect_gcp.deployment.steps.pull_from_gcs:
          id: pull_code
          requires: prefect-gcp>=0.6
          bucket: '{{ push_code.bucket }}'
          folder: '{{ pull_code.folder }}'
          credentials: "{{ prefect.blocks.gcp-credentials.my-credentials-block }}" # if explicit authentication is required 

      deployments:
      - name: my-gcs-deployment
          version: null
          tags: []
          concurrency_limit: null
          description: null
          entrypoint: my_file.py:my_flow
          parameters: {}
          work_pool:
            name: my-work-pool
            work_queue_name: null
            job_variables: {}
          enforce_parameter_schema: true
          schedules: []
      ```
    </CodeGroup>

    To create a `GcpCredentials` block:

    1. Install the [prefect-gcp](/integrations/prefect-gcp/) library with `pip install -U prefect-gcp`
    2. Register the blocks in prefect-gcp with `prefect block register -m prefect_gcp`
    3. Create a service account in GCP for a role with read and write permissions to access the bucket contents.
       If using the GCP console, go to *IAM & Admin -> Service accounts -> Create service account*.
       After choosing a role with the required permissions,
       see your service account and click on the three dot menu in the *Actions* column.
       Select *Manage Keys -> ADD KEY -> Create new key -> JSON*. Download the JSON file.
    4. Create a GCP Credentials block in code or the Prefect UI. Enter a name for the block and paste the entire contents of the JSON key file into the *Service Account Info* field.
    5. Reference the block as shown above.
  </Tab>
</Tabs>

Another authentication option is to give the worker access to the storage location at runtime through SSH keys.


# How to version deployments
Source: https://docs-3.prefect.io/v3/how-to-guides/deployments/versioning

Track changes to your deployments and roll back to previous versions

In Prefect Cloud, deployments have a version history.
The **live** deployment version is the runnable version of a deployment.
A previous deployment version can be made live by **rolling back** to it.
When a previous deployment version is live, a newer deployment version can be made live by **promoting** it.

<Warning>
  When a new version of a deployment is created, it is automatically set as the live version.
</Warning>

## What's included in a deployment version

Deployment versions are a history of changes to a deployment's configuration.

While the majority of deployment properties are included in a deployment's version, some properties cannot be versioned.
Persisting these properties across all versions helps prevent unexpected execution behavior when rolling back or promoting versions.

<AccordionGroup>
  <Accordion title="Versioned deployment properties" icon="check" iconType="solid">
    These properties are pinned to each deployment version.

    | Deployment Property        | Versioned                              |
    | -------------------------- | -------------------------------------- |
    | `description`              | <Icon icon="check" iconType="solid" /> |
    | `tags`                     | <Icon icon="check" iconType="solid" /> |
    | `labels`                   | <Icon icon="check" iconType="solid" /> |
    | `entrypoint`               | <Icon icon="check" iconType="solid" /> |
    | `pull_steps`               | <Icon icon="check" iconType="solid" /> |
    | `parameters`               | <Icon icon="check" iconType="solid" /> |
    | `parameter_openapi_schema` | <Icon icon="check" iconType="solid" /> |
    | `enforce_parameter_schema` | <Icon icon="check" iconType="solid" /> |
    | `work_queue_id`            | <Icon icon="check" iconType="solid" /> |
    | `work_pool_name`           | <Icon icon="check" iconType="solid" /> |
    | `job_variables`            | <Icon icon="check" iconType="solid" /> |
    | `created_by`               | <Icon icon="check" iconType="solid" /> |
    | `updated_by`               | <Icon icon="check" iconType="solid" /> |
    | `version_info`             | <Icon icon="check" iconType="solid" /> |
  </Accordion>

  <Accordion title="Unversioned deployment properties" icon="xmark" description="">
    These properties persist across version rollbacks and promotions.

    | Deployment Property   | Versioned                                                          |
    | --------------------- | ------------------------------------------------------------------ |
    | `name`                | <Icon icon="xmark" iconType="solid" color="#FF0000" /> (immutable) |
    | `schedules`           | <Icon icon="xmark" iconType="solid" color="#FF0000" />             |
    | `is_schedule_active`  | <Icon icon="xmark" iconType="solid" color="#FF0000" />             |
    | `paused`              | <Icon icon="xmark" iconType="solid" color="#FF0000" />             |
    | `disabled`            | <Icon icon="xmark" iconType="solid" color="#FF0000" />             |
    | `concurrency_limit`   | <Icon icon="xmark" iconType="solid" color="#FF0000" />             |
    | `concurrency_options` | <Icon icon="xmark" iconType="solid" color="#FF0000" />             |
  </Accordion>
</AccordionGroup>

## How to create and manage versions

A new deployment version is created every time a deployment is updated, whether from the CLI, from Python, or from the UI.

If you're deploying from a supported source code management platform or from inside a Git repository, Prefect automatically collects the **repository name**, **repository URL**, the currently checked out **branch**, the **commit SHA**, and the **first line of your commit message** from your environment.
This information is used to help create a record of which code versions produced which deployment versions, and does not affect deployment execution.

### Supported source code management platforms

Prefect searches for environment variables in each supported platform's CI environment in order to collect information about the current state of the repository from which deployment versions are created.
It may be useful to access these environment variables in other stages of your deployment process for constructing version identifiers.

<Note>
  Prefect's automatic version information collection currently supports GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure Pipelines.
  If deploying from a Git repository not on one of these platforms, Prefect will use `git` CLI commands as a best effort to discover these values.
</Note>

<Tabs>
  <Tab title="GitHub Actions">
    | Environment Variable | Value                              |
    | -------------------- | ---------------------------------- |
    | `GITHUB_SHA`         | Commit SHA                         |
    | `GITHUB_REF_NAME`    | Branch name                        |
    | `GITHUB_REPOSITORY`  | Repository name                    |
    | `GITHUB_SERVER_URL`  | Github account or organization URL |
  </Tab>

  <Tab title="GitLab CI">
    | Environment Variable | Value           |
    | -------------------- | --------------- |
    | `CI_COMMIT_SHA`      | Commit SHA      |
    | `CI_COMMIT_REF_NAME` | Branch name     |
    | `CI_PROJECT_NAME`    | Repository name |
    | `CI_PROJECT_URL`     | Repository URL  |
  </Tab>

  <Tab title="Bitbucket Pipelines">
    | Environment Variable        | Value                                 |
    | --------------------------- | ------------------------------------- |
    | `BITBUCKET_COMMIT`          | Commit SHA                            |
    | `BITBUCKET_BRANCH`          | Branch name                           |
    | `BITBUCKET_REPO_SLUG`       | Repository name                       |
    | `BITBUCKET_GIT_HTTP_ORIGIN` | Bitbucket account or organization URL |
  </Tab>

  <Tab title="Azure Pipelines">
    | Environment Variable     | Value           |
    | ------------------------ | --------------- |
    | `BUILD_SOURCEVERSION`    | Commit SHA      |
    | `BUILD_SOURCEBRANCHNAME` | Branch name     |
    | `BUILD_REPOSITORY_NAME`  | Repository name |
    | `BUILD_REPOSITORY_URI`   | Repository URL  |
  </Tab>
</Tabs>

### Using the `version` deployment property

Supplying a `version` to your deployment is not required, but using human-readable version names helps give meaning to each change you make.
It's also valuable for quickly finding or communicating the version you want to roll back to or promote.

For additional details on how Prefect handles the value of `version`, see [deployment metadata for bookkeeping](/v3/deploy#metadata-for-bookkeeping).

### Executing specific code versions

It's possible to synchronize code changes to deployment versions so each deployment version executes the exact commit that was checked out when it was created.
Since `pull_steps` and `job_variables` define what repository or image to pull when a flow runs, updating their contents with each code change keeps deployment versions in step with your codebase.
Which of these configurations to use depends on whether you are pulling code from Git or storing code in Docker images.

The examples in this section use GitHub as their source control management and CI platform, so be sure to replace URLs, environment variables, and CI workflows with the ones relevant to your platform.
You can check out complete example repositories on GitHub for executing specific code versions when [pulling from Git](https://github.com/kevingrismore/version-testing) and [pulling Docker images](https://github.com/kevingrismore/version-testing-docker/tree/main).

#### Pulling from Git

The `git_clone` deployment pull step and `GitRepository` deployment storage class offer a `commit_sha` field.
When deploying from a Git repository, provide the commit SHA from your environment to your deployment.
Both approaches below will result in a deployment pull step that clones your repository and checks out a specific commit.

<CodeGroup>
  ```yaml With prefect.yaml
  pull:
  - prefect.deployments.steps.git_clone:
      repository: https://github.com/my-org/my-repo.git
      commit_sha: "{{ $GITHUB_SHA }}"

  deployments:
  - name: my-deployment
    version: 0.0.1
    entrypoint: example.py:my_flow
    work_pool:
      name: my-work-pool
  ```

  ```python With .deploy()
  import os

  from prefect import flow
  from prefect.runner.storage import GitRepository

  @flow(log_prints=True)
  def my_flow():
      print("Hello world!")

  if __name__ == "__main__":
      my_flow.from_source(
          source=GitRepository(
              repo_url="https://github.com/my-org/my-repo.git",
              commit_sha=os.getenv("GITHUB_SHA"),
          )
      ).deploy(
          name="my-deployment",
          version="0.0.1",
          work_pool_name="my-work-pool",
      )
  ```
</CodeGroup>

#### Pulling Docker images

When baking code into Docker images, use the image digest to pin exact code versions to deployment versions.
An image digest uniquely and immutably identifies a container image.

First, build your image in your CI job and pass the image digest as an environment variable to the Prefect deploy step.

```yaml Github Actions
      ...

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        id: build-docker-image
        uses: docker/build-push-action@v6
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: my-registry/my-example-image:my-tag
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Deploy a Prefect flow
        env:
          IMAGE_DIGEST: ${{ steps.build-docker-image.outputs.digest }}
          PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}
          PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}
        ... # your deployment action here
```

Then, refer to that digest in the image name you provide to this deployment version's job variables.

<CodeGroup>
  ```yaml With prefect.yaml
  deployments:
  - name: my-deployment
    version: 0.0.1
    entrypoint: example.py:my_flow
    work_pool:
      name: my-work-pool
      job_variables:
        image: "my-registry/my-image@{{ $IMAGE_DIGEST }}"
  ```

  ```python With .deploy()
  import os

  from prefect import flow

  @flow(log_prints=True)
  def my_flow():
      print("Hello world!")

  if __name__ == "__main__":
      my_flow.deploy(
          name="my-deployment",
          version="0.0.1",
          work_pool_name="my-work-pool",
          image=f"my-registry/my-image@{os.getenv('IMAGE_DIGEST')}",
          build=False,
      )
  ```
</CodeGroup>


# How-to Guides
Source: https://docs-3.prefect.io/v3/how-to-guides/index



## Sections

<CardGroup cols={3}>
  <Card title="Workflows" icon="play" href="/v3/how-to-guides/workflows/">
    Learn how to write and customize your Prefect workflows.
  </Card>

  <Card title="Deployments" icon="rocket" href="/v3/how-to-guides/deployments/">
    Learn how to deploy and manage your workflows as Prefect deployments.
  </Card>

  <Card title="Configuration" icon="gears" href="/v3/how-to-guides/configuration/">
    Learn how to configure your Prefect environment.
  </Card>

  <Card title="Automations" icon="robot" href="/v3/how-to-guides/automations/">
    Learn how to work with events, triggers, and automations.
  </Card>

  <Card title="Workflow Infrastructure" icon="city" href="/v3/how-to-guides/deployment_infra/">
    Learn how to deploy your workflows to specific infrastructure.
  </Card>

  <Card title="Prefect Cloud" icon="cloud" href="/v3/how-to-guides/cloud/">
    Learn how to set up your Prefect Cloud account.
  </Card>

  <Card title="Prefect Self-hosted" icon="server" href="/v3/how-to-guides/self-hosted/">
    Learn how to host your own Prefect server.
  </Card>

  <Card title="Migrate" icon="circle-up" href="/v3/how-to-guides/migrate/">
    Learn how to migrate from other platforms and upgrade to the latest versions of Prefect.
  </Card>
</CardGroup>


# How to Migrate from Airflow
Source: https://docs-3.prefect.io/v3/how-to-guides/migrate/airflow

Migration from Apache Airflow to Prefect: A Comprehensive How-To Guide

Migrating from Apache Airflow to Prefect simplifies orchestration, reduces overhead, and enables a more Pythonic workflow.
Prefect's flexible **library-based approach** lets you write, test, and run workflows with regular code—without the complexity of schedulers, executors, or metadata databases.

This guide will walk you through a **step-by-step migration**, helping you transition from Airflow DAGs to Prefect flows while mapping key concepts, adapting infrastructure, and optimizing deployments. By the end, you'll have a streamlined, scalable orchestration system that lets your team focus on engineering rather than maintaining workflow infrastructure.

**Airflow to Prefect Mapping**

This table provides a quick reference for migrating key Airflow concepts to their Prefect equivalents. Click on each concept to jump to a detailed explanation.

| **Airflow Concept**                                        | **Prefect Equivalent**                                       | **Key Differences**                                                                           |
| ---------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| [**DAGs**](#choose-a-dag-to-convert)                       | [**Flows**](#define-a-prefect-flow)                          | Prefect flows are standard Python functions (`@flow`). No DAG classes or `>>` dependencies.   |
| [**Operators**](#create-equivalent-prefect-tasks)          | [**Tasks**](#create-equivalent-prefect-tasks)                | Prefect tasks (`@task`) replace Airflow Operators, removing the need for specialized classes. |
| [**Executors**](#airflow-executors)                        | [**Work Pools & Workers**](#airflow-executors)               | Prefect decouples task execution using lightweight **workers** polling **work pools**.        |
| [**Scheduling**](#prefect-deployment)                      | [**Deployments**](#prefect-deployment)                       | Scheduling is separate from flow code and configured externally.                              |
| [**XComs**](#define-a-prefect-flow)                        | [**Return Values**](#define-a-prefect-flow)                  | Prefect tasks return data directly; no need for XComs or metadata storage.                    |
| [**Hooks & Connections**](#airflow-hooks-and-integrations) | [**Blocks & Integrations**](#airflow-hooks-and-integrations) | Prefect replaces Hooks with **Blocks** for secure resource management.                        |
| [**Sensors**](#airflow-sensors)                            | [**Triggers & Event-Driven Flows**](#airflow-sensors)        | Prefect uses external event triggers or lightweight polling flows.                            |
| [**Airflow UI**](#observability)                           | [**Prefect UI**](#observability)                             | Prefect provides real-time monitoring, task logs, and automation features.                    |

There are also so key differences when it comes to task execution, resource control, data passing, and parallelism. We'll cover these in more detail below.

| **Feature**           | **Airflow**                               | **Prefect**                                |
| --------------------- | ----------------------------------------- | ------------------------------------------ |
| **Task Execution**    | Tasks run as independent processes/pods   | Tasks execute in single flow runtime       |
| **Resource Control**  | Task-level via executor settings          | Flow-level via work pools & task runners   |
| **Data Passing**      | Requires XComs or external storage        | Direct in-memory data passing              |
| **Parallelism**       | Managed by executor configuration         | Managed by work pools and task runners     |
| **Task Dependencies** | Uses `>>` operators and `set_upstream()`  | Implicit via Python function calls         |
| **DAG Parsing**       | Pre-parsed with global variable execution | Standard Python function execution         |
| **State & Retries**   | Individual task retries, manual DAG fixes | Built-in flow & task retry handling        |
| **Scheduling**        | Tightly coupled with DAG code             | Decoupled via deployments                  |
| **Infrastructure**    | Requires scheduler, metadata DB, workers  | Lightweight API server with optional cloud |

## Preparing for migration

Before jumping into code conversion, set the stage for a smooth migration. Preparation includes auditing your existing Airflow DAGs, setting up a Prefect environment for testing, and mapping Airflow concepts to their Prefect equivalents.

**Audit your Airflow DAGs and dependencies:** Catalog all DAGs, schedules, task counts, and dependencies (databases, APIs, cloud services). Identify **high-priority pipelines** (business-critical, failure-prone, frequently updated) and **simpler DAGs** for pilot migration. Start with a small, non-critical DAG to gain confidence before tackling complex workflows.

**Set up Prefect for testing:** Before fully migrating, set up a parallel Prefect environment to test your flows. Prefect provides a managed execution environment out of the box, so you can get started without configuring infrastructure.

1. [**Install Prefect**](/v3/get-started/install) (`pip install prefect`).
2. **Start a Prefect server locally** (`prefect server start`) or sign up for [**Prefect Cloud**](https://app.prefect.cloud/) to run flows immediately.
3. **Run initial flows without infrastructure setup**: Run flows locally or using Prefect Cloud Managed Exxecution - allowing you to test without configuring work pools or Kubernetes.

<Tip>Prefect Cloud provides a managed execution environment out of the box, so you can get started without configuring infrastructure.</Tip>

Once you've validated basic functionality, you can explore configuring an [**execution environment**](/v3/deploy/infrastructure-concepts/work-pools) (e.g., Docker, Kubernetes) for production, which we cover later in this tutorial.

For each Airflow DAG, you can outline its Prefect flow structure (tasks and control flow), where its schedule will live, and what execution infrastructure it needs. With preparation done, it's time to start converting code.

## Converting DAGs to Prefect Flows

In this phase, you will **rewrite your Airflow DAGs as Prefect flows and tasks**. The goal is to replicate each workflow's logic in Prefect, while simplifying wherever possible.

<Note>Prefect's API is quite ergonomic - many Airflow users find they can express the same logic with *less code* and *more flexibility*</Note>

Let's break down the conversion process step-by-step, and walk through a concrete example.

### Choose a DAG to convert

Start with one of your simpler DAGs (perhaps one of those identified in the audit as an easy win). For illustration, suppose we have an Airflow DAG that runs a simple ETL: it **extracts data**, **transforms** it, and then **loads** the results. In Airflow, this might be defined as:

{/* pmd-metadata: notest */}

```python
# Airflow DAG example (simplified ETL)
from airflow import DAG
from airflow.operators.python import PythonOperator
from datetime import datetime

# Airflow task functions (to be used by PythonOperator)
def extract_fn():
    # ... (extract data, e.g., query an API or database)
    return data

def transform_fn(data):
    # ... (transform the data)
    return processed_data

def load_fn(processed_data):
    # ... (load data to target, e.g., save to DB or file)

with DAG("etl_pipeline", start_date=datetime(2023,1,1), schedule_interval="@daily", catchup=False) as dag:
    extract = PythonOperator(task_id='extract_data', python_callable=extract_fn)
    transform = PythonOperator(task_id='transform_data', python_callable=transform_fn)
    load = PythonOperator(task_id='load_data', python_callable=load_fn)

    # Set task dependencies
    extract >> transform >> load
```

In this Airflow DAG, we define three tasks using `PythonOperator`, then specify that they run sequentially (`extract` then `transform` then `load`).

### Create equivalent Prefect tasks

In Prefect, we'll take the core logic of `extract_fn`, `transform_fn`, `load_fn` and turn each into a `@task` decorated function. The code inside can remain largely the same (minus any Airflow-specific cruft). For example:

{/* pmd-metadata: notest */}

```python
# Prefect tasks for ETL
from prefect import task, flow

@task
def extract_data():
    # ... (extract data as before)
    return data

@task
def transform_data(data):
    # ... (transform data as before)
    return processed_data

@task
def load_data(processed_data):
    # ... (load data as before)
```

Notice we simply applied `@task` to each function. No need for a special operator class or task IDs - the function name serves as an identifier, and Prefect will handle the orchestration.

### Define a Prefect flow

Now we write a `@flow` function that calls these tasks in the required order:

{/* pmd-metadata: notest */}

```python
@flow
def etl_pipeline():
    data = extract_data()         # calls extract_data task
    processed = transform_data(data)  # uses output of extract_data
    load_data(processed)          # calls load_data with result of transform_data
```

This Prefect flow function replaces the Airflow DAG. No need for `>>` dependencies or XComs. **Task results can be stored in variables that are passed directly to other tasks as arguments**. By default, tasks are automatically executed in the order they are called.

Unlike Airflow, where testing often requires an Airflow context, Prefect flows run like standard Python code. You can execute `etl_pipeline()` in an interpreter, import it elsewhere, or test tasks individually (`transform_data.fn(sample_data)`).

<Card title="Key Differences" icon="file-plus-minus">
  * **Airflow:** Defines operators, sets dependencies (`>>`), and relies on XCom for data passing.
  * **Prefect:** Calls tasks like functions, with execution order determined by data flow, making workflows more intuitive and testable.
</Card>

### Branching and conditional logic

In Airflow, conditional branching is typically handled using BranchPythonOperator, ShortCircuitOperator, or trigger rules, requiring explicit DAG constructs to determine execution paths. Prefect simplifies branching by leveraging standard Python if/else logic directly within flows.

**Implementing Branching in Prefect**

Instead of using BranchPythonOperator and dummy tasks for joining paths, you can structure conditional execution using native Python control flow:

{/* pmd-metadata: notest */}

```python
@flow
def my_flow():
    result = extract_data()
    if some_condition(result):
        outcome = branch_task_a()  # a task or subflow for branch A
    else:
        outcome = branch_task_b()  # branch B
    final_task(outcome)
```

**Key Differences from Airflow**

| **Feature**          | **Airflow (BranchPythonOperator)**                        | **Prefect (`if/else` logic)**                                           |
| -------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Branching Method** | Often uses specialized operators (`BranchPythonOperator`) | Uses native Python conditionals (`if/else`)                             |
| **Skipped Tasks**    | Unselected branches are explicitly **skipped**            | Prefect **only runs** the executed branch—no skipping needed            |
| **Join Behavior**    | Uses **DummyOperator** to rejoin paths                    | Downstream tasks execute **automatically** after the conditional branch |

**Advantages of Prefect’s Approach**

* **No special operators** — branching is simpler and more intuitive
* **Cleaner code** — fewer unnecessary tasks like `DummyOperator`
* **No explicit skipping required** — Prefect only executes the called tasks

By using standard Python control flow, Prefect **eliminates complexity** and makes conditional execution more **readable, maintainable, and testable**.

### Retries and error handling

Airflow DAGs often have retry settings either at the DAG level (`default_args`) or per task (e.g., `retries=3`). In Prefect, you can specify [retries](/v3/develop/write-flows#retries) for any task or flow.

Use `@task(retries=2, retry_delay_seconds=60)` to retry a task twice on failure, or `@flow(retries=1)` to retry the entire flow once. Prefect **distinguishes flow and task retries**—flow retries rerun all tasks, while task retries rerun only the failed task. Replace Airflow-specific error handling (`on_failure_callback`, sensors) with Prefect's **Retry**, **State Handlers**, or built-in failure notifications.

### Remove Airflow-specific code

Go through the DAG code and strip out anything that doesn't apply in Prefect.

This includes: DAG declarations (`DAG(...)` blocks), default\_args, Airflow imports (`from airflow...`), XCom push/pull calls (replace with return values), Jinja templating in operator arguments (you can often just compute those values in Python directly or use [Prefect parameters](/v3/deploy/index#workflow-scheduling-and-parametrization)).

If your DAG used Airflow Variables or Connections (Airflow's way to store config in the Metastore), you'll need to supply those to Prefect tasks via another means - for example, as [environment variables](/v3/develop/settings-and-profiles#environment-variables) or using [Prefect Blocks](/integrations/integrations) (like a Block for a database connection string). Essentially, your Prefect flow code should look like a regular Python script with functions, not like an Airflow DAG file.

As an illustration, here's how our example **ETL pipeline** looks after conversion:

{/* pmd-metadata: notest */}

```python
from prefect import flow, task

@task(retries=1, log_prints=True)
def extract_data():
    # fetch data from API (simulated)
    data = get_data_from_api()
    return data

@task
def transform_data(data):
    # process the data
    processed = transform(data)
    return processed

@task
def load_data(data):
    # load data to database
    load_into_db(data)

@flow(name="etl_pipeline")
def etl_pipeline_flow():
    raw = extract_data()
    processed = transform_data(raw)
    load_data(processed)

if __name__ == "__main__":
    # For local testing
    etl_pipeline_flow()
```

Key improvements in this converted code:

* **Direct execution for testing** - `if __name__ == "__main__": etl_pipeline_flow()` allows running the flow locally during development. In production, Prefect handles scheduling.
* **Built-in retries and logging** - `retries=1` ensures one retry on failure, and `log_prints=True` sends `print()` output to Prefect's UI.
* **Pure Python** - No Airflow imports or context, making the flow easy to test, debug, and run consistently across environments (IDE, CI, or production).

### Validate functional equivalence

Once a DAG has been rewritten as a Prefect flow, execute the flow and compare its results with the Airflow DAG to ensure expected outcomes. If discrepancies arise, modify the flow accordingly. Keep in mind the original DAG may have depended on XComs or global variables that you will need to account for.

For each task and special case, including [subDAGs](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html#concepts-subdags) and [TaskGroups](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html#taskgroups), implement them as subflows or Python functions in Prefect. When transitioning from Airflow's TaskFlow API, keep in mind that Prefect's `@task` decorator serves a similar purpose but does not rely on XComs.

After completing these steps, the Prefect flow should accurately replicate the functionality of the Airflow DAG while being more modular and testable. The migration is now complete, and the next step is to focus on deploying and optimizing the new workflows.

## Infrastructure Migration Considerations

Migrating your code is a big step, but ensuring your workflows run smoothly in Prefect is just as important. Prefect's **flexible execution** makes this easier, supporting Prefect managed execution, local machines, VMs, containers, and Kubernetes with less setup. This section maps Airflowss executors to **Prefect Work Pools and Workers**, while also covering sensors, hooks, logging, and state management to complete your migration.

### Leveraging Prefect Managed Execution

**Running Flows Without Infrastructure Setup**

Prefect Cloud offers [Managed Execution](/v3/how-to-guides/deployment_infra/serverless), allowing you to run flows **without setting up infrastructure or maintaining workers**. With Prefect Managed work pools, Prefect handles compute, execution, and scheduling, eliminating the need for a cloud provider account or on-premises infrastructure.

**Getting Started with Prefect Managed Execution**

<Steps>
  <Step title="Create a Prefect Managed Work Pool">
    ```bash
    prefect work-pool create my-managed-pool --type prefect:managed
    ```
  </Step>

  <Step title="Deploy a Flow to Managed Execution">
    {/* pmd-metadata: notest */}

    ```python
    from prefect import flow

    if __name__ == "__main__":
        flow.from_source(
            source="https://github.com/prefecthq/demo.git",
            entrypoint="flow.py:my_flow",
        ).deploy(
            name="test-managed-flow",
            work_pool_name="my-managed-pool",
        )
    ```
  </Step>

  <Step title="Run the Deployment via Prefect UI or CLI">
    ```bash
    python managed-execution.py
    ```
  </Step>
</Steps>

This will allow your flow to run remotely without provisioning workers, setting up Kubernetes, or maintaining cloud infrastructure.

**When to Use Prefect Managed Execution**

<CardGroup cols={2}>
  <Card title="Best for" icon="check" color="green">
    Ideal for testing and running flows without infrastructure setup, especially for teams that want managed execution without a cloud provider.
  </Card>

  <Card title="Consider self-hosted execution" icon="x" color="red">
    If you need custom images, heavy dependencies, private networking, or higher concurrency limits than Prefect's tiers allow.
  </Card>
</CardGroup>

**Next Steps**

If you require self-hosted execution, the next sections cover how to migrate Airflow Executors to Prefect Work Pools across different infrastructure types (Kubernetes, Docker, Celery, etc.).

For full details on Prefect Managed Execution, refer to the [Managed Execution documentation](/v3/how-to-guides/deployment_infra/serverless).

### Airflow Executors

**Airflow Executors vs Prefect Work Pools/Workers:** Airflow's executor setting determines how tasks are distributed. Prefect's equivalent concept is the [**work pool**](/v3/deploy/infrastructure-concepts/work-pools) (with one or more [**workers**](/v3/deploy/infrastructure-concepts/workers) polling it).

In Airflow, each task executes independently, regardless of the executor used. Whether running with LocalExecutor, CeleryExecutor, or KubernetesExecutor, every task runs as an isolated process or pod. Executors control how and where these tasks are executed, but the core execution model remains task-by-task.

In contrast, Prefect executes an entire flow run within a single execution environment (e.g., a local process, Docker container, or Kubernetes pod). Tasks within a flow execute within the same runtime context, reducing fragmentation and improving performance. Prefect's execution model simplifies resource management, allowing for in-memory data passing between tasks rather than relying on external storage or metadata databases.

Here's a mapping of typical setups:

#### Airflow LocalExecutor

With the **Airflow LocalExecutor** tasks run as subprocesses on the same machine. In Prefect, the default behavior is similar - you can run the flow in a local Python process, and tasks will execute sequentially by default. That does not *have* to be the same machine that is running your Prefect UI and scheduler.

For parallelism on a single machine, use [**`DaskTaskRunner`**](/integrations/prefect-dask/index) to enable multi-process execution:

{/* pmd-metadata: notest */}

```python
@flow(task_runner=DaskTaskRunner())
```

By default, Prefect's **Process work pool** runs flows as subprocesses. A basic **Airflow LocalExecutor** setup can be replaced with a **Prefect worker** on the same VM using a **process work pool**, eliminating the need for a separate scheduler.

#### Airflow CeleryExecutor

**Airflow CeleryExecutor** where distributed workers run across multiple machines, using a message broker like RabbitMQ/Redis.

Prefect eliminates the need for a **message broker** or **results backend**, as its API server manages work distribution. To replicate an Airflow **CeleryExecutor** setup, deploy **multiple Prefect workers** across machines, all polling from a shared **work pool**.

**Setting Up a Work Pool and Workers**

1. **Create a work pool** (e.g., `"prod-work-pool"`):
   ```bash
   prefect work-pool create prod-work-pool --type process
   ```
2. **Start a worker on each node**, assigning it to the work pool:
   ```bash
   prefect worker start -p prod-work-pool
   ```
3. **Workers poll the work pool** and execute assigned flow runs.

Prefect **work pools** function similarly to **Celery queues**, allowing multiple workers to process tasks concurrently.

#### Airflow KubernetesExecutor

In Airflow, the **KubernetesExecutor** follows the per-task execution model, launching each task in its own Kubernetes pod. Prefect, instead, uses a Kubernetes Work Pool, where each flow run executes in a single Kubernetes pod. This approach reduces fragmentation, as tasks run within the same execution environment rather than spawning separate pods.

**Configuring a Kubernetes Work Pool**
For detailed instructions, see [Prefect's Kubernetes Work Pool documentation](/v3/how-to-guides/deployment_infra/kubernetes). But the general steps to take are:

1. **Create a Kubernetes work pool** with the desired pod template (e.g., image, resources):
   ```bash
   prefect work-pool create k8s-pool --type kubernetes
   ```
2. **Deploy a flow to the Kubernetes work pool**:

{/* pmd-metadata: notest */}

```python
from prefect import flow

@flow(log_prints=True)
def buy():
    print("Buying securities")

if __name__ == "__main__":
    buy.deploy(
        name="my-code-baked-into-an-image-deployment",
        work_pool_name="k8s-pool",
        image="my_registry/my_image:my_image_tag"
    )
```

Alternatively, you can use a [prefect.yaml](/v3/how-to-guides/deployment_infra/kubernetes#define-a-prefect-deployment) file to deploy your flow to the Kubernetes work pool.

3. [**Run a Kubernetes worker in-cluster**](/v3/how-to-guides/deployment_infra/kubernetes#deploy-a-worker-using-helm) to execute flow runs.
4. **Execution Flow**:

* The worker **picks up a scheduled flow run**.
* It **creates a new pod**, which executes the entire flow.
* The **pod terminates automatically** after execution.

This setup eliminates the need for a long-running scheduler, reducing operational complexity while leveraging Kubernetes for **on-demand, containerized execution**.

#### Airflow CeleryKubernetes

**Airflow + Celery + Kubernetes (CeleryKubernetes Executor)** or other hybrid: Some Airflow deployments use Celery for distributed scheduling but run tasks in containers or on Kubernetes.

Prefect's model can handle these as well by combining approaches - e.g., use a Kubernetes work pool with multiple worker processes distributed as needed. The general principle is that Prefect **work pools** can cover all these patterns (local, multi-machine, containers, serverless) via configuration, not code, and you manage them via Prefect's UI/CLI.

#### Using Serverless compute

Prefect supports [**serverless execution**](/v3/how-to-guides/deployment_infra/serverless) on various cloud platforms, eliminating the need for dedicated infrastructure. Instead of provisioning long-running workers, flows can be executed **on-demand** in ephemeral environments. Prefect's push-based work pools allow flows to be submitted to serverless services, where they run in isolated containers and automatically scale with demand.

**Serverless Platforms**
Prefect flows can run on:

* **AWS ECS** (Fargate or EC2-backed containers)
* **Azure Container Instances (ACI)**
* **Google Cloud Run**
* **Modal** (serverless compute for AI/ML workloads)
* **Coiled** (serverless Dask clusters for parallel workloads)

**Configuring a Serverless Work Pool**
To run flows on a serverless platform, create a **push-based work pool** and configure it to submit jobs to the desired service.

Example: Creating an **ECS work pool**:

```bash
prefect work-pool create --type ecs:push --provision-infra my-ecs-pool
```

Deployments can then be configured to use the serverless work pool, allowing Prefect to submit flow runs without maintaining long-lived infrastructure.

For setup details, refer to [Prefect's serverless execution documentation](/v3/how-to-guides/deployment_infra/serverless).

### Airflow Sensors

Airflow Sensors continuously poll for external conditions, such as file availability or database changes, which can tie up resources. Prefect replaces this with an **event-driven approach**, where external systems trigger flow execution when conditions are met.

**Using External Triggers**
Instead of using an Airflow `S3KeySensor`, configure an AWS Lambda or EventBridge rule to call the Prefect API when an S3 file is uploaded. Prefect Cloud and Server provide API endpoints to start flows on demand. Prefect's **Automations** can also trigger flows based on specific conditions.

**Handling Polling Scenarios**
If an external system lacks event-driven capabilities, implement a lightweight **polling flow** that runs on a schedule (e.g., every 5 minutes), checks the condition, and triggers the main flow if met. This approach minimizes idle resource consumption compared to Airflow's persistent sensors.

Prefect's model eliminates long-running sensor tasks, making workflows **more efficient, scalable, and event-driven**.

### Airflow Hooks and Integrations

Airflow provides hooks and operators for interacting with external systems (e.g., **JDBC, cloud services, databases**). In Prefect, these integrations are handled through [**Prefect Integrations**](/integrations/integrations) (e.g., `prefect-snowflake`, `prefect-gcp`, `prefect-dbt`) or by directly using the relevant **Python libraries** within tasks.

**Migrating Airflow Hooks to Prefect**

1. **Identify Airflow hooks** used in your DAGs (e.g., `PostgresHook`, `GoogleCloudStorageHook`).
2. **Replace them with equivalent Prefect integrations** or direct Python library calls.

**Example:** Instead of

{/* pmd-metadata: notest */}

```python
hook = PostgresHook(postgres_conn_id=my_conn_id)
engine = hook.get_sqlalchemy_engine()
session = sessionmaker(bind=engine)()
```

Use Prefect Blocks for secure credential management:

{/* pmd-metadata: notest */}

```python
from prefect_sqlalchemy import SqlAlchemyConnector

SqlAlchemyConnector.load("BLOCK_NAME-PLACEHOLDER")
```

3. **Use Prefect Blocks for secrets management**, similar to Airflow Connections, to separate credentials from code.

**Replacing Airflow Operators with Prefect Tasks**

* **Prefect tasks** can call any Python library, eliminating the need for custom Airflow operators.
* Example: Instead of using a **BashOperator** to call an API via a shell script, install the necessary package in the flow's environment and call it directly in a task.

Prefect's approach **removes unnecessary abstraction layers**, allowing direct access to the full Python ecosystem without Airflow-specific constraints.

Basically: **anything done with a custom Airflow operator or hook can be replaced in Prefect with a task using the appropriate Python library.** Prefect removes Airflow's constraints, allowing direct use of the full Python ecosystem. For example, instead of using a **BashOperator** to call an API via a shell script, install the required package in your environment and call it directly from a task, eliminating unnecessary workarounds.

### Observability

#### State and logging

**Task and Flow State Management**
In Airflow, task states (`success`, `failed`, `skipped`, etc.) are stored in a metadata database and displayed in the Airflow UI's DAG run view. Prefect also tracks state for **each task and flow run**, but these states are managed by the **Prefect backend** (Prefect Server or Cloud API) and can be accessed via the **Prefect UI, API, or CLI**.

After migration, similar visibility is available in Prefect's UI, where you can track which flows and tasks succeeded or failed. Prefect also includes additional state management features such as:

* Cancel a flow run (`Cancelling` state).
* Retry a failed flow run (with manual steps).
* **Task caching** between runs to avoid redundant computations.

**Logging Differences**
Airflow logs task execution output to files (stored on executor machines or remote storage), viewable through the UI. Prefect **captures stdout, stderr, and Python logging** from tasks and sends them to the Prefect backend, making logs accessible in the **Prefect UI, API, and CLI**.

To ensure logs appear correctly in Prefect's UI, use `@flow(log_prints=True)` or `@task(log_prints=True)`

These flags route `print()` statements to Prefect logs automatically.

For centralized logging (e.g., ElasticSearch, Stackdriver), Prefect supports [**custom logging handlers**](/v3/advanced/logging-customization) and **third-party integrations**. Logs can be forwarded similarly to how Airflow handled external logging.

**Debugging and Troubleshooting**
Prefect simplifies debugging because tasks are **standard Python functions**. Instead of analyzing scheduler or worker logs, you can:

* **Re-run individual tasks or flows locally** to reproduce issues.
* **Test flows interactively** in an IDE before deploying.

This direct execution model eliminates the need to troubleshoot failures through a scheduling system, making debugging faster and more intuitive than in Airflow.

#### Monitoring

**Notifications and Alerts**
In Airflow, monitoring is typically managed through the UI, email alerts on task failures, and external monitoring of the scheduler.
Prefect provides similar capabilities through *Automations*, which can be configured to trigger alerts via Slack, email, or webhooks based on specific events.

To replicate Airflow's alerting (e.g., failures or SLA misses), configure [**Prefect Automations**](/v3/automate/events/automations-triggers) to:

* Notify on **flow or task failures**.
* Alert when a **flow run exceeds a specified runtime**.
* Trigger **custom actions** based on state changes.

**Service Level Agreements (SLAs)**
Prefect Cloud supports Service Level Agreements (SLAs) to monitor and enforce performance expectations for flow runs. SLAs automatically trigger alerts when predefined thresholds are violated.

SLAs can be defined via the Prefect UI, prefect.yaml, `.deploy()` method, or CLI. Violations generate `prefect.sla.violation` events, which can trigger Automations to send notifications or take corrective actions.

For full configuration details, refer to the [Measure reliability with Service Level Agreements](/v3/automate/events/slas) documentation.

**Implementation Considerations**
Prefect allows flexible logging and alerting adjustments to match existing monitoring workflows. Logging handlers can integrate with **third-party services** (e.g., ElasticSearch, Datadog), and **Prefect's API and UI provide real-time state visibility** for proactive monitoring.

## Deployment & CI/CD Changes

Deploying workflows in Prefect differs from Airflow's approach of “drop DAG files in a folder.” In Prefect, a **Deployment** is the unit of deployment: it associates a flow (Python function) with infrastructure (how/where to run) and optional schedule or triggers. Migrating to Prefect means adopting a new way to package and release your workflows, as well as updating any CI/CD pipelines that automated your Airflow deployments.

### Prefect Deployment

**From Airflow DAG schedules to Prefect Deployment:** In Airflow, deployment usually meant placing your DAG code on the Airflow scheduler (e.g., by committing to a Git repo that the scheduler reads, or copying files to the DAGs directory). There isn't a formal deployment artifact beyond the Python files. Prefect, by contrast, treats deployments as first-class objects. You will create a deployment for each flow (or for each distinct configuration of a flow you want to run). This can be done via code (calling `flow.deploy()`), via CLI (`prefect deployment`), or by writing a YAML (`prefect.yaml`) that describes the deployment.

Key things a **Prefect deployment** defines:

* **Target flow** (which function, and which file or import path it comes from).
* **Infrastructure configuration**: e.g., use the “Kubernetes work pool” or “process” type, possibly the docker image to use, resource settings, etc.
* **Storage of code**: e.g., whether the code is stored in the image, pulled from Git, etc. (Prefect can package code into a Docker image or rely on an existing image).
* **Schedule** (optional): e.g., Cron or interval schedule for automatic runs, or you can leave it manual.
* **Parameters** (optional): default parameter values for the flow, if any.

To migrate each Airflow DAG, you will create a Prefect deployment for its flow. For example, if we converted `etl_pipeline` DAG to `etl_pipeline_flow` in Prefect, we might write a `prefect.yaml` like:

```yaml
# prefect.yaml
deployments:
  - name: etl-pipeline-prod
    flow_name: etl_pipeline_flow
    entrypoint: etl_flow.py:etl_pipeline_flow # file and function where the flow is defined
    parameters: {}
    schedule: "@daily"
    work_pool:
      name: prod-k8s-pool
      # other infra settings like image, etc., if needed
```

This YAML can define multiple deployments, but in this case we have one named “etl-pipeline-prod” which runs daily via the `prod-k8s-pool` (a Kubernetes pool perhaps). In Airflow, these details were all intertwined in the DAG file (the schedule was in code, the infrastructure maybe in the executor config or the DAG via `executor_config`). In Prefect, there is a separation of these concerns.

### Automation via CI/CD

Many organizations use CI/CD to deploy Airflow DAGs (for example, a Git push triggers a Jenkins job that lints DAGs and copies them to the Airflow server). With Prefect, you'll likely adjust your CI/CD to **register Prefect deployments** whenever you update the flow code. Prefect's CLI is your friend here. A common pattern is:

1. On merge to main, build a Docker image with your flow code, push it to a registry
2. Then run `prefect deployment build -n <name> -p <work_pool_name> --cron "<schedule>" -q default -o deployment.yaml` (or use `prefect.yaml`) and apply it.

This can all be scripted. In fact, Prefect provides guidance on using [GitHub Actions or similar tooling to do this](/v3/advanced/deploy-ci-cd). By integrating Prefect's deployment steps into CI, you ensure that any change in your flow code gets reflected in Prefect's orchestrator, much like updating DAG code in Airflow.

Alternatively, if your deployment is set to pull the workflow code from your git repository each time, you only need to push the latest workflow code, and automatically next time your deployment runs it will pull the latest workflow code.

This CI pipeline approach allows versioning and automating your flows deployment, treating them similarly to application code deployments. It's a shift from Airflow where deployment could be syncing a folder - Prefect's method is more **controlled** and **atomic** (you create a deployment manifest and apply it, which registers everything with Prefect).

### Prefect in Production

Once deployed, Prefect schedules and orchestrates flows based on your **deployments**. Follow these best practices to ensure a reliable production setup:

* **High Availability**: If self-hosting, use PostgreSQL and consider running **multiple API replicas** behind a load balancer. [**Prefect Cloud**](https://prefect.io/cloud) handles availability automatically.
* **Keep Workers Active**: Ensure Prefect workers are always running, whether as systemd services, Docker containers, or Kubernetes deployments.
* **Logging & Observability**: Use Prefect's UI for logs or configure external storage (e.g., S3, Elasticsearch) for **long-term retention**.
* **Notifications & Alerts**: Set up failure alerts via Slack, email, or Twilio using [**Prefect Automations**](/v3/automate/events/automations-triggers) to ensure timely issue resolution.
* **CI/CD & Testing**: Validate deployment YAMLs in CI (`prefect deployment build --skip-upload`), and unit test tasks as regular Python functions.
* **Configuration Management**: Replace Airflow Variables/Connections with [**Prefect Blocks**](/v3/develop/variables), storing secrets via CLI, UI, or version-controlled JSON.
* **Security & Access Control**: Prefect Cloud includes built-in authentication & role-based access; self-hosted setups should secure API and workers accordingly.
* **Decommissioning Airflow**: Once migration is complete, disable DAGs, archive the code, and shut down Airflow components to reduce operational overhead.

For more details on operating Prefect in production, see the [How-To Guides](/v3/how-to-guides).

## Testing & Validation

Thorough testing ensures your Prefect flows perform like their Airflow equivalents. Since this is a **full migration**, validation is essential before decommissioning Airflow.

**Testing Prefect Flows in Isolation**

* **Unit test task logic** - Write tests for tasks as regular Python functions.
* **Run flows locally** - Run the script that calls your flow function - just like a normal Python script.
* **Use Prefect's local orchestration** - Start a Prefect server (`prefect server start`), register a deployment, and trigger flows via Prefect UI to mirror production behavior.
* **Compare outputs** - Run both Airflow and Prefect for the same input and validate results (e.g., database rows, file outputs). Debug discrepancies early.

**Validation Phase: Temporary Parallel Running (Shadow Mode)**

* **Keep the Airflow DAG inactive** but available for testing.
* **Manually trigger** both Airflow and Prefect flows for the same execution date.
* **Write test outputs separately** to prevent conflicts, ensuring parity before stopping Airflow runs.

For batch jobs, this phase should be **brief**, ensuring correctness without long-term dual maintenance.

**Decommissioning Airflow**
Once a Prefect flow is stable, **disable the corresponding Airflow DAG** to prevent accidental execution. Clearly document Prefect as the new source of truth. Avoid keeping inactive DAGs indefinitely, as they can cause confusion—**archive or remove them once the migration is complete**.

### Common issues and troubleshooting

* **Missing dependencies:** If a Prefect flow fails with `ImportError`, ensure all required libraries are installed in the execution environment (Docker image, VM, etc.), not just locally.
* **Credentials & access:** Verify that Prefect workers have the same permissions as Airflow (e.g., service accounts, IAM roles). If using Kubernetes, ensure pods can access necessary databases and APIs.
* **Scheduling differences:** Airflow schedules may trigger at the end of an interval, while Prefect runs in real-time. Align Cron schedules and time zones if needed.
* **Concurrency & parallelism:** Configure **work pool and flow run concurrency limits** to prevent overlapping jobs. If too many tasks run in parallel, use Prefect's **tags and concurrency controls** to throttle execution.
* **Error handling & retries:** Test retries by forcing failures. If Airflow used `trigger_rule="all_done"`, implement equivalent logic in Prefect with `try/except`.
* **Performance monitoring:** Compare Prefect vs. Airflow run times. If slower, check if tasks are running sequentially instead of in parallel (enable mapping, async, or parallel task runners). If too much parallelism, adjust concurrency settings.

For some help with troubleshooting, you can see articles on:

* [Configuring logging](/v3/how-to-guides/workflows/add-logging)
* [Tracking activity](/v3/concepts/events)

Throughout testing, keep an eye on the Prefect UI's **Flow Run and Task Run views** - they will show you the execution steps, logs, and any exceptions. The UI can be very helpful for pinpointing where a flow failed or hung. It's analogous to Airflow's Graph view and log view but with the benefit of real-time state updates (no need to refresh for state changes).

You might also consider joining the [Prefect Slack community](https://prefect.io/slack) to get help from the community and Prefect team.

**Debugging tips:**

* If a flow run gets stuck, you can cancel it via UI/CLI.
* Utilize the fact that you can re-run a Prefect flow easily. For example, if a specific task fails consistently, you can add some debug `print` statements, re-deploy (which is quick with Prefect CLI), and re-run to see output.
* Leverage Prefect's task state inspection. In the UI, you can often see the exception message and stack trace for a failed task, which helps identify the problem in code.
* Read the results from MarvinAI's analysis of your code to help identify potential issues.

<Frame caption="MarvinAI is a tool that can help you debug your Prefect flows.">
  <img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/marvin-ai.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=fe0535a244c49db9646518e953ef0965" alt="MarvinAI" data-og-width="626" width="626" data-og-height="155" height="155" data-path="v3/img/ui/marvin-ai.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/marvin-ai.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c6a13bd1975b54e61969dcb4be55e6b9 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/marvin-ai.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=425c3d02d50950b743e223093391210f 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/marvin-ai.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=d35d5ab21cdf2218b1348dbe94d2bf49 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/marvin-ai.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=4cf11d36b9973571407f84a99152a4c5 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/marvin-ai.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=63da3788dea45d11ccb0c7ef596e3557 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/marvin-ai.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=0c6ca79596e39e53060dd69343e402db 2500w" data-optimize="true" data-opv="2" />
</Frame>

As you systematically validate each migrated workflow, you'll build confidence in the new system. When all tests pass and the outputs match the old system's, you can declare the migration a success for that workflow. After migrating a few, you'll also develop a playbook for the rest, and the process may speed up.

## Post-Migration

### Optimizing & Scaling Prefect Workflows

With your workflows running in Prefect, it's time to optimize, scale, and take full advantage of its capabilities. This section covers best practices for streamlining flows, monitoring performance, and ensuring long-term reliability.

**Simplify and Enhance Your Workflows**

* **Remove unnecessary complexity**: If your Airflow DAGs used workarounds (e.g., database intermediaries for data passing), replace them with direct Prefect task returns.
* **Use nested flows for modularity**: Instead of chaining DAGs, use **nested flows** to orchestrate dependencies within a single flow.
* **Optimize async convenience**: Use **dynamic task mapping** (`task.map(items)`) to process large datasets efficiently.
* **Leverage caching**: Enable **result persistence** to skip redundant computations.
* **Ensure idempotency**: Prevent duplicate processing by parameterizing flows and validating execution logic.

**Monitor and Maintain Your Prefect System**

* **Track performance**: Use Prefect UI and analytics to monitor run durations, failure rates, and bottlenecks.
* **Set up alerts**: Automate failure notifications via Slack, email, or other integrations.
* **Improve debugging**: Use UI logs, parameterized re-runs, and version control for better issue resolution.
* **Version control deployments**: Treat flows like code, using PRs and staging environments before production deployment.
* **Update documentation**: Ensure internal runbooks reflect Prefect's CLI/UI for managing schedules, failures, and retries.

To scale and optimize for cost:

| Technique                 | Description                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| *Scale efficiently*       | Prefect makes it simple to distribute workloads across work pools and workers, eliminating Airflow's scheduler bottlenecks.  |
| *Optimize infrastructure* | Adjust worker capacity based on usage, scaling vertically (more resources per worker) or horizontally (adding more workers). |
| *Reduce costs*            | Consider *serverless work pools* (AWS ECS, GCP Cloud Run) to avoid idle infrastructure costs.                                |

To set yourself up for future success:

| Technique                       | Description                                                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| *Share best practices*          | Conduct a team retrospective to refine workflows and establish templates for new flows.                                         |
| *Embrace Prefect's flexibility* | Now that scheduling and execution are handled seamlessly, focus on building better data workflows, not managing infrastructure. |

### Conclusion

By completing this migration, you've moved to a more scalable, efficient orchestration system.
Prefect allows your team to focus on engineering—iterating faster, improving reliability, and scaling seamlessly.

**Next steps:**

* [Learn more about Prefect](/v3/get-started/index)
* [See more Prefect examples](/v3/examples/index)
* [Join the community](https://prefect.io/slack)
* [Dig into Prefect's Integrations](/integrations/integrations)
* [Learn more about Prefect Cloud](https://prefect.io/cloud)
* [Visit Prefect's GitHub](https://github.com/PrefectHQ/prefect)


# How to transfer resources between Prefect environments
Source: https://docs-3.prefect.io/v3/how-to-guides/migrate/transfer-resources

Migrate flows, deployments, work pools, and other resources between Prefect profiles

The `prefect transfer` command enables you to migrate resources between different Prefect environments, whether moving from development to production, from self-hosted to cloud, or between cloud workspaces.

The command accepts a `--from` and `--to` [profile](/v3/concepts/settings-and-profiles#profiles), and transfers all resources from the source to the destination.

<Info>
  The transfer command is available in Prefect [3.4.14](/v3/release-notes/oss/version-3-4) and later.
</Info>

## Quick start

Transfer all resources from a development environment to production:

```bash
prefect transfer --from local --to cloud
```

The command will:

1. Discover all resources in the source profile
2. Transfer resources to the destination profile
3. Report success, failures, and skipped resources

## What gets transferred

The transfer command moves the following resources:

* [Flows](/v3/concepts/flows) and [deployments](/v3/concepts/deployments)
* [Work pools](/v3/concepts/work-pools) and [work queues](/v3/concepts/work-pools#work-queues)
* [Blocks](/v3/concepts/blocks) and their associated schemas/types
* [Variables](/v3/concepts/variables)
* [Concurrency limits](/v3/how-to-guides/workflows/global-concurrency-limits)
* [Automations](/v3/concepts/automations)

Resources are transferred in the correct order to preserve relationships between them.

## Common transfer scenarios

### Development to production

Transfer resources between different environments:

```bash
prefect transfer --from dev-profile --to prod-profile
```

### Self-hosted to cloud migration

Move from a self-hosted Prefect server to Prefect Cloud:

```bash
prefect transfer --from self-hosted-profile --to cloud-profile
```

<Warning>
  When transferring to Prefect Cloud Hobby tier workspaces, certain resource types may be skipped due to tier limitations.
</Warning>

### Workspace consolidation

Resources can be transferred between multiple workspaces. Resources that already exist in the destination will be skipped.

## Resource handling

### Work pools

The transfer command handles different work pool types according to the destination:

* **Hybrid pools** (process, docker, kubernetes): Transfer to any destination (except Prefect Cloud Hobby tier workspaces)
* **Push pools**: Transfer only to Prefect Cloud destinations (except Prefect Cloud Hobby tier workspaces)
* **Managed pools**: Never transferred

### Existing resources

Resources that already exist in the destination are skipped you can run it multiple times safely.

```bash
# First run
prefect transfer --from dev --to prod
# Output: 25 succeeded, 0 skipped

# Second run (idempotent)
prefect transfer --from dev --to prod
# Output: 0 succeeded, 25 skipped
```

### Resource limits

When transferring to Prefect Cloud workspaces, certain resources may be skipped based on tier limitations. The transfer command will provide clear messages explaining why resources were skipped.

## Limitations

### Resources not transferred

Certain resources are not transferred between environments:

* Flow run history and logs
* Result artifacts and cached data
* Cloud-specific infrastructure resources
* Credentials and secrets (must be recreated in the destination)

### Environment-specific configuration

Some resources may require manual configuration after transfer to work correctly in the new environment, particularly those that reference external systems or credentials.

## Best practices

### Pre-transfer checklist

1. **Verify profiles**: Ensure both source and destination profiles are correctly configured
   ```bash
   prefect profile inspect source-profile
   prefect profile inspect dest-profile
   ```

2. **Test connectivity**: Confirm you can connect to both environments
   ```bash
   prefect --profile source-profile config view
   prefect --profile dest-profile config view
   ```

3. **Check tier limitations**: Understand destination workspace capabilities
   * Hobby tier: Managed pools only, 5 deployment limit
   * Standard/Pro tier: Full resource support

### Post-transfer validation

After transferring resources:

1. **Verify critical resources**:
   ```bash
   prefect --profile dest-profile work-pool ls
   prefect --profile dest-profile deployment ls
   ```

2. **Test a deployment**:
   ```bash
   prefect --profile dest-profile deployment run my-deployment/my-flow
   ```

3. **Check automation status**:
   ```bash
   prefect --profile dest-profile automation ls
   ```

## Troubleshooting

### Common issues

**Resources skipped as "already exists"**

* This is expected when resources already exist in the destination
* The transfer can be run multiple times safely

**Resources skipped due to tier limitations**

* Some resource types require specific Prefect Cloud tiers
* Check your workspace tier and capabilities

**Connection errors**

* Verify both profiles are correctly configured
* Check network connectivity and authentication

### Debug mode

For detailed transfer information, enable debug logging:

```bash
PREFECT_LOGGING_LEVEL=DEBUG prefect transfer --from source --to dest
```

## See also

* [Settings and profiles](/v3/concepts/settings-and-profiles) for configuring source and destination profiles
* [Work pools](/v3/concepts/work-pools) for understanding pool types
* [Prefect Cloud pricing](https://www.prefect.io/pricing) for workspace capabilities


# How to upgrade from agents to workers
Source: https://docs-3.prefect.io/v3/how-to-guides/migrate/upgrade-agents-to-workers

Learn how to upgrade from agents to workers to significantly enhance the experience of deploying flows.

Upgrading from agents to workers significantly enhances the experience of deploying flows
by simplifying the specification of each flow's infrastructure and runtime environment.

<Note>
  This guide is for users who are upgrading from agents (a deployment pattern specific to `prefect>2.0,<3.0`) to workers.
  If you are new to Prefect, we recommend starting with the
  [Prefect Quickstart](/v3/get-started/quickstart/).
</Note>

## About workers and agents

A [worker](/v3/concepts/workers) is the fusion of an
agent with an infrastructure block.
Like agents, workers poll a work pool for flow runs that are scheduled to start.
Like infrastructure blocks, workers are typed. They work with only one kind of infrastructure,
and they specify the default configuration for jobs submitted to that infrastructure.

Accordingly, workers are not a drop-in replacement for agents. **Using workers requires
deploying flows differently.** In particular, deploying a flow with a worker does not involve
specifying an infrastructure block. Instead, infrastructure configuration is specified on the
[work pool](/v3/concepts/work-pools) and passed to each worker that polls work
from that pool.

## Upgrade enhancements

### Workers

* Improved visibility into the status of each worker, including when a worker was started
  and when it last polled.
* Better handling of race conditions for high availability use cases.

### Work pools

* Work pools allow greater customization and governance of infrastructure parameters for deployments
  through their [base job template](/v3/how-to-guides/deployment_infra/manage-work-pools#base-job-template).
* Prefect Cloud [push work pools](/v3/how-to-guides/deployment_infra/serverless) enable flow
  execution in your cloud provider environment without the need to host a worker.
* Prefect Cloud [managed work pools](/v3/how-to-guides/deployment_infra/managed) allow you to run flows on
  Prefect's infrastructure, without the need to host a worker or configure cloud provider infrastructure.

### Improved deployment interfaces

* The Python deployment experience with [`.deploy()`](/v3/how-to-guides/deployments/deploy-via-python) or the alternative deployment experience with
  `prefect.yaml` are more flexible and easier to use than block and agent-based deployments.
* Both options allow you to [deploy multiple flows](/v3/deploy/infrastructure-concepts/prefect-yaml/#work-with-multiple-deployments-with-prefect-yaml)
  with a single command.
* Both options allow you to build Docker images for your flows to create portable execution environments.
* The YAML-based API supports [templating](/v3/deploy/infrastructure-concepts/prefect-yaml/#templating-options)
  to enable [dryer deployment definitions](/v3/how-to-guides/deployments/prefect-yaml#reuse-configuration-across-deployments).

## Upgrade changes

1. **Deployment CLI and Python SDK:**

   `prefect deployment build <entrypoint>`/`prefect deployment apply` --> [`prefect deploy`](/v3/deploy/infrastructure-concepts/prefect-yaml/#deployment-declaration-reference)

   Prefect now automatically detects flows in your repo and provides a [wizard](/v3/#step-5-deploy-the-flow)
   to guide you through setting required attributes for your deployments.

   `Deployment.build_from_flow` --> [`flow.deploy`](https://reference.prefect.io/prefect/flows/#prefect.flows.Flow.deploy)

2. **Configuring remote flow code storage:**

   storage blocks --> [pull action](/v3/deploy/infrastructure-concepts/prefect-yaml/#the-pull-action)

   When using the YAML-based deployment API, you can configure a pull action in your `prefect.yaml`
   file to specify how to retrieve flow code for your deployments. You can use configuration from your
   existing storage blocks to define your pull action [through templating](/v3/deploy/infrastructure-concepts/prefect-yaml/#templating-options).

   When using the Python deployment API, you can pass any storage block to the `flow.deploy` method to
   specify how to retrieve flow code for your deployment.

3. **Configuring flow run infrastructure:**

   infrastructure blocks --> [typed work pool](/v3/deploy/infrastructure-concepts/workers/#worker-types)

   Default infrastructure config is now set on the typed work pool, and can be overwritten by
   individual deployments.

4. **Managing multiple deployments:**

   Create and/or update many deployments at once through a
   [`prefect.yaml`](/v3/deploy/infrastructure-concepts/prefect-yaml/#work-with-multiple-deployments-with-prefect-yaml)
   file or use the [`deploy`](/v3/how-to-guides/deployments/deploy-via-python)
   function.

## What's similar

* You can set storage blocks as the pull action in a `prefect.yaml` file.

* Infrastructure blocks have configuration fields similar to typed work pools.

* Deployment-level infrastructure overrides operate in much the same way.

  `infra_override` -> [`job_variable`](/v3/deploy/infrastructure-concepts/prefect-yaml/#work-pool-fields)

* The process for starting an agent and [starting a worker](/v3/deploy/infrastructure-concepts/workers/#start-a-worker)
  in your environment are virtually identical.

  `prefect agent start --pool <work pool name>` --> `prefect worker start --pool <work pool name>`

<Tip>
  **Worker Helm chart**

  If you host your agents in a Kubernetes cluster, you can use the [Prefect worker Helm chart](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker)
  to host workers in your cluster.
</Tip>

## Upgrade steps

If you have existing deployments that use infrastructure blocks, you can quickly upgrade them to
be compatible with workers by following these steps:

1. **[Create a work pool](/v3/deploy/infrastructure-concepts/work-pools/#work-pool-configuration)**

This new work pool replaces your infrastructure block.

You can use the [`.publish_as_work_pool`](https://docs.prefect.io/2.19.2/api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.publish_as_work_pool)
method on any infrastructure block to create a work pool with the same configuration.

{/*
  <!-- vale off -->
  */}

For example, if you have a `KubernetesJob` infrastructure block named 'my-k8s-job', you can
create a work pool with the same configuration with this script:

```python
from prefect.infrastructure import KubernetesJob


KubernetesJob.load("my-k8s-job").publish_as_work_pool()
```

Running this script creates a work pool named 'my-k8s-job' with the same configuration as your infrastructure block.

{/*
  <!-- vale on -->
  */}

<Tip>
  **Serving flows**
  If you are using a `Process` infrastructure block and a `LocalFilesystem` storage block
  (or aren't using an infrastructure and storage block at all), you can use [`flow.serve`](/v3/deploy/index)
  to create a deployment without specifying a work pool name or start a worker.

  This is a quick way to create a deployment for a flow and manage your
  deployments if you don't need the dynamic infrastructure creation or configuration offered
  by workers.
</Tip>

2. **[Start a worker](/v3/deploy/infrastructure-concepts/workers/#start-a-worker)**

This worker replaces your agent and polls your new work pool for flow runs to execute.

```bash
prefect worker start -p <work pool name>
```

3. **Deploy your flows to the new work pool**

To deploy your flows to the new work pool, use `flow.deploy` for a Pythonic deployment
experience or `prefect deploy` for a YAML-based deployment experience.

If you currently use `Deployment.build_from_flow`, we recommend using `flow.deploy`.

If you currently use `prefect deployment build` and `prefect deployment apply`, we recommend
using `prefect deploy`.

### Use `flow.deploy`

If you have a Python script that uses `Deployment.build_from_flow` to create a deployment, you
can replace it with `flow.deploy`.

You can translate most arguments to `Deployment.build_from_flow` directly to `flow.deploy`,
but here are some possible changes you may need:

* Replace `infrastructure` with `work_pool_name`.
  * If you've used the `.publish_as_work_pool` method on your infrastructure block, use the
    name of the created work pool.
* Replace `infra_overrides` with `job_variables`.
* Replace `storage` with a call to [`flow.from_source`](/v3/deploy/index).
  * `flow.from_source` loads your flow from a remote storage location and makes it deployable.
    You can pass your existing storage block to the `source` argument of `flow.from_source`.

Below are some examples of how to translate `Deployment.build_from_flow` into `flow.deploy`.

#### Deploying from a local file

Using agents and `Deployment.build_from_flow` to deploy a flow from a local file looked like:

```python
from prefect import flow


@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a Python script!")


if __name__ == "__main__":
    Deployment.build_from_flow(
        my_flow,
        name="my-deployment",
        parameters=dict(name="Marvin"),
    )
```

When using workers, you can accomplish the same local-storage deployment with `flow.deploy`:

```python example.py
from pathlib import Path
from prefect import flow


@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a Python script!")


if __name__ == "__main__":
    my_flow.from_source(
        source=str(Path(__file__).parent),
        entrypoint="example.py:my_flow",
    ).deploy(
        name="my-deployment",
        parameters=dict(name="Marvin"),
        work_pool_name="local",
    )
```

You can then start a worker to execute scheduled runs, pulling the flow code from `example.py`:

```bash
# starts a worker and creates `local` Process work pool if it doesn't exist
prefect worker start --pool local
```

<Note>
  If you'd like to immediately serve this flow as a deployment without running a worker or using work pools, you can [use `flow.serve`](/v3/how-to-guides/deployment_infra/run-flows-in-local-processes).
</Note>

#### Deploying using a storage block

If you currently use a storage block to load your flow code but no infrastructure block:

```python
from prefect import flow
from prefect.filesystems import GitHub


@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a GitHub repo!")


if __name__ == "__main__":
    Deployment.build_from_flow(
        my_flow,
        name="my-deployment",
        storage=GitHub.load("demo-repo"),
        parameters=dict(name="Marvin"),
    )
```

You can use `flow.from_source` to load your flow from the same location and `flow.deploy` to
create a deployment:

```python example.py
from prefect import flow
from prefect.blocks.system import Secret
from prefect.runner.storage import GitRepository

@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a GitHub repo!")

if __name__ == "__main__":
    flow.from_source(
        source=GitRepository(
            url="https://github.com/me/myrepo.git",
            credentials={"username": "oauth2", "access_token": Secret.load("my-github-pat")},
        ),
        entrypoint="example.py:my_flow"
    ).deploy(
        name="my-deployment",
        parameters=dict(name="Marvin"),
        work_pool_name="local", # or the name of your work pool
    )
```

#### Deploy using an infrastructure block and a storage block

For the code below, you need to create a work pool from your infrastructure block and pass it to
`flow.deploy` as the `work_pool_name` argument. You also need to pass your storage block to
`flow.from_source` as the `source` argument.

```python example.py
from prefect import flow
from prefect.deployments import Deployment
from prefect.filesystems import GitHub # this block class no longer exists
from prefect.infrastructure.kubernetes import KubernetesJob


@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a GitHub repo!")

repo = GitHub.load("demo-repo")

if __name__ == "__main__":
    Deployment.build_from_flow(
        my_flow,
        name="my-deployment",
        storage=repo,
        entrypoint="example.py:my_flow",
        infrastructure=KubernetesJob.load("my-k8s-job"),
        infra_overrides=dict(pull_policy="Never"),
        parameters=dict(name="Marvin"),
    )
```

The equivalent deployment code using `flow.deploy` should look like this:

```python example.py
from prefect import flow

if __name__ == "__main__":
    flow.from_source(
        source="https://github.com/me/myrepo.git",
        entrypoint="example.py:my_flow"
    ).deploy(
        name="my-deployment",
        work_pool_name="my-k8s-job",
        job_variables=dict(pull_policy="Never"),
        parameters=dict(name="Marvin"),
    )
```

{/*
  <!-- vale off -->
  */}

<Note>
  When using `flow.from_source().deploy()` with a remote `source`such as a `GitHub` block or `str` URL like [https://github.com/me/myrepo.git](https://github.com/me/myrepo.git)), the flow you're deploying doesn't need to be available locally before running your script.
  See the [SDK reference](https://reference.prefect.io/prefect/#prefect.Flow.from_source) for more info on `from_source`.
</Note>

{/*
  <!-- vale on -->
  */}

#### Deploy via a Docker image

If you currently bake your flow code into a Docker image before deploying, you can use the
`image` argument of `flow.deploy` to build a Docker image as part of your deployment process:

```python
from prefect import flow

@flow(log_prints=True)
def my_flow(name: str = "world"):
    print(f"Hello {name}! I'm a flow from a Docker image!")


if __name__ == "__main__":
    my_flow.deploy(
        name="my-deployment",
        image="my-repo/my-image:latest",
        work_pool_name="my-k8s-job",
        job_variables=dict(pull_policy="Never"),
        parameters=dict(name="Marvin"),
    )
```

You can skip a `flow.from_source` call when building an image with `flow.deploy`. Prefect
keeps track of the flow's source code location in the image and loads it from that location when the
flow is executed.

### Use `prefect deploy`

<Warning>
  **Always run `prefect deploy` commands from the `root` level of your repo!**

  With agents, you may have multiple `deployment.yaml` files. But under worker deployment
  patterns, each repo has a single `prefect.yaml` file located at the **root** of the repo
  that contains [deployment configuration](/v3/deploy/infrastructure-concepts/prefect-yaml/#work-with-multiple-deployments-with-prefect-yaml)
  for all flows in that repo.
</Warning>

To set up a new `prefect.yaml` file for your deployments, run the following command from the root
level of your repo:

```bash
prefect deploy
```

This starts a wizard that guides you through setting up your deployment.

<Note>
  **For step 4, select `y` on the last prompt to save the configuration for the deployment.**

  Saving the configuration for your deployment results in a `prefect.yaml` file populated
  with your first deployment. You can use this YAML file to edit and [define multiple deployments](/v3/deploy/infrastructure-concepts/prefect-yaml/#work-with-multiple-deployments-with-prefect-yaml)
  for this repo.
</Note>

You can add more [deployments](/v3/deploy/infrastructure-concepts/prefect-yaml/#deployment-declaration-reference)
to the `deployments` list in your `prefect.yaml` file and/or by continuing to use the deployment
creation wizard.

For more information on deployments, check out our [in-depth guide for deploying flows to work pools](/v3/how-to-guides/deployment_infra/serve-flows-docker).


# How to upgrade to Prefect 3.0
Source: https://docs-3.prefect.io/v3/how-to-guides/migrate/upgrade-to-prefect-3

Learn how to upgrade from Prefect 2.x to Prefect 3.0.

Prefect 3.0 introduces a number of enhancements to the OSS product: a new events & automations backend for event-driven workflows and observability, improved runtime performance, autonomous task execution and a streamlined caching layer based on transactional semantics.

The majority of these enhancements maintain compatibility with most Prefect 2.0 workflows, but there are a few caveats that you may need to adjust for.

To learn more about the enhanced performance and new features, see [What's new in Prefect 3.0](/v3/get-started/whats-new-prefect-3).

For the majority of users, upgrading to Prefect 3.0 will be a seamless process that requires few or no code changes.
This guide highlights key changes that you may need to consider when upgrading.

<Info>
  **Prefect 2.0** refers to the 2.x lineage of the open source prefect package, and **Prefect 3.0** refers exclusively to the 3.x lineage of the prefect package. Neither version is strictly tied to any aspect of Prefect's commercial product, [Prefect Cloud](/v3/how-to-guides/cloud/connect-to-cloud).
</Info>

## Quickstart

To upgrade to Prefect 3.0, run:

```bash
pip install -U prefect
```

If you self-host a Prefect server, run this command to update your database:

```bash
prefect server database upgrade
```

If you use a Prefect integration or extra, remember to upgrade it as well. For example:

```bash
pip install -U 'prefect[aws]'
```

## Upgrade notes

### Pydantic V2

Prefect 3.0 is built with Pydantic 2.0 for improved performance. All Prefect objects will automatically upgrade, but if you use custom Pydantic models for flow parameters or custom blocks, you'll need to ensure they are compatible with Pydantic 2.0. You can continue to use Pydantic 1.0 models in your own code if they do not interact directly with Prefect.

Refer to [Pydantic's migration guide](https://docs.pydantic.dev/latest/migration/) for detailed information on necessary changes.

<Warning>
  We recommend pausing all deployment schedules prior to upgrading.
  Because of differences in Pydantic datetime handling that affect the scheduler's idempotency logic, there is a small risk of the scheduler duplicating runs in its first loop.
</Warning>

### Module location and name changes

Some less-commonly used modules have been renamed, reorganized, or removed for clarity. The old import paths will continue to be supported for 6 months, but emit deprecation warnings. You can look at the [deprecation code](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/_internal/compatibility/migration.py) to see a full list of affected paths.

### Async tasks in synchronous flows

<info>
  This change affects you if: you use advanced asynchronous behaviors in your flows.
</info>

In Prefect 2.0, it was possible to call native `async` tasks from synchronous flows, a pattern that is not normally supported in Python. Prefect 3.0.0 removes this behavior to reduce complexity and potential issues and edge cases. If you relied on asynchronous tasks in synchronous flows, you must either make your flow asynchronous or use a task runner that supports asynchronous execution.

### Flow final states

<info>
  This change affects you if: you want your flow to fail if any task in the flow fails, and you invoke your tasks in a way that doesn't automatically raise an error (including submitting them to a `TaskRunners`).
</info>

In Prefect 2.0, the final state of a flow run was influenced by the states of its task runs; if any task run failed, the flow run was marked as failed.

In Prefect 3.0, the final state of a flow run is entirely determined by:

1. The `return` value of the flow function (same as in Prefect 2.0):
   * Literal values are considered successful.
   * Any explicit `State` that is returned will be considered the final state of the flow run. If an iterable of `State` objects is returned, all must be `Completed` for the flow run to be considered `Completed`. If any are `Failed`, the flow run will be marked as `Failed`.

2. Whether the flow function allows an exception to `raise`:
   * Exceptions that are allowed to propagate will result in a `Failed` state.
   * Exceptions suppressed with `raise_on_failure=False` will not affect the flow run state.

This change means that task failures within a flow do not automatically cause the flow run to fail unless they affect the flow's return value or raise an uncaught exception.

<Warning>
  When migrating from Prefect 2.0 to Prefect 3, be aware that flows may now complete successfully even if they contain failed tasks, unless you explicitly handle task failures.
</Warning>

To ensure your flow fails when critical tasks fail, consider these approaches:

1. Allow task exceptions to propagate by not using `raise_on_failure=False`.
2. Use `return_state=True` and explicitly check task states to conditionally `raise` the underlying exception or return a failed state.
3. Use try/except blocks to handle task failures and return appropriate states.

#### Examples

<CodeGroup>
  ```python Allow Unhandled Exceptions
  from prefect import flow, task

  @task
  def failing_task():
      raise ValueError("Task failed")

  @flow
  def my_flow():
      failing_task()  # Exception propagates, causing flow failure

  try:
      my_flow()
  except ValueError as e:
      print(f"Flow failed: {e}")  # Output: Flow failed: Task failed
  ```

  ```python Use return_state
  from prefect import flow, task
  from prefect.states import Failed

  @task
  def failing_task():
      raise ValueError("Task failed")

  @flow
  def my_flow():
      state = failing_task(return_state=True)
      if state.is_failed():
          raise ValueError(state.result())
      return "Flow completed successfully"

  try:
      print(my_flow())
  except ValueError as e:
      print(f"Flow failed: {e}")  # Output: Flow failed: Task failed
  ```

  ```python Use try/except
  from prefect import flow, task
  from prefect.states import Failed

  @task
  def failing_task():
      raise ValueError("Task failed")

  @flow
  def my_flow():
      try:
          failing_task()
      except ValueError:
          return Failed(message="Flow failed due to task failure")
      return "Flow completed successfully"

  print(my_flow())  # Output: Failed(message='Flow failed due to task failure')
  ```
</CodeGroup>

Choose the strategy that best fits your specific use case and error handling requirements.

***

### Futures interface

<info>
  This change affects you if: you directly interact with `PrefectFuture` objects.
</info>

PrefectFutures now have a standard synchronous interface, with an asynchronous one [planned soon](https://github.com/PrefectHQ/prefect/issues/15008).

### Automatic task caching

<info>
  This change affects you if: you rely on side effects in your tasks
</info>

Prefect 3.0 introduces a powerful idempotency engine. By default, tasks in a flow run are automatically cached if they are called more than once with the same inputs. If you rely on tasks with side effects, this may result in surprising behavior. To disable caching, pass `cache_policy=None` to your task.

### Workers

<info>
  This change affects you if: you're using agents from an early version of Prefect 2.0.
</info>

In Prefect 2.0, agents were deprecated in favor of next-generation workers. Workers are now standard in Prefect 3. For detailed information on upgrading from agents to workers, please refer to our [upgrade guide](https://docs-3.prefect.io/v3/resources/upgrade-agents-to-workers).

### Resolving common gotchas

#### `AttributeError: 'coroutine' object has no attribute <some attribute>`

When within an asynchronous task or flow context, if you do **not** `await` an asynchronous function or method, this error will be raised when you try to use the object.

To fix it, `await` the asynchronous function or method or use `_sync=True`.

For example, `Block`'s `load` method is asynchronous in an async context:

<CodeGroup>
  ```python Incorrect
  from prefect.blocks.system import Secret

  async def my_async_function():
      my_secret = Secret.load("my-secret")
      print(my_secret.get()) # AttributeError: 'coroutine' object has no attribute 'get'
  ```

  ```python Correct
  from prefect.blocks.system import Secret

  async def my_async_function():
      my_secret = await Secret.load("my-secret")
      print(my_secret.get()) # This will work
  ```

  ```python Also Correct
  from prefect.blocks.system import Secret

  async def my_async_function():
      my_secret = Secret.load("my-secret", _sync=True)
      print(my_secret.get()) # This will work
  ```
</CodeGroup>

Similarly, if you never use an un-awaited coroutine, you may see a warning like this:

```python
RuntimeWarning: coroutine 'some_async_callable' was never awaited
...
RuntimeWarning: Enable tracemalloc to get the object allocation traceback
```

This is the same problem as above, and you may `await` the coroutine to fix it or use `_sync=True`.

#### `TypeError: object <some Type> can't be used in 'await' expression`

This error occurs when using the `await` keyword before an object that is not a coroutine.

To fix it, remove the `await`.

For example, `my_task.submit(...)` is *always* synchronous in Prefect 3.x:

<CodeGroup>
  ```python Incorrect
  from prefect import flow, task

  @task
  async def my_task():
      pass

  @flow
  async def my_flow():
      future = await my_task.submit() # TypeError: object PrefectConcurrentFuture can't be used in 'await' expression
  ```

  ```python Correct
  from prefect import flow, task

  @task
  async def my_task():
      pass

  @flow
  async def my_flow():
      future = my_task.submit() # This will work
  ```
</CodeGroup>

See the [Futures interface section](#futures-interface) for more information on this particular gotcha.

#### `TypeError: Flow.deploy() got an unexpected keyword argument 'schedule'`

In Prefect 3.0, the `schedule` argument has been removed in favor of the `schedules` argument.

This applies to both the `Flow.serve` and `Flow.deploy` methods.

<CodeGroup>
  ```python Prefect 2.0 {11}
  from datetime import timedelta
  from prefect import flow
  from prefect.client.schemas.schedules import IntervalSchedule

  @flow
  def my_flow():
      pass

  my_flow.serve(
      name="my-flow",
      schedule=IntervalSchedule(interval=timedelta(minutes=1))
  )
  ```

  ```python Prefect 3.0 {11}
  from datetime import timedelta
  from prefect import flow
  from prefect.schedules import Interval

  @flow
  def my_flow():
      pass

  my_flow.serve(
      name="my-flow",
      schedules=[Interval(timedelta(minutes=1))]
  )
  ```
</CodeGroup>


# How to run the Prefect Server via Docker Compose
Source: https://docs-3.prefect.io/v3/how-to-guides/self-hosted/docker-compose

Deploy a self-hosted Prefect server environment using Docker Compose, including PostgreSQL, Redis, server, background services, and worker.

This guide shows how to run a complete self-hosted Prefect server environment using Docker Compose. This setup includes the following services:

* `postgres`: PostgreSQL database
* `redis`: Redis message broker
* `prefect-server`: Prefect server
* `prefect-services`: Prefect background services
* `prefect-worker`: Prefect worker

## Docker Compose file

Create a `compose.yml` file with the following contents:

```yaml
services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: prefect
      POSTGRES_PASSWORD: prefect
      POSTGRES_DB: prefect
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U prefect"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  prefect-server:
    image: prefecthq/prefect:3-latest
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      PREFECT_API_DATABASE_CONNECTION_URL: postgresql+asyncpg://prefect:prefect@postgres:5432/prefect
      PREFECT_SERVER_API_HOST: 0.0.0.0
      PREFECT_MESSAGING_BROKER: prefect_redis.messaging
      PREFECT_MESSAGING_CACHE: prefect_redis.messaging
      PREFECT_REDIS_MESSAGING_HOST: redis
      PREFECT_REDIS_MESSAGING_PORT: 6379
      PREFECT_REDIS_MESSAGING_DB: 0
    command: prefect server start --no-services
    ports:
      - "4200:4200"

  prefect-services:
    image: prefecthq/prefect:3-latest
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      PREFECT_API_DATABASE_CONNECTION_URL: postgresql+asyncpg://prefect:prefect@postgres:5432/prefect
      PREFECT_MESSAGING_BROKER: prefect_redis.messaging
      PREFECT_MESSAGING_CACHE: prefect_redis.messaging
      PREFECT_REDIS_MESSAGING_HOST: redis
      PREFECT_REDIS_MESSAGING_PORT: 6379
      PREFECT_REDIS_MESSAGING_DB: 0
    command: prefect server services start

  prefect-worker:
    image: prefecthq/prefect:3-latest
    depends_on:
      prefect-server:
        condition: service_started
    environment:
      PREFECT_API_URL: http://prefect-server:4200/api
    command: prefect worker start --pool local-pool

volumes:
  postgres_data:
  redis_data:
```

## Running the stack

1. Save the `compose.yml` file to your local machine.

2. From the directory containing the file, start the stack by running:

```bash
docker compose up -d
```

3. Wait for all services to start (it may take a few moments).

4. Open your browser and navigate to [http://localhost:4200](http://localhost:4200) to access the Prefect UI.

5. To stop the stack, run:

```bash
docker compose down
```

## Notes

* The PostgreSQL database is preconfigured with user and database `prefect`.
* Redis is not strictly required but is recommended as the messaging broker when [scaling a Prefect server installation](/v3/advanced/self-hosted).
* The Prefect worker automatically registers a pool named `local-pool`.
* The Prefect server exposes the API on port 4200; ensure this port is free.
* Use `docker compose logs -f` to view live logs for all services.
* This `compose.yml` does not configure authentication. See the [authentication guide](/v3/advanced/security-settings#basic-authentication) for more information.

## Troubleshooting

* If the UI does not load, verify that port 4200 is not occupied by another process.
* Check container logs for errors with:

```bash
docker compose logs -f
```

* Make sure Docker and Docker Compose are installed and up to date.

***

For more information, see the official [Prefect documentation](https://docs.prefect.io).

***


# How to run a local Prefect server
Source: https://docs-3.prefect.io/v3/how-to-guides/self-hosted/server-cli

Get started with self-hosting by running Prefect server locally.

The [Prefect CLI](/v3/get-started/install) is the easiest way to start a local instance of Prefect server.

## Start the server

1. Spin up a self-hosted Prefect server instance UI with the `prefect server start` CLI command in the terminal:

```bash
prefect server start
```

2. Open the URL for the Prefect server UI ([http://127.0.0.1:4200](http://127.0.0.1:4200) by default) in a browser.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/self-hosted-server-dashboard.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=455fc524a4713d0a15710471edc5ca63" alt="Viewing the dashboard in the Prefect UI." data-og-width="2484" width="2484" data-og-height="1475" height="1475" data-path="v3/img/ui/self-hosted-server-dashboard.png" data-optimize="true" data-opv="2" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/self-hosted-server-dashboard.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=98822e1595dda10882658dcaee9e516d 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/self-hosted-server-dashboard.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=0027b8c73ee8dff1b914caf23b24dd17 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/self-hosted-server-dashboard.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=3cdeda13aa65efd4910e3c5c34703e00 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/self-hosted-server-dashboard.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=960f6558a26d3639108d198b602a83b8 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/self-hosted-server-dashboard.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c4b65c8b0e5a37008333bc0ea085ad42 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/self-hosted-server-dashboard.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=54e6ee3ec756ce20c13d523461918165 2500w" />

3. Shut down the Prefect server with ctrl  +  c in the terminal.

## Configure the server

Go to your terminal session and run this command to set the API URL to point to a self-hosted Prefect server instance:

```bash
prefect config set PREFECT_API_URL="http://127.0.0.1:4200/api"
```

You can save the API server address in a Prefect profile.
Whenever that profile is active, the API endpoint is at that address.
See [Profiles and configuration](/v3/develop/settings-and-profiles/) for more information on profiles and configurable Prefect settings.

## Database configuration

### Use SQLite (default)

By default, Prefect uses a SQLite database stored at `~/.prefect/prefect.db`. No additional configuration is needed for basic use.

### Use PostgreSQL

To use PostgreSQL as your database backend:

1. Set the database connection URL:

```bash
prefect config set PREFECT_API_DATABASE_CONNECTION_URL="postgresql+asyncpg://postgres:yourTopSecretPassword@localhost:5432/prefect"
```

2. Start the server:

```bash
prefect server start
```

For more database configuration options, see the [database settings reference](/v3/api-ref/settings-ref#database).

## Database management commands

### Reset the database

Clear all data and reapply the schema:

```bash
prefect server database reset -y
```

### Manage migrations

Apply database migrations:

```bash
# Upgrade to the latest version
prefect server database upgrade -y

# Downgrade to the previous version
prefect server database downgrade -y -r -1

# Downgrade to a specific revision
prefect server database downgrade -y -r d20618ce678e
```

For large databases, you may need to increase the timeout:

```bash
export PREFECT_API_DATABASE_TIMEOUT=600
prefect server database upgrade -y
```

## Multi-worker API server

For high-throughput scenarios, you can run the server with multiple worker processes to handle concurrent requests more efficiently:

```bash
prefect server start --workers 4
```

This starts 4 worker processes to handle API and UI requests concurrently.

### Requirements for multi-worker mode

Multi-worker mode has specific infrastructure requirements:

1. **PostgreSQL database** - SQLite is not supported due to database locking issues
2. **Redis messaging** - In-memory messaging doesn't work across processes

### Configuration example

```bash
# Set PostgreSQL connection
prefect config set PREFECT_API_DATABASE_CONNECTION_URL="postgresql+asyncpg://postgres:password@localhost:5432/prefect"

# Configure Redis messaging
prefect config set PREFECT_SERVER_EVENTS_MESSAGING_CACHE="prefect.server.utilities.messaging.redis"
prefect config set PREFECT_SERVER_EVENTS_MESSAGING_BROKER="prefect.server.utilities.messaging.redis"

# Configure Redis messaging host and port
export PREFECT_REDIS_MESSAGING_HOST="redis"
export PREFECT_REDIS_MESSAGING_PORT="6379"

# Start server with 4 workers
prefect server start --workers 4
```

<Tip>
  The number of workers should typically match the number of CPU cores available to your server process, but you may need to experiment to find the optimal value for your workload.
</Tip>

## Advanced configuration

For advanced deployment scenarios including:

* Running behind a reverse proxy
* Configuring SSL certificates
* Multi-server deployments
* Handling migration issues

See [How to scale self-hosted Prefect](/v3/advanced/self-hosted).


# How to run the Prefect server in Docker
Source: https://docs-3.prefect.io/v3/how-to-guides/self-hosted/server-docker

Run a containerized Prefect server instance with Docker.

You can use the official Prefect Docker image to run a server in a container.

If you're running a server in a Docker container, you need to:

* Port forward the server to your local machine (e.g. `-p 4200:4200`)
* Set the `--host` flag on the `prefect server start` command to `0.0.0.0`
* Set the API server address, `PREFECT_API_URL`, to use Prefect within a container.

For example:

```bash
docker run -p 4200:4200 -d --rm prefecthq/prefect:3-latest -- prefect server start --host 0.0.0.0
```

<Tip>
  The `-d` flag runs the container in detached mode (i.e. in the background) and the `--rm` flag removes the container once it is stopped.
</Tip>

After running this command, verify that your local `prefect` profile is configured to point at your containerized server.

```bash
prefect config view --show-secrets
```

Open the dashboard in your browser:

```bash
prefect dashboard open
```

For more information, see the Docker topic about [Networking using the host network](https://docs.docker.com/network/network-tutorial-host/).

## Further reading

* [How to scale self-hosted Prefect](/v3/advanced/self-hosted)
* [Server concepts](/v3/concepts/server)
* [How to manage settings](/v3/how-to-guides/configuration/manage-settings)


# How to run Prefect on Windows
Source: https://docs-3.prefect.io/v3/how-to-guides/self-hosted/server-windows

Learn how to run Prefect server and workers on Windows with PowerShell.

Prefect provides first-class Windows support with native PowerShell integration and full feature parity with other platforms. This guide covers Windows-specific setup and best practices.

## Windows support

Prefect provides comprehensive Windows support with the Windows ecosystem. Prefect automatically detects PowerShell and uses it as the default shell on Windows, allowing you to run shell commands and scripts naturally without additional configuration. The subprocess execution is fully compatible with Windows process management.

Windows path conventions are fully supported, including UNC paths for network storage. This allows you to configure Prefect to use network shares for databases, storage, and other resources, which is particularly useful in enterprise environments where shared storage is common:

```powershell
# Configure database on network share using UNC paths
prefect config set PREFECT_HOME="\\server\share\prefect-data"

# Or use mapped drives
prefect config set PREFECT_HOME="Z:\prefect-data"

# Standard Windows paths work as expected
prefect config set PREFECT_HOME="C:\ProgramData\Prefect"
```

Environment variables work using standard Windows conventions and can be set using PowerShell syntax, either for the current session or permanently for the user:

```powershell
# Set for current session
$env:PREFECT_API_DATABASE_TIMEOUT = "600"

# Set permanently for user
[System.Environment]::SetEnvironmentVariable("PREFECT_API_DATABASE_TIMEOUT", "600", "User")
```

Shell tasks automatically use PowerShell on Windows, providing access to the full Windows command ecosystem:

```python
from prefect import flow
from prefect_shell import shell_run_command

@flow
def windows_flow():
    # This will run in PowerShell by default on Windows
    result = shell_run_command(command="Get-Process prefect")
    return result
```

## Database configuration and workers

By default, Prefect uses SQLite stored at `%USERPROFILE%\.prefect\prefect.db` with no additional configuration needed. For production deployments, you can configure PostgreSQL using standard connection strings:

```powershell
prefect config set PREFECT_API_DATABASE_CONNECTION_URL="postgresql+asyncpg://postgres:password@localhost:5432/prefect"
```

Prefect workers on Windows support both process execution and Docker containers. Process workers run flows directly as Windows processes. Docker workers can leverage Windows containers for isolated execution environments:

```powershell
# Run flows as Windows processes
prefect worker start --pool my-process-pool --type process

# Use Windows containers with Docker Desktop
docker pull mcr.microsoft.com/windows/servercore:ltsc2019
prefect worker start --pool my-docker-pool --type docker
```

## Security and performance considerations

Windows environments require specific security configurations for optimal Prefect operation. You'll need to allow Prefect server through Windows Firewall and configure PowerShell execution policies. Additionally, antivirus software can significantly impact performance if not configured properly.

Configure Windows Firewall to allow Prefect server traffic on port 4200:

```powershell
# Run as Administrator
New-NetFirewallRule -DisplayName "Prefect Server" -Direction Inbound -Port 4200 -Protocol TCP -Action Allow
```

If you encounter PowerShell execution policy errors when running scripts or deployments, configure the execution policy for the current user:

```powershell
# Set execution policy for current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

For better performance, consider adding these directories to your antivirus exclusions: `%USERPROFILE%\.prefect\`, your Python installation directory, and temporary directories used by flows. This prevents real-time scanning from interfering with Prefect operations.

## Production deployment as Windows service

For production environments, you should run Prefect server as a Windows service to ensure it starts automatically and runs reliably. The Non-Sucking Service Manager (NSSM) is the recommended tool for this purpose. Download NSSM from [nssm.cc](https://nssm.cc) and install the service with administrator privileges:

```powershell
# Run as Administrator
nssm install PrefectServer
nssm set PrefectServer Application "C:\Path\To\Python\python.exe"
nssm set PrefectServer AppParameters "-m prefect server start"
nssm set PrefectServer AppDirectory "C:\Path\To\Your\Project"

# Set environment variables if needed
nssm set PrefectServer AppEnvironmentExtra "PREFECT_API_URL=http://localhost:4200/api"

nssm start PrefectServer
```

This configuration ensures Prefect server starts automatically when Windows boots and provides proper service management capabilities including automatic restarts on failure.

## Troubleshooting common Windows issues

Several Windows-specific issues can occur when running Prefect. The most common problems relate to PATH configuration, encoding issues, port conflicts, and permission errors.

### Command not found errors

These typically indicate PATH issues. Verify that the Python Scripts directory is in your PATH and restart PowerShell after making changes. You can also try running `where prefect` to see if the command is found.

For example, if the `prefect` command isn't found, you'll need to add the Python Scripts directory to your `PATH`. This is a common issue on Windows when Python isn't installed system-wide:

```powershell
# Check if Scripts directory is in PATH
$env:PATH -split ';' | Select-String "Scripts"

# Add Scripts directory to PATH (replace with your Python path)
$scriptsPath = "C:\Users\$env:USERNAME\AppData\Local\Programs\Python\Python39\Scripts"
$env:PATH += ";$scriptsPath"
```

### Port conflicts

These can prevent the server from starting. Check what's using port 4200 and kill the process if necessary:

```powershell
# Check what's using port 4200
netstat -ano | findstr :4200

# Kill process if needed (replace PID with actual process ID)
taskkill /PID 1234 /F
```

Alternatively, you can configure Prefect server to use a different port by setting the `PREFECT_SERVER_API_HOST` and `PREFECT_SERVER_API_PORT` environment variables:

```powershell
# Set server to use port 8080 instead of 4200
$env:PREFECT_SERVER_API_PORT = "8080"
prefect server start

# Update client configuration to match
prefect config set PREFECT_API_URL="http://127.0.0.1:8080/api"
```

### Character encoding errors

Character encoding errors (particularly `'charmap' codec` errors) can occur on some Windows systems. Set the Python I/O encoding to UTF-8:

```powershell
$env:PYTHONIOENCODING = "UTF-8"
```

### Permission errors

Permission errors often require running PowerShell as Administrator for system-wide changes, or checking file permissions on Prefect directories. Network connectivity issues typically involve Windows Firewall rules or corporate proxy settings.

## Additional Resources

For additional help with Windows-specific issues, check the [Prefect Community Slack](https://prefect.io/slack), search [GitHub Issues](https://github.com/PrefectHQ/prefect/issues) for Windows-related problems, or review PowerShell execution logs for detailed error messages.


# How to access runtime information
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/access-runtime-info



Use the `prefect.runtime` module to access runtime information from within a workflow.

```python
from prefect import flow
from prefect.runtime import flow_run


@flow
def moody_workflow(name: str):
    return f"I wish my parents had named me {name} instead of {flow_run.name}."
```

The value of `flow_run.name` will change between workflow runs to match the name of the flow run.

<Note>
  **Attributes of `prefect.runtime` are `None` if a value is not available**

  Attributes of `prefect.runtime` will never error when accessed. If a value is not available, the attribute will be `None`.

  ```python
  from prefect.runtime import flow_run

  assert flow_run.name is None
  ```
</Note>

See the `prefect.runtime` module [reference](/v3/api-ref/python) for all available attributes.


# How to add logging to a workflow
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/add-logging



### Emit custom logs

To emit custom logs, use `get_run_logger` from within a flow or task.

```python
from prefect import flow, task
from prefect.logging import get_run_logger


@task(name="log-example-task")
def logger_task():
    # this logger instance will emit logs 
    # associated with both the flow run *and* the individual task run
    logger = get_run_logger()
    logger.info("INFO level log message from a task.")
    logger.debug("DEBUG level log message from a task.")


@flow(name="log-example-flow")
def logger_flow():
    # this logger instance will emit logs
    # associated with the flow run only
    logger = get_run_logger()
    logger.info("INFO level log message.")
    logger.debug("DEBUG level log message.")
    logger.error("ERROR level log message.")
    logger.critical("CRITICAL level log message.")

    logger_task()
```

The logger returned by `get_run_logger` support the [standard Python logging methods](https://docs.python.org/3/library/logging.html). Any logs emitted by the logger will be associated with the flow run or task run they are emitted from and sent to the Prefect backend. Logs sent to the Prefect backend are visible in the Prefect UI.

<Warning>
  `get_run_logger()` can only be used in the context of a flow or task.

  To use a normal Python logger anywhere with your same configuration, use `get_logger()` from `prefect.logging`.

  The logger retrieved with `get_logger()` will **not** send log records to the Prefect API.
</Warning>

### Log with print statements

To send `print` statements to the Prefect backend as logs, set the `log_prints` kwarg to `True` on the flow or task.

```python
from prefect import task, flow

@task
def my_task():
    print("we're logging print statements from a task")

@flow(log_prints=True)
def my_flow():
    print("we're logging print statements from a flow")
    my_task()
```

The `log_prints` kwarg is inherited by default by nested flow runs and tasks. To opt out of logging `print` statements for a specific task or flow, set `log_prints=False` on the child flow or task.

```python
from prefect import task, flow

@task(log_prints=False)
def my_task():
    print("not logging print statements in this task")

@flow(log_prints=True)
def my_flow():
    print("we're logging print statements from a flow")
    my_task()
```

You can configure the default `log_prints` setting for all Prefect flow and task runs through the
`PREFECT_LOGGING_LOG_PRINTS` setting:

```bash
prefect config set PREFECT_LOGGING_LOG_PRINTS=True
```

## Access logs from the command line

You can retrieve logs for a specific flow run ID using Prefect's CLI:

```bash
prefect flow-run logs MY-FLOW-RUN-ID
```

This can be particularly helpful if you want to access the logs as a local file:

```bash
prefect flow-run logs  MY-FLOW-RUN-ID > flow.log
```


# How to produce workflow artifacts
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/artifacts



### Create link artifacts

To create a link artifact, use the `create_link_artifact()` function.

To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI,
provide a `key` argument to the `create_link_artifact()` function to track the artifact's history over time.
Without a `key`, the artifact is only visible in the Artifacts tab of the associated flow run or task run.

```python
from prefect import flow, task
from prefect.artifacts import create_link_artifact


@task
def my_first_task():
    create_link_artifact(
        key="irregular-data",
        link="https://nyc3.digitaloceanspaces.com/my-bucket-name/highly_variable_data.csv",
        description="## Highly variable data",
    )


@task
def my_second_task():
    create_link_artifact(
        key="irregular-data",
        link="https://nyc3.digitaloceanspaces.com/my-bucket-name/low_pred_data.csv",
        description="# Low prediction accuracy",
    )


@flow
def my_flow():
    my_first_task()
    my_second_task()


if __name__ == "__main__":
    my_flow()
```

<Tip>
  **Specify multiple artifacts with the same key for artifact lineage**

  You can specify multiple artifacts with the same key to easily track something very specific, such as irregularities in your data pipeline.
</Tip>

After running flows that create artifacts, view the artifacts in the **Artifacts** page of the UI.
Click into the "irregular-data" artifact to see its versions, along with custom descriptions and links to the relevant data.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/link-artifact-info.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=113a4fc91846eb134048dd79813a95de" alt="Link artifact details with multiple versions" data-og-width="2560" width="2560" data-og-height="1646" height="1646" data-path="v3/img/ui/link-artifact-info.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/link-artifact-info.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=a8cbf40518252c098dab6a24da3cc1e6 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/link-artifact-info.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c6a410985bef9d1465827d0c3dcd30a5 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/link-artifact-info.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=4d44e935bd4d8568a9364d574ea129bf 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/link-artifact-info.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=68760958c357a25bde126b040e90bbe3 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/link-artifact-info.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=cfe48216587d8142179d6bdcf1489eb3 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/link-artifact-info.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=b601d7b17b40c10af8089ffd8e9e2ec3 2500w" data-optimize="true" data-opv="2" />

You can also view information about the artifact such as:

* its associated flow run or task run id
* previous and future versions of the artifact (multiple artifacts can have the same key to show lineage)
* data (in this case a Markdown-rendered link)
* an optional Markdown description
* when the artifact was created or updated

To make the links more readable for you and your collaborators, you can pass a `link_text` argument:

```python
from prefect import flow
from prefect.artifacts import create_link_artifact


@flow
def my_flow():
    create_link_artifact(
        key="my-important-link",
        link="https://www.prefect.io/",
        link_text="Prefect",
    )


if __name__ == "__main__":
    my_flow()
```

In the above example, the `create_link_artifact` method is used within a flow to create a link artifact with a key of `my-important-link`.
The `link` parameter specifies the external resource to link to, and `link_text` specifies the text to display for the link.
Add an optional `description` for context.

### Create progress artifacts

Progress artifacts render dynamically on the flow run graph in the Prefect UI, indicating the progress of long-running tasks.

To create a progress artifact, use the `create_progress_artifact()` function. To update a progress artifact, use the `update_progress_artifact()` function.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/progress-artifact-example.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=3d0d6dae1173e61d198a5b3a22750d75" alt="Progress artifact example" data-og-width="2502" width="2502" data-og-height="1648" height="1648" data-path="v3/img/ui/progress-artifact-example.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/progress-artifact-example.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=55d85f889203f57deb5ad9f863f6365a 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/progress-artifact-example.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=9279bcfcf67d0e135d5b873058a59ce3 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/progress-artifact-example.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=20f5edba48cbd5bc58665f735d0e178d 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/progress-artifact-example.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=6f874ec129c7d67fc59c839270af3365 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/progress-artifact-example.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=afc7bb9d0fa1a3ef14d88a5546dfd8ae 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/progress-artifact-example.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=42229a79b276dc8c69102a184bdc5333 2500w" data-optimize="true" data-opv="2" />

```python
from time import sleep

from prefect import flow, task
from prefect.artifacts import (
    create_progress_artifact,
    update_progress_artifact,
)


def fetch_batch(i: int):
    # Simulate fetching a batch of data
    sleep(2)


@task
def fetch_in_batches():
    progress_artifact_id = create_progress_artifact(
        progress=0.0,
        description="Indicates the progress of fetching data in batches.",
    )
    for i in range(1, 11):
        fetch_batch(i)
        update_progress_artifact(artifact_id=progress_artifact_id, progress=i * 10)


@flow
def etl():
    fetch_in_batches()


if __name__ == "__main__":
    etl()
```

Progress artifacts are updated with the `update_progress_artifact()` function. Prefect updates a progress artifact in place, rather than versioning it.

### Create Markdown artifacts

To create a Markdown artifact, you can use the `create_markdown_artifact()` function.

To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a `key` argument to the `create_markdown_artifact()` function to track an artifact's history over time.

Without a `key`, the artifact is only visible in the Artifacts tab of the associated flow run or task run.

<Warning>
  **Don't indent Markdown**

  Don't indent Markdown in multi-line strings. Otherwise it will be interpreted incorrectly.
</Warning>

```python
from prefect import flow, task
from prefect.artifacts import create_markdown_artifact


@task
def markdown_task():
    na_revenue = 500000
    markdown_report = f"""# Sales Report

## Summary

In the past quarter, our company saw a significant increase in sales, with a total revenue of $1,000,000. 
This represents a 20% increase over the same period last year.

## Sales by Region

| Region        | Revenue |
|:--------------|-------:|
| North America | ${na_revenue:,} |
| Europe        | $250,000 |
| Asia          | $150,000 |
| South America | $75,000 |
| Africa        | $25,000 |

## Top Products

1. Product A - $300,000 in revenue
2. Product B - $200,000 in revenue
3. Product C - $150,000 in revenue

## Conclusion

Overall, these results are very encouraging and demonstrate the success of our sales team in increasing revenue 
across all regions. However, we still have room for improvement and should focus on further increasing sales in 
the coming quarter.
"""
    create_markdown_artifact(
        key="gtm-report",
        markdown=markdown_report,
        description="Quarterly Sales Report",
    )


@flow()
def my_flow():
    markdown_task()
    

if __name__ == "__main__":
    my_flow()
```

After running the above flow, you should see your "gtm-report" artifact in the Artifacts page of the UI.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=0daffdebede0bcf508172cd503fbe873" alt="Markdown sales report screenshot" data-og-width="1315" width="1315" data-og-height="925" height="925" data-path="v3/img/ui/md-artifact-info.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=7ffc604ae8aa3a9a66668279de4d0f68 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=c70b80ab79d497c8695fd36c771eaba1 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=5a6d42ade2b53f07b526ababe155be5a 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=02adac85d69dc70712cfdf301f84e998 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=2323063e708dbc746c4cac3003a7b15d 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/md-artifact-info.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=52cf19724759481fca06264354276263 2500w" data-optimize="true" data-opv="2" />

You can view the associated flow run id or task run id, previous versions of the artifact, the rendered Markdown data, and the optional Markdown description.

### Create table artifacts

Create a table artifact by calling `create_table_artifact()`.

To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a `key` argument to the `create_table_artifact()` function to track an artifact's history over time.

Without a `key`, the artifact is only visible in the artifacts tab of the associated flow run or task run.

<Note>
  The `create_table_artifact()` function accepts a `table` argument. Pass this as a list of lists, a list of dictionaries, or a dictionary of lists.
</Note>

```python
from prefect.artifacts import create_table_artifact


def my_fn():
    highest_churn_possibility = [
       {'customer_id':'12345', 'name': 'John Smith', 'churn_probability': 0.85 }, 
       {'customer_id':'56789', 'name': 'Jane Jones', 'churn_probability': 0.65 } 
    ]

    create_table_artifact(
        key="personalized-reachout",
        table=highest_churn_possibility,
        description= "# Marvin, please reach out to these customers today!"
    )


if __name__ == "__main__":
    my_fn()
```

<img src="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/table-artifact-info.png?fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=8da47c36540b4b3ae89b8851bf008e9a" alt="Table artifact with customer info" data-og-width="1331" width="1331" data-og-height="630" height="630" data-path="v3/img/ui/table-artifact-info.png" srcset="https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/table-artifact-info.png?w=280&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=34be10093131e7ffcc60cd120109c0f0 280w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/table-artifact-info.png?w=560&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=1e8edba8e986e6dbeeade0f4313dc63e 560w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/table-artifact-info.png?w=840&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=e0e32f8e1016377771f728ab60d2860a 840w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/table-artifact-info.png?w=1100&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=afc066d4b78e1889fd20bf1eef928c35 1100w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/table-artifact-info.png?w=1650&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=6d2a0aec05e93f53bd9c29ad8d0609e1 1650w, https://mintcdn.com/prefect-bd373955/rT_XiX8cZI7Bzt5c/v3/img/ui/table-artifact-info.png?w=2500&fit=max&auto=format&n=rT_XiX8cZI7Bzt5c&q=85&s=a5aa3f413ed79b406d88a7094e83a076 2500w" data-optimize="true" data-opv="2" />

### Create image artifacts

Image artifacts render publicly available images in the Prefect UI. To create an image artifact, use the `create_image_artifact()` function.

<img src="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/image-artifact-example.png?fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=d84414a3e83d817e77dfde0c37992e39" alt="Image artifact example" data-og-width="2497" width="2497" data-og-height="1646" height="1646" data-path="v3/img/ui/image-artifact-example.png" srcset="https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/image-artifact-example.png?w=280&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=1bfdd656b5ba8f8989d0443b693e9cfd 280w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/image-artifact-example.png?w=560&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=f1d6fdd93cd9d563ae167828d240ad91 560w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/image-artifact-example.png?w=840&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=dda4df70d2515e8a6443d48505f7d88f 840w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/image-artifact-example.png?w=1100&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=7ab19ec44fcb632ee84b95b5f62605d9 1100w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/image-artifact-example.png?w=1650&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=05a523f3d59fd3b5945989d8e63b2e2d 1650w, https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/image-artifact-example.png?w=2500&fit=max&auto=format&n=dwD6EJObIjtIzwSC&q=85&s=737f6032a08c336bbe73d445c50d89c1 2500w" data-optimize="true" data-opv="2" />

```python
from prefect import flow, task
from prefect.artifacts import (
    create_image_artifact,
)


@task
def create_image():
    # Do something to create an image and upload to a url
    image_url = "https://media3.giphy.com/media/v1.Y2lkPTc5MGI3NjExZmQydzBjOHQ2M3BhdWJ4M3V1MGtoZGxuNmloeGh6b2dvaHhpaHg0eSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/3KC2jD2QcBOSc/giphy.gif"
    create_image_artifact(image_url=image_url, description="A gif.", key="gif")
    return image_url


@flow
def my_flow():
    return create_image()


if __name__ == "__main__":
    image_url = my_flow()
    print(f"Image URL: {image_url}")
```

To create an artifact that links to a private image, use the `create_link_artifact()` function instead.

### Reading artifacts

In the Prefect UI, you can view all of the latest versions of your artifacts and click into a specific artifact to see its lineage over time.
Additionally, you can inspect all versions of an artifact with a given key from the CLI by running:

```bash
prefect artifact inspect <my_key>
```

or view all artifacts by running:

```bash
prefect artifact ls
```

You can also use the [Prefect REST API](https://app.prefect.cloud/api/docs#tag/Artifacts/operation/read_artifacts_api_accounts__account_id__workspaces__workspace_id__artifacts_filter_post)
to programmatically filter your results.

### Fetching artifacts

In Python code, you can retrieve an existing artifact with the `Artifact.get` class method:

```python
from prefect.artifacts import Artifact


my_retrieved_artifact = Artifact.get("my_artifact_key")
```

### Delete artifacts

Delete an artifact in the CLI by providing a key or id:

```bash
prefect artifact delete <my_key>
```

```bash
prefect artifact delete --id <my_id>
```


# How to use assets to track workflow outputs
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/assets



<span class="badge cloud" />

Assets in Prefect represent important outputs (such as data) that are produced by your tasks and flows. Assets can reference virtually any output such as files, dataframes, tables, dashboards, or ML models. By using the `@materialize` decorator, you can track when your workflows create, update, or reference these objects.

## Basic asset materialization

Use the `@materialize` decorator to mark functions that create or update assets. This decorator wraps your function similar to `@task` but specifically tracks asset creation:

```python
from prefect import flow
from prefect.assets import materialize

@materialize("s3://my-bucket/processed-data.csv")
def process_data(data: dict) -> dict:
    # Your data processing logic here
    # save_to_s3(data, "s3://my-bucket/processed-data.csv")
    return data

@flow
def data_pipeline(data: dict):
    process_data(data)
```

Asset keys must be valid URIs that uniquely identify your workflow outputs. Assets are automatically grouped by type (specified by the URI prefix) and can be nested based on the URI path structure. For example, `s3://` assets are grouped separately from `postgres://` assets, and nested paths like `s3://bucket/team-a/data.csv` and `s3://bucket/team-b/data.csv` create hierarchical organization.

<Note>
  **`@materialize` wraps `@task`**: the `@materialize` decorator accepts all keyword arguments and configuration that the `@task` decorator accepts and can be used as a drop-in replacement.
</Note>

## Asset dependencies

### Inferred from task graphs

Prefect automatically infers asset dependencies from your task graph. When materialized assets flow through your workflow, downstream materializations inherit these dependencies:

```python
from prefect import flow
from prefect.assets import materialize


@materialize("file://my-local-directory/raw-data.csv")
def extract_data() -> str:
    raw_data = "name,age\nchris,21"
    with open("raw-data.csv", "w") as f:
        f.write(raw_data)
    return raw_data


@materialize("s3://my-bucket/clean-data.csv")
def transform_data(raw_data):
    # saves raw_data to s3
    pass


@flow
def etl_pipeline():
    raw_data = extract_data()
    transform_data(raw_data)  # Automatically depends on raw-data.csv
```

Running this flow produces the following asset graph:

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-1.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=f94e8971f57299cd43e178177ec977e6" alt="Asset Graph in the UI" data-og-width="2168" width="2168" data-og-height="1050" height="1050" data-path="v3/img/guides/assets-1.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-1.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=3942dff6aebbc16b3003edd0f1157939 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-1.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=891215c14054dde3756f57a42ee0be4e 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-1.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=ff37d171b4ed22c84448b970efd2ce92 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-1.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=8e8831d3dee4e393723911d2de11af4e 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-1.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=b374943828b27175579a47e7f37b3930 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-1.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=347f9e4f85d98a235f6cb27833b3813f 2500w" data-optimize="true" data-opv="2" />

### External and cross-flow asset dependencies

Use `asset_deps` to reference assets that are external to your current workflow. This creates dependencies on assets that may be materialized by other flows, external systems, or manual processes:

```python
from prefect import flow
from prefect.assets import materialize


# Depends on asset from another Prefect flow
@materialize(
    "s3://my-bucket/downstream-data.csv",
    asset_deps=["s3://my-bucket/upstream-data.csv"]  # From different flow
)
def process_downstream_data():
    pass

# Depends on external system assets
@materialize(
    "s3://my-bucket/enriched-data.csv",
    asset_deps=[
        "postgres://db/users_table",      # External database
        "sftp://vendor/daily-feed.csv"    # External data feed
    ]
)
def enrich_user_data():
    pass

@flow
def analytics_pipeline():
    process_downstream_data()
    enrich_user_data()
```

Running this flow produces the following asset graph:

<img src="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-2.png?fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=c64f005627357c5ddaf1e46552291c71" alt="Asset Graph in the UI" data-og-width="1920" width="1920" data-og-height="1288" height="1288" data-path="v3/img/guides/assets-2.png" srcset="https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-2.png?w=280&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=c1c62e2c56fe4a48a43a0bb5cdc29a73 280w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-2.png?w=560&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=d2f64e0e1d585c5acec95dedf06b5c60 560w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-2.png?w=840&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=73ca041924db8b1c57a13db8212ebf31 840w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-2.png?w=1100&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=d56b80723f2088d45b13a863f0cc86b7 1100w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-2.png?w=1650&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=d110be8dcd989769d3264d544424dea4 1650w, https://mintcdn.com/prefect-bd373955/rm4-_dTLtkmSX6eG/v3/img/guides/assets-2.png?w=2500&fit=max&auto=format&n=rm4-_dTLtkmSX6eG&q=85&s=f78547f2d31b6c70e9c3efae4ed8d203 2500w" data-optimize="true" data-opv="2" />

This approach allows you to model your complete data ecosystem, tracking dependencies even when some assets are managed outside your current workflow or outside Prefect entirely.

## Multiple asset materialization

Materialize multiple related assets in a single function when they share the same upstream dependencies:

```python
from prefect.assets import materialize


@materialize(
    "s3://my-bucket/summary.csv",
    "s3://my-bucket/details.csv"
)
def generate_reports():
    data = fetch_source_data()
    create_summary_report(data)
    create_detailed_report(data)
```

## Dynamic asset materialization

Use [the `with_options` pattern](/v3/api-ref/python/prefect-tasks#with-options) to dynamically change asset keys and dependencies at runtime. This is useful when you need to parameterize asset paths based on flow inputs, dates, or other runtime conditions:

```python
from prefect import flow
from prefect.assets import materialize
from datetime import datetime


@materialize("s3://my-bucket/daily-report.csv")
def generate_daily_report(date: str):
    # Process and save daily report
    pass


@flow
def dynamic_reporting_pipeline():
    base_task = generate_daily_report
    today = datetime.now().strftime("%Y-%m-%d")
    
    # Dynamically set asset key based on date
    daily_task = base_task.with_options(
        assets=[f"s3://my-bucket/reports/{today}/daily-report.csv"]
    )
    
    daily_task(today)
```

You can also dynamically modify asset dependencies alongside the materialized assets:

```python
from prefect import flow
from prefect.assets import materialize


@materialize(
    "s3://my-bucket/processed-data.csv",
    asset_deps=["s3://my-bucket/raw-data.csv"]
)
def process_data(environment: str):
    pass


@flow
def environment_specific_pipeline(env: str):
    base_task = process_data
    
    # Use different assets based on environment
    env_task = base_task.with_options(
        assets=[f"s3://my-bucket/{env}/processed-data.csv"],
        asset_deps=[f"s3://my-bucket/{env}/raw-data.csv"]
    )
    
    env_task(env)
```

This pattern enables you to reuse the same processing logic across different environments, time periods, or data partitions while maintaining proper asset lineage tracking.

## Further Reading

* [How to customize asset metadata](/v3/advanced/assets)
* [Learn about asset health and asset events](/v3/concepts/assets)


# How to cache workflow step outputs
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/cache-workflow-steps



The simplest way to cache the results of tasks within in a flow is to set `persist_result=True` on a task definition.

```python
from prefect import task, flow

@task(persist_result=True)
def add_one(x: int):
    return x + 1

@flow
def my_flow():
    add_one(1) # will not be cached
    add_one(1) # will be cached
    add_one(2) # will not be cached

if __name__ == "__main__":
    my_flow()
```

<Accordion title="Output">
  ```python
  16:28:51.230 | INFO    | Flow run 'outgoing-cicada' - Beginning flow run 'outgoing-cicada' for flow 'my-flow'
  16:28:51.257 | INFO    | Task run 'add_one-d85' - Finished in state Completed()
  16:28:51.276 | INFO    | Task run 'add_one-eff' - Finished in state Cached(type=COMPLETED)
  16:28:51.294 | INFO    | Task run 'add_one-d16' - Finished in state Completed()
  16:28:51.311 | INFO    | Flow run 'outgoing-cicada' - Finished in state Completed()
  ```
</Accordion>

This will implicitly use the `DEFAULT` cache policy, which is a composite cache policy defined as:

```python
DEFAULT = INPUTS + TASK_SOURCE + RUN_ID
```

This means subsequent calls of a task with identical inputs from within the same parent run will return cached results without executing the body of the function.

<Note>
  The `TASK_SOURCE` component of the `DEFAULT` cache policy helps avoid naming collisions between similar tasks that should not share a cache.
</Note>

### Cache based on inputs

To cache the result of a task based only on task inputs, set `cache_policy=INPUTS` in the task decorator:

```python
from prefect import task
from prefect.cache_policies import INPUTS

import time


@task(cache_policy=INPUTS)
def my_stateful_task(x: int):
    print('sleeping')
    time.sleep(10)
    return x + 1

my_stateful_task(x=1) # sleeps
my_stateful_task(x=1) # does not sleep
my_stateful_task(x=2) # sleeps
```

The above task will sleep the first time it is called with `x=1`, but will not sleep for any subsequent calls with the same input.

Prefect ships with several [cache policies](/v3/concepts/caching#cache-policies) that can be used to customize caching behavior.

### Cache based on a subset of inputs

To cache based on a subset of inputs, you can subtract kwargs from the `INPUTS` cache policy.

```python
from prefect import task
from prefect.cache_policies import INPUTS

import time


@task(cache_policy=INPUTS - 'debug')
def my_stateful_task(x: int, debug: bool = False):
    print('sleeping')
    time.sleep(10)
    return x + 1

my_stateful_task(x=1) # sleeps
my_stateful_task(x=1, debug=True) # does not sleep
my_stateful_task(x=1, debug=False) # does not sleep
```

### Cache with an expiration

To cache with an expiration, set the `cache_expiration` parameter on the task decorator.

```python
from prefect import task
from prefect.cache_policies import INPUTS

import time
from datetime import timedelta


@task(cache_policy=INPUTS, cache_expiration=timedelta(seconds=10))
def my_stateful_task(x: int):
    print('sleeping')
    time.sleep(10)
    return x + 1

my_stateful_task(x=1) # sleeps
my_stateful_task(x=1) # does not sleep
# ... 10 seconds pass ...
my_stateful_task(x=1) # sleeps again
```

### Ignore the cache

To ignore the cache regardless of the cache policy, set the `refresh_cache` parameter on the task decorator.

```python
import random

from prefect import task
from prefect.cache_policies import TASK_SOURCE


@task(cache_policy=TASK_SOURCE, refresh_cache=True)
def never_caching_task():
    return random.random()
```

To refresh the cache for all tasks, use the `PREFECT_TASKS_REFRESH_CACHE` setting.
Setting `PREFECT_TASKS_REFRESH_CACHE=true` changes the default behavior of all tasks to refresh.

If you have tasks that should not refresh when this setting is enabled, set `refresh_cache` to `False`. These tasks will never write to the cache. If a cache key exists it will be read, not updated.
If a cache key does *not* exist yet, these tasks can still write to the cache.

```python
import random

from prefect import task
from prefect.cache_policies import TASK_SOURCE


@task(cache_policy=TASK_SOURCE, refresh_cache=False)
def caching_task():
    return random.random()
```

### Cache on multiple criteria

Cache policies can be combined using the `+` operator.

```python
from prefect import task
from prefect.cache_policies import INPUTS, TASK_SOURCE

@task(cache_policy=INPUTS + TASK_SOURCE)
def my_task(x: int):
    return x + 1
```

The above task will use a cached result as long as the same inputs and task source are used.

### Cache in a distributed environment

By default Prefect stores results locally in `~/.prefect/storage/`. To share the cache across tasks running on different machines, provide a storage block to the `result_storage` parameter on the task decorator.

Here's an example with of a task that uses an S3 bucket to store cache records:

```python
from prefect import task
from prefect.cache_policies import INPUTS

from prefect_aws import AwsCredentials, S3Bucket

s3_bucket = S3Bucket(
    credentials=AwsCredentials(
        aws_access_key_id="my-access-key-id",
        aws_secret_access_key="my-secret-access-key",
    ),
    bucket_name="my-bucket",
)
# save the block to ensure it is available across machines
s3_bucket.save("my-cache-bucket")

@task(cache_policy=INPUTS, result_storage=s3_bucket)
def my_cached_task(x: int):
    return x + 42
```

<Note>
  When using a storage block from a Prefect integration package, the package the storage block is imported from must be installed in all environments where the task will run.

  For example, the `prefect_aws` package must be installed to use the `S3Bucket` storage block.
</Note>

### Further reading

For more advanced caching examples, see the [advanced caching how-to guide](/v3/advanced/caching).

For more information on Prefect's caching system, see the [caching concepts page](/v3/concepts/caching).


# How to customize a workflow's metadata
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/custom-metadata



### Customize a workflow's name

Give your workflow a name with the `name` parameter:

```python
from prefect import flow


@flow(name="My Flow")
def my_workflow() -> str:
    return "Hello, world!"
```

If you don't provide a name, Prefect uses the flow function name.

### Customize a workflow's description

Give your workflow a description with the `description` parameter:

```python
from prefect import flow


@flow(name="My Flow", description="My flow with a name and description")
def my_workflow() -> str:
    return "Hello, world!"
```

If no description is provided, a flow function's docstring is used as the description.

### Customize run names

Give a custom name to each flow run for a flow with the `flow_run_name` parameter:

```python
import datetime
from prefect import flow


@flow(flow_run_name="hello-{name}-on-{date:%A}")
def my_workflow(name: str, date: datetime.datetime):
    return f"I said hello to {name} on {date:%A}!"
```

Inputs to the flow function are available as variables in the `flow_run_name` template string.

You can also provide a `flow_run_name` as a function that returns a string:

```python
import datetime
from prefect import flow


def generate_flow_run_name():
    date = datetime.datetime.now(datetime.timezone.utc)
    return f"{date:%A}-is-a-nice-day"


@flow(flow_run_name=generate_flow_run_name)
def my_workflow(name: str):
    return f"Hello, {name}!"
```

<Info>
  **Custom flow run names are applied at runtime**

  When a flow run is created via a schedule or the API, the `flow_run_name` defined on the flow is not immediately applied. The name is updated when the flow begins running.
</Info>


# How to apply global concurrency and rate limits
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/global-concurrency-limits

Learn how to control concurrency and apply rate limits using Prefect's provided utilities.

export const API = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect API</a>.</p>;

export const TF = ({name, href}) => <p>You can manage {name} with the <a href={href}>Terraform provider for Prefect</a>.</p>;

export const global_concurrency = {
  cli: "https://docs.prefect.io/v3/api-ref/cli/global-concurrency-limit",
  api: "https://app.prefect.cloud/api/docs#tag/Concurrency-Limits-V2",
  tf: "https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/global_concurrency_limit"
};

export const CLI = ({name, href}) => <p>You can manage {name} with the <a href={href}>Prefect CLI</a>.</p>;

**Global concurrency limits** allow you to manage execution efficiently, controlling how many tasks, flows, or other operations can run simultaneously.
They are ideal for optimizing resource usage, preventing bottlenecks, and customizing task execution.

<Tip>
  **Clarification on use of the term 'tasks'**

  In the context of global concurrency and rate limits, "tasks" doesn't specifically refer to Prefect tasks, but to concurrent units of work in
  general—such as those managed by an event loop or `TaskGroup` in asynchronous programming. These general "tasks" could include Prefect
  tasks when they are part of an asynchronous execution environment.
</Tip>

**Rate Limits** ensure system stability by governing the frequency of requests or operations. They are suitable for preventing overuse, ensuring
fairness, and handling errors gracefully.

When selecting between global concurrency and rate limits, consider your primary goal:

* Choose global concurrency limits for **resource optimization** and **task management**.

* Choose rate limits to **maintain system stability** and **fair access** to services.

The core difference between a rate limit and a concurrency limit is the way slots are released. With a rate limit, slots are released at a
controlled rate determined by `slot_decay_per_second`. With a concurrency limit, slots are released when the concurrency manager exits.

<Note>
  **Concurrency slots have timed leases**

  Each time a concurrency slot is occupied, a countdown begins on the server.
  The length of this countdown is known as the concurrency slot's **lease duration**.
  While a concurrency slot is occupied, the Prefect client will periodically notify the server that the slot is still in use and restart the countdown.
  If the countdown concludes before the lease has been renewed, the concurrency slot is released.

  Lease expiration typically occurs when a process occupying a slot exits unexpectedly and is unable to notify the server that the slot should be released.
  This system exists to ensure that all concurrency slots are eventually released to prevent concurrency-related deadlocks.

  The default lease duration is 5 minutes, but custom durations with a minimum of 1 minute can be supplied to the concurrency context manager.
</Note>

## Manage global concurrency and rate limits

You can create, read, edit, and delete concurrency limits through the Prefect UI or Python SDK.

When creating a concurrency limit, you can specify the following parameters:

* **Name**: The name of the concurrency limit. This name is also how you'll reference the concurrency limit in your code. Special characters,
  such as `/`, `%`, `&`, `>`, `<`, are not allowed.
* **Concurrency Limit**: The maximum number of slots that can be occupied on this concurrency limit.
* **Slot Decay Per Second**: Controls the rate at which slots are released when the concurrency limit is used as a rate limit. You must
  configure this value when using the `rate_limit` function.
* **Active**: Whether or not the concurrency limit is in an active state.

### Active vs. inactive limits

Global concurrency limits can be in an `active` or `inactive` state:

* **Active**: In this state, slots can be occupied, and code execution is blocked when slots are unable to be acquired.
* **Inactive**: In this state, slots are not occupied, and code execution is not blocked. Concurrency enforcement occurs only when
  you activate the limit.

### Slot decay

To implement rate limiting, you can configure "slot decay", which determines how rapidly used slots are freed up for new tasks.

When you set up a concurrency limit with slot decay:

1. Each time a slot is occupied, it becomes unavailable for other tasks to use.
2. The slot eventually becomes available again over time, based on the slot decay rate (with `slot_decay_per_second`).
3. This creates a "rate limiting" effect, limiting how often slots can be used.

To configure slot decay, set the `slot_decay_per_second` parameter when creating or updating a concurrency limit. This value determines how quickly slots refresh:

* A higher value (for example, 5.0) means slots refresh quickly. Tasks can run more frequently, but with short pauses between them.
* A lower value (for example, 0.1) means slots refresh slowly. Tasks run less frequently, with longer pauses between them.

For example:

* With a decay rate of 5.0, you could run a task roughly every 0.2 seconds.
* With a decay rate of 0.1, you'd wait about 10 seconds between task runs.

Choose a decay rate that balances your required frequency of task execution with the acceptable limit of overall system load. This allows you to fine-tune your workflow's performance and resource usage.

### Through the UI

You can manage global concurrency limits in the **Concurrency** section of the Prefect UI.

<img src="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/gcl-1.png?fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=2730ce50c5061894115a300fe25c53d1" alt="Concurrency limits in the UI" data-og-width="807" width="807" data-og-height="428" height="428" data-path="images/gcl-1.png" srcset="https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/gcl-1.png?w=280&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=478e69c2aaa98038fc92d80567175a61 280w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/gcl-1.png?w=560&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=3f518b8a3313decdb662ef6074753ac4 560w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/gcl-1.png?w=840&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=eb7e32f970b8365970e2c1a20e5a6626 840w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/gcl-1.png?w=1100&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=88b65dabe19ff407164e134b474a2142 1100w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/gcl-1.png?w=1650&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=ede57dac36c3da806590bbeef789ccde 1650w, https://mintcdn.com/prefect-bd373955/61rCXJ5a7pFAZAcb/images/gcl-1.png?w=2500&fit=max&auto=format&n=61rCXJ5a7pFAZAcb&q=85&s=878f6f7d5cca25a250e275e52cbf46a8 2500w" data-optimize="true" data-opv="2" />

### Through the CLI

<CLI name="global concurrency" href={global_concurrency.cli} />

To create a new concurrency limit, use the `prefect gcl create` command. You must specify a `--limit` argument, and can optionally specify a
`--slot-decay-per-second` and `--disable` argument.

```bash
prefect gcl create my-concurrency-limit --limit 5 --slot-decay-per-second 1.0
```

Inspect the details of a concurrency limit using the `prefect gcl inspect` command:

```bash
prefect gcl inspect my-concurrency-limit
```

To update a concurrency limit, use the `prefect gcl update` command. You can update the `--limit`, `--slot-decay-per-second`, `--enable`,
and `--disable` arguments:

```bash
prefect gcl update my-concurrency-limit --limit 10
```

```bash
prefect gcl update my-concurrency-limit --disable
```

To delete a concurrency limit, use the `prefect gcl delete` command:

```bash
prefect gcl delete my-concurrency-limit
Are you sure you want to delete global concurrency limit 'my-concurrency-limit'? [y/N]: y
Deleted global concurrency limit with name 'my-concurrency-limit'.
```

See all available commands and options by running `prefect gcl --help`.

### Through Terraform

<TF name="global concurrency" href={global_concurrency.tf} />

### Through the API

<API name="global concurrency" href={global_concurrency.api} />

## Using the `concurrency` context manager

The `concurrency`context manager allows control over the maximum number of concurrent operations. Select either the synchronous (`sync`)
or asynchronous (`async`) version, depending on your use case. Here's how to use it:

<Tip>
  **Concurrency limits are not implicitly created**

  When using the `concurrency` context manager, if the provided `names` of the concurrency limits don't already exist, then no limiting is enforced and a warning will be logged.
  For stricter control, use `strict=True` to instead raise an error if no matching limits exist to block execution of the task.
</Tip>

**Sync**

```python
from prefect import flow, task
from prefect.concurrency.sync import concurrency
from prefect.futures import wait


@task
def process_data(x, y):
    with concurrency("database", occupy=1):
        return x + y


@flow
def my_flow():
    futures = []
    for x, y in [(1, 2), (2, 3), (3, 4), (4, 5)]:
        futures.append(process_data.submit(x, y))

    wait(futures)


if __name__ == "__main__":
    my_flow()
```

**Async**

```python
import asyncio
from prefect import flow, task
from prefect.concurrency.asyncio import concurrency
from prefect.futures import wait


@task
async def process_data(x, y):
    async with concurrency("database", occupy=1):
        return x + y


@flow
def my_flow():
    futures = []
    for x, y in [(1, 2), (2, 3), (3, 4), (4, 5)]:
        futures.append(process_data.submit(x, y))

    wait(futures)


if __name__ == "__main__":
    asyncio.run(my_flow())
```

1. The code imports the necessary modules and the concurrency context manager. Use the `prefect.concurrency.sync` module for sync usage
   and the `prefect.concurrency.asyncio` module for async usage.
2. It defines a `process_data` task, taking `x` and `y` as input arguments. Inside this task, the concurrency context manager controls
   concurrency, using the `database` concurrency limit and occupying one slot. If another task attempts to run with the same limit and no
   slots are available, that task is blocked until a slot becomes available.
3. A flow named `my_flow` is defined. Within this flow, it iterates through a list of tuples, each containing pairs of x and y values.
   For each pair, the `process_data` task is submitted with the corresponding x and y values for processing.

## Using `rate_limit`

The Rate Limit feature provides control over the frequency of requests or operations, ensuring responsible usage and system stability.
Depending on your requirements, you can use `rate_limit` to govern both synchronous (sync) and asynchronous (async) operations.
Here's how to make the most of it:

<Tip>
  **Slot decay**
  When using the `rate_limit` function, the concurrency limit must have a slot decay configured.
</Tip>

**Sync**

```python
from prefect import flow, task
from prefect.concurrency.sync import rate_limit


@task
def make_http_request():
    rate_limit("rate-limited-api")
    print("Making an HTTP request...")


@flow
def my_flow():
    for _ in range(10):
        make_http_request.submit()


if __name__ == "__main__":
    my_flow()
```

**Async**

```python
import asyncio

from prefect import flow, task
from prefect.concurrency.asyncio import rate_limit


@task
async def make_http_request():
    await rate_limit("rate-limited-api")
    print("Making an HTTP request...")


@flow
def my_flow():
    for _ in range(10):
        make_http_request.submit()


if __name__ == "__main__":
    asyncio.run(my_flow())
```

1. The code imports the necessary modules and the `rate_limit` function. Use the `prefect.concurrency.sync` module for sync usage and the
   `prefect.concurrency.asyncio` module for async usage.
2. It defines a `make_http_request` task. Inside this task, the `rate_limit` function ensures that the requests are made at a controlled pace.
3. A flow named `my_flow` is defined. Within this flow the `make_http_request` task is submitted 10 times.

## Use `concurrency` and `rate_limit` outside of a flow

Use`concurrency` and `rate_limit` outside of a flow to control concurrency and rate limits for any operation.

```python
import asyncio

from prefect.concurrency.asyncio import rate_limit


async def main():
    for _ in range(10):
        await rate_limit("rate-limited-api")
        print("Making an HTTP request...")



if __name__ == "__main__":
    asyncio.run(main())
```

## Use cases

### Throttling task submission

Throttling task submission helps avoid overloading resources, complying with external rate limits, or ensuring a steady, controlled flow of work.

In this scenario the `rate_limit` function throttles the submission of tasks. The rate limit acts as a bottleneck, ensuring
that tasks are submitted at a controlled rate, governed by the `slot_decay_per_second` setting on the associated concurrency limit.

```python
from prefect import flow, task
from prefect.concurrency.sync import rate_limit


@task
def my_task(i):
    return i


@flow
def my_flow():
    for _ in range(100):
        rate_limit("slow-my-flow", occupy=1)
        my_task.submit(1)


if __name__ == "__main__":
    my_flow()
```

### Manage database connections

Manage the maximum number of concurrent database connections to avoid exhausting database resources.

This scenario uses a concurrency limit named `database`. It has a maximum concurrency limit that matches the maximum number
of database connections. The `concurrency` context manager controls the number of database connections
allowed at any one time.

```python
from prefect import flow, task, concurrency
from myproject import db

@task
def database_query(query):
    # Here we request a single slot on the 'database' concurrency limit. This
    # will block in the case that all of the database connections are in use
    # ensuring that we never exceed the maximum number of database connections.
    with concurrency("database", occupy=1):
        result = db.execute(query)
        return result

@flow
def my_flow():
    queries = ["SELECT * FROM table1", "SELECT * FROM table2", "SELECT * FROM table3"]

    for query in queries:
        database_query.submit(query)

if __name__ == "__main__":
    my_flow()
```

### Parallel data processing

Limit the maximum number of parallel processing tasks.

This scenario limits the number of `process_data` tasks to five at any one time. The `concurrency`
context manager requests five slots on the `data-processing` concurrency limit. This blocks until five slots are free and then
submits five more tasks, ensuring that the maximum number of parallel processing tasks is never exceeded.

```python
import asyncio
from prefect.concurrency.sync import concurrency


async def process_data(data):
    print(f"Processing: {data}")
    await asyncio.sleep(1)
    return f"Processed: {data}"


async def main():
    data_items = list(range(100))
    processed_data = []

    while data_items:
        with concurrency("data-processing", occupy=5):
            chunk = [data_items.pop() for _ in range(5)]
            processed_data += await asyncio.gather(
                *[process_data(item) for item in chunk]
            )

    print(processed_data)


if __name__ == "__main__":
    asyncio.run(main())
```

## Other ways to limit concurrency

In addition to global concurrency limits, Prefect provides several other ways to limit concurrency for fine-grained control.

Unlike global concurrency limits, which are a more general way to control concurrency for any Python-based operation, the following concurrency limit options are specific to Prefect objects:

* [Work pool flow run concurrency limits](/v3/concepts/work-pools#manage-concurrency)
* [Work queue flow run concurrency limits](/v3/concepts/work-pools#queue-concurrency-limits)
* [Deployment flow run concurrency limits](/v3/concepts/deployments#concurrency-limiting)
* [Task run concurrency limits](/v3/how-to-guides/workflows/tag-based-concurrency-limits)


# How to pass inputs to a workflow
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/pass-inputs



### Define workflow inputs

Define the inputs to a workflow by adding parameters to the function definition.

```python
from prefect import flow


@flow
def my_workflow(name: str = "World"):
    return f"Hello, {name}!"
```

Pass arguments to the function call to provide inputs to the workflow.

{/* pmd-metadata: continuation */}

```python
my_workflow(name="Marvin")
```

### Validate inputs

By default, Prefect will validate the types of inputs to your workflow.

{/* pmd-metadata: notest */}

```python
from prefect import flow


@flow
def my_workflow(name: str = "World"):
    return f"Hello, {name}!"

my_workflow(name=1) # This will fail with a type validation error
```

To turn off type validation, set the `validate_parameters` parameter to `False`:

```python
from prefect import flow


@flow(validate_parameters=False)
def my_workflow(name: str = "World"):
    return f"Hello, {name}!"

my_workflow(name=1)
```

If you use `pydantic`, parameters typed with a `BaseModel` subclass will be coerced to the appropriate types and validated.

{/* pmd-metadata: notest */}

```python
from prefect import flow
from pydantic import BaseModel


class Model(BaseModel):
    a: int
    b: str


@flow
def flow_that_validates_parameters(model: Model): ...

flow_that_validates_parameters(
    model={"a": "WRONG", "b": "fine"}
)
```


# How to automatically rerun your workflow when it fails
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/retries



### Set the number of retries

To rerun your workflow when an exception is raised, set the `retries` parameter to an integer.

```python
from prefect import flow


@flow(retries=3)
def troublesome_workflow():
    raise Exception("oopsie daisy")
```

### Wait between retries

To add a wait between retries, pass a value to the `retry_delay_seconds` parameter.

```python
from prefect import flow


@flow(retries=3, retry_delay_seconds=2.7182)
def troublesome_workflow():
    raise Exception("oopsie daisy")
```

### Retry parts of a workflow

You can configure retries for individual tasks in a workflow to limit the scope of a retry.

```python
import random

import httpx
from prefect import flow, task


@task
def consistent_task() -> dict:
    print("I won't rerun even if the task after me fails")


@task(retries=4, retry_delay_seconds=5)
def mercurial_task() -> dict:
    # Will fail half of the time
    url = f"https://httpbin.org/status/{random.choice([200, 500])}"

    response = httpx.get(url)
    response.raise_for_status()
    

@flow
def my_workflow():
    consistent_task()
    mercurial_task()
```

### Retry with configurable delay

A task's retry delays can also be defined as a list of integers for different delays between retries.

```python
from prefect import task


@task(retries=4, retry_delay_seconds=[1, 2, 4, 8])
def melancholic_task():
    raise Exception("We used to see each other so much more often")
```

You can also use the `exponential_backoff` utility to generate a list of retry delays that correspond to an exponential backoff retry strategy.

```python
from prefect import task
from prefect.tasks import exponential_backoff


@task(retries=4, retry_delay_seconds=exponential_backoff(backoff_factor=2))
def melancholic_task():
    raise Exception("We used to see each other so much more often")
```

### Retry with a custom condition

Whether or not a task should be retried can be determined dynamically by passing a callable to the `retry_condition_fn` parameter.

```python
import httpx
from prefect import flow, task


def retry_handler(task, task_run, state) -> bool:
    """
    Retry handler that skips retries if the HTTP status code is 401 or 404.
    """
    try:
        state.result()
    except httpx.HTTPStatusError as exc:
        do_not_retry_on_these_codes = [401, 404]
        return exc.response.status_code not in do_not_retry_on_these_codes
    except httpx.ConnectError:
        return False
    except:
        return True


@task(retries=1, retry_condition_fn=retry_handler)
def api_call_task(url):
    response = httpx.get(url)
    response.raise_for_status()
    return response.json()


@flow
def my_workflow(url):
    api_call_task(url=url)
```

If a callable passed to `retry_condition_fn` returns `True`, the task will be retried. Otherwise, the task will exit with an exception.

### Add jitter to retry delays

To add a random amount of time to retry delays, pass a value to the `retry_jitter_factor` parameter.

```python
import time

from prefect import task
from prefect.tasks import exponential_backoff

last_run_time = time.time()

@task(
    retries=3,
    retry_delay_seconds=exponential_backoff(backoff_factor=5),
    retry_jitter_factor=3,
)
def some_task_with_exponential_backoff_retries():
    global last_run_time
    print(f"Time between retries: {time.time() - last_run_time}")
    if time.time() - last_run_time < 10:
        last_run_time = time.time()
        raise Exception("I could fail some more")
    return "That's enough failure"
```

Adding jitter to the retry delays avoids multiple tasks introducing load to external systems by failing and retrying at the exact same cadence.

### Configure task retry behavior globally

You can set the default retries and retry delays for all tasks via Prefect's settings.
The default values can be overridden on a per-task basis via the `retries` and `retry_delay_seconds` parameters.

```
prefect config set PREFECT_TASK_DEFAULT_RETRIES=2
prefect config set PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS="1,10,100"
```


# How to run tasks background tasks
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/run-background-tasks



### Start a background task worker

To start a worker to run background tasks for a single function, define a task and call `.serve()` on it.

{/* pmd-metadata: notest */}

```python
from prefect import task

@task(log_prints=True)
def add(a: int, b: int):
    print(f"{a} + {b} = {a + b}")

add.serve()
```

### Trigger a background task

To trigger a background task, call `.delay()` on the same task in a different terminal.

{/* pmd-metadata: notest */}

```python
add.delay(1, 2)
```

<Tip>
  `.delay()` has the same signature as the `@task` decorated function.
</Tip>

### Start a worker to run background tasks for multiple functions

To start a worker to run background tasks for multiple functions, call `serve()` with the tasks you want to run.

{/* pmd-metadata: notest */}

```python
from prefect import task
from prefect.task_worker import serve

@task(log_prints=True)
def add(a: int, b: int):
    print(f"{a} + {b} = {a + b}")

@task(log_prints=True)
def multiply(a: int, b: int):
    print(f"{a} * {b} = {a * b}")

# Both these invocations will run once the worker is started
add.delay(1, 2)
multiply.delay(1, 4)

serve(add, multiply) # start a task worker listening for both `add` and `multiply`
```

### Submit multiple background tasks

To submit multiple background tasks, call `.map()` on the task with `deferred=True`.

{/* pmd-metadata: notest */}

```python
from prefect import task

@task(log_prints=True)
def add(a: int, b: int):
    print(f"{a} + {b} = {a + b}")

A = [1, 2, 3]
B = [4, 5, 6]

add.map(A, B, deferred=True)

add.serve()
```

<Tip>
  `.map()` accepts `Iterable[P.args]`, `Iterable[P.kwargs]` or `unmapped` inputs.
</Tip>

If you want to keep one argument mapped and the other unmapped, you can do so by passing `unmapped` to the mapped argument.

{/* pmd-metadata: notest */}

```python
from prefect import task, unmapped

@task(log_prints=True)
def add(a: int, b: int):
    print(f"{a} + {b} = {a + b}")

A = [1, 2, 3]

add.map(A, unmapped(4), deferred=True)

add.serve()
```

### Further reading

* [How to deploy a web application with Prefect background tasks](/v3/advanced/background-tasks)
* [Prefect Background Task Examples](https://github.com/PrefectHQ/prefect-background-task-examples) repository for reference implementations of applications leveraging background tasks.


# How to run work concurrently
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/run-work-concurrently



## Calling tasks directly

Tasks can be called directly (i.e. using [`__call__`](https://docs.python.org/3/reference/datamodel.html#object.__call__)), but they **will not** run concurrently.

```python
import time

from prefect import task

@task
def stop_at_floor(floor: int):
    print(f"elevator moving to floor {floor}")
    time.sleep(floor)
    print(f"elevator stops on floor {floor}")

stop_at_floor(0.1) # blocks for 0.1 seconds
stop_at_floor(0.2) # blocks for 0.2 seconds
stop_at_floor(0.3) # blocks for 0.3 seconds
```

When you call a task directly, it will block the main thread until the task completes.

Continue reading to learn how to run tasks concurrently via [task runners](/v3/concepts/task-runners).

## Using `.submit`

Tasks in your workflows can be run concurrently using the `.submit()` method.

```python
import time

from prefect import flow, task
from prefect.futures import wait

@task
def stop_at_floor(floor: int):
    print(f"elevator moving to floor {floor}")
    time.sleep(floor)
    print(f"elevator stops on floor {floor}")

@flow
def elevator():
    floors = []
    for floor in range(10, 0, -1):
        floors.append(stop_at_floor.submit(floor))
    wait(floors)
```

By default, tasks are submitted via the `ThreadPoolTaskRunner`, which runs tasks concurrently in a thread pool.

<Warning>
  A common mistake is to pass non-thread-safe objects to tasks that you submit to a task runner. Avoid passing non-thread-safe objects to tasks you intend to run concurrently.

  See [Design Considerations](/v3/concepts/task-runners#design-considerations) for more information.
</Warning>

### Using a different task runner

To run submitted tasks with a different task runner, you can pass a `task_runner` argument to the `@flow` decorator.

<Note>
  To run this example, you'll need to install the `prefect[dask]` extra
</Note>

```python
import time

from prefect import flow, task
from prefect.futures import wait
from prefect_dask.task_runners import DaskTaskRunner

@task
def stop_at_floor(floor: int):
    print(f"elevator moving to floor {floor}")
    time.sleep(floor)
    print(f"elevator stops on floor {floor}")

@flow(task_runner=DaskTaskRunner())
def elevator():
    floors = []
    for floor in range(10, 0, -1):
        floors.append(stop_at_floor.submit(floor))
    wait(floors)
```

### Handling futures

When you submit a task, you'll receive a `PrefectFuture` object back which you can use to track the task's execution. Use the `.result()` method to get the result of the task.

```python
from prefect import task, flow

@task
def cool_task():
    return "sup"
    
@flow
def my_workflow():
    future = cool_task.submit()
    result = future.result()
    print(result)
```

If you don't need to the result of the task, you can use the `.wait()` method to wait for execution to complete.

```python
from prefect import task, flow

@task
def cool_task():
    return "sup"
    
@flow
def my_workflow():
    future = cool_task.submit()
    future.wait()
```

To wait for multiple futures to complete, use the `wait()` utility.

```python
from prefect import task, flow
from prefect.futures import wait


@task
def cool_task():
    return "sup"
    
    
@flow
def my_workflow():
    futures = [cool_task.submit() for _ in range(10)]
    wait(futures)
```

<Tip>
  **Passing futures between tasks**

  If you pass `PrefectFuture` objects between tasks or flows, the task or flow receiving the future will wait for the future to complete before starting execution.

  ```python
  from prefect import task, flow

  @task
  def cool_task():
      return "sup"


  @task
  def what_did_cool_task_say(what_it_said: str):
      return f"cool task said {what_it_said}"

  @flow
  def my_workflow():
      future = cool_task.submit()
      print(what_did_cool_task_say(future))
  ```
</Tip>

## Using `.map`

For a convenient way to iteratively submit tasks, use the `.map()` method.

```python
import time

from prefect import flow, task
from prefect.futures import wait

@task
def stop_at_floor(floor: int):
    print(f"elevator moving to floor {floor}")
    time.sleep(floor)
    print(f"elevator stops on floor {floor}")

@flow
def elevator():
    floors = list(range(10, 0, -1))
    floors = stop_at_floor.map(floors)
    wait(floors)
```

Like `.submit`, `.map` uses the task runner configured on the parent flow. Changing the task runner will change where mapped tasks are executed.

### Using the `unmapped` annotation

Sometimes you may not want to map a task over a certain input value.

By default, non-iterable values will not be mapped over (so `unmapped` is not required):

```python
from prefect import flow, task

@task
def add_together(x, y):
    return x + y

@flow
def sum_it(numbers: list[int], static_value: int):
    futures = add_together.map(numbers, static_value)
    return futures.result()

resulting_sum = sum_it([1, 2, 3], 5)
assert resulting_sum == [6, 7, 8]
```

... but if your argument is an iterable type, wrap it with `unmapped` to tell `.map` to treat it
as static:

```python
from prefect import flow, task, unmapped

@task
def sum_plus(x, static_iterable):
    return x + sum(static_iterable)

@flow
def sum_it(numbers, static_iterable):
    futures = sum_plus.map(numbers, unmapped(static_iterable))
    return futures.result()

resulting_sum = sum_it([4, 5, 6], [1, 2, 3])
assert resulting_sum == [10, 11, 12]
```

### Bulk `PrefectFuture` operations

When using `.map` as in the above example, the result of the task is a list of futures.

You can wait for or retrieve the results from these futures with `wait` or `result` methods:

{/* pmd-metadata: notest */}

```python
futures = some_task.map(some_iterable)
results = futures.result()
```

which is syntactic sugar for the corresponding list comprehension:

{/* pmd-metadata: notest */}

```python
futures = some_task.map(some_iterable)
results = [future.result() for future in futures]
```

### Nested mapped tasks

To model more complex concurrent workflows, you can map tasks within other tasks:

```python {16}
import re

from prefect import flow, task
from prefect.futures import wait

def count_words(text: str) -> int:
    """Count the number of words in a text."""
    return len(text.split())

def extract_emails(text: str) -> list[str]:
    return re.findall(r"[\w.+-]+@[\w-]+\.[\w.-]+", text)

@task
def analyze_texts(texts: list[str]) -> dict[str, list[int | list[str]]]:
    futures = {
        op.__name__: task(op).map(texts) for op in [count_words, extract_emails]
    }
    wait([f for futs in futures.values() for f in futs])
    return {name: [f.result() for f in futs] for name, futs in futures.items()}

@flow
def run_text_analysis():
    """Analyze a batch of social media posts with multiple operations."""
    results = analyze_texts(
        texts=[
            "Just visited #Paris! Contact me at visitor@example.com #travel #vacation",
            "Working on my new #project. Reach out at developer@example.com if interested!",
            "Happy to announce our company event #celebration #milestone email: events@company.org",
        ]
    )
    print("\nAnalysis Results:")
    print(f"  Word counts: {results['count_words']}")
    print(f"  Extracted emails: {results['extract_emails']}\n")
    return results

run_text_analysis()
```

<Accordion title="Output">
  {/* pmd-metadata: notest */}

  ```python
  00:03:45.159 | INFO    | Flow run 'hilarious-collie' - Beginning flow run 'hilarious-collie' for flow 'run-text-analysis'
  00:03:45.233 | INFO    | Task run 'count_words-01a' - Finished in state Completed()
  00:03:45.236 | INFO    | Task run 'extract_emails-7a7' - Finished in state Completed()
  00:03:45.237 | INFO    | Task run 'extract_emails-ca2' - Finished in state Completed()
  00:03:45.239 | INFO    | Task run 'count_words-01d' - Finished in state Completed()
  00:03:45.240 | INFO    | Task run 'count_words-f0a' - Finished in state Completed()
  00:03:45.242 | INFO    | Task run 'extract_emails-0c6' - Finished in state Completed()
  00:03:45.247 | INFO    | Task run 'analyze_texts-53b' - Finished in state Completed()

  Analysis Results:
    Word counts: [9, 11, 10]
    Extracted emails: [['visitor@example.com'], ['developer@example.com'], ['events@company.org']]

  00:03:45.491 | INFO    | Flow run 'hilarious-collie' - Finished in state Completed()
  ```
</Accordion>

This pattern is useful when you need to:

1. Process combinations of parameters concurrently
2. Apply multiple transformations to multiple datasets
3. Create a grid of operations where each cell is an independent task

## Creating state dependencies

You may also use the [`wait_for=[]`](https://reference.prefect.io/prefect/tasks/#prefect.tasks.Task.submit) parameter
when calling a task by specifying upstream task dependencies. This enables you to control task execution
order for tasks that do not share data dependencies.

```python
from prefect import flow, task
@task
def task_a():
    pass

@task
def task_b():
    pass

@task
def task_c():
    pass
    
@task
def task_d():
    pass

@flow
def my_flow():
    a = task_a.submit()
    b = task_b.submit()
    # Wait for task_a and task_b to complete
    c = task_c.submit(wait_for=[a, b])
    # task_d will wait for task_c to complete
    # Note: If waiting for one task it must still be in a list.
    d = task_d(wait_for=[c])
```

## Handling failures in concurrent work

Instead of failing your entire workflow when a single concurrent task fails, you may want to run concurrent work to completion, even if some tasks fail. To run tasks concurrently and handle failures afterwards, use the `wait()` utility along with the `.state` attribute on futures:

```python
from typing import Any

from prefect import flow, task
from prefect.futures import wait
from prefect.states import State

@task
def process_data(item: int) -> str:
    if item < 0:
        raise ValueError(f"Cannot process negative value: {item}")
    return f"Processed {item}"

@flow
def batch_processing():
    items = [1, -2, 3, -4, 5]
    
    # Submit all tasks and return the futures
    futures = process_data.map(items)
    
    # Wait for all futures to complete concurrently
    done, not_done = wait(futures)
    
    # Check each future's state
    successful: list[Any] = []
    failed: list[State] = []
    
    for future in done:
        if future.state.is_completed():
            successful.append(future.result())
        else:
            failed.append(future.state)
    
    print(f"Processed {len(successful)} items successfully")
    print(f"Failed to process {len(failed)} items")
    
    return successful
```

The `wait()` function returns two sets of futures: `done` and `not_done`. Each future has a `.state` attribute you can inspect to determine how the associated task run's result (or exception) should be treated downstream.

<Note>
  The "right way" to handle failures will depend on your use case. Review the [final state determination](/v3/concepts/states#final-state-determination) documentation for more information.
</Note>

## Using `asyncio`

If you have tasks are defined as async functions, you can use `asyncio` from the Python standard library to run them concurrently.

```python
import asyncio

from prefect import flow, task

@task
async def stop_at_floor(floor: int):
    print(f"elevator moving to floor {floor}")
    await asyncio.sleep(floor)
    print(f"elevator stops on floor {floor}")

@flow
async def elevator():
    floors = list(range(10, 0, -1))
    await asyncio.gather(*[stop_at_floor(floor) for floor in floors])


if __name__ == "__main__":
    asyncio.run(elevator())
```

## Real-world applications

Mapped tasks are particularly valuable in common data science and ETL workflows such as:

1. **Machine learning model evaluation**: Train multiple models on multiple datasets concurrently
2. **ETL pipelines**: Process multiple data sources with multiple transformations
3. **API data enrichment**: Enrich multiple records with data from multiple external services

For example, imagine you want to find the best training configuration for a series of datasets, and you want to process all datasets concurrently:

```python
import random
from dataclasses import dataclass

from prefect import flow, task
from prefect.futures import PrefectFuture, wait

@dataclass
class Dataset:
    name: str

@dataclass
class ModelConfig:
    name: str

@task(task_run_name="train on {dataset.name} with {model_config.name}")
def train_model(dataset: Dataset, model_config: ModelConfig) -> dict:
    return {
        "dataset": dataset.name,
        "model": model_config.name,
        "score": random.random(),
    }

@flow
def evaluate_models(datasets: list[Dataset], model_configs: list[ModelConfig]):
    all_futures: list[PrefectFuture[dict[str, object]]] = []
    for dataset in datasets:
        futures = train_model.map(
            dataset=dataset,
            model_config=model_configs,
        )
        all_futures.extend(futures)

    results = [future.result() for future in wait(all_futures).done]

    print(f"\nBest model: {max(results, key=lambda r: r['score'])}")

evaluate_models(
    datasets=[
        Dataset("customers"), Dataset("products"), Dataset("orders")
    ],
    model_configs=[
        ModelConfig("random_forest"), ModelConfig("gradient_boosting")
    ],
)
```

<Accordion title="Output">
  {/* pmd-metadata: notest */}

  ```python
  00:56:47.873 | INFO    | Flow run 'precious-walrus' - Beginning flow run 'precious-walrus' for flow 'evaluate-models'
  00:56:47.981 | INFO    | Task run 'train on customers with random_forest' - Finished in state Completed()
  00:56:47.984 | INFO    | Task run 'train on orders with gradient_boosting' - Finished in state Completed()
  00:56:47.984 | INFO    | Task run 'train on customers with gradient_boosting' - Finished in state Completed()
  00:56:47.985 | INFO    | Task run 'train on products with random_forest' - Finished in state Completed()
  00:56:47.988 | INFO    | Task run 'train on orders with random_forest' - Finished in state Completed()
  00:56:47.990 | INFO    | Task run 'train on products with gradient_boosting' - Finished in state Completed()

  Best model: {'dataset': 'products', 'model': 'random_forest', 'score': 0.5603239415052655}

  00:56:48.121 | INFO    | Flow run 'precious-walrus' - Finished in state Completed()
  ```
</Accordion>


# How to respond to state changes
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/state-change-hooks

Learn how to execute code in response to entering states in your workflows.

### Available state change hooks

| Type                                           | Flow | Task | Description                                                  |
| ---------------------------------------------- | ---- | ---- | ------------------------------------------------------------ |
| `on_completion`                                | ✓    | ✓    | Executes when a flow or task run enters a `Completed` state. |
| `on_failure`                                   | ✓    | ✓    | Executes when a flow or task run enters a `Failed` state.    |
| <span class="no-wrap">`on_cancellation`</span> | ✓    | -    | Executes when a flow run enters a `Cancelling` state.        |
| `on_crashed`                                   | ✓    | -    | Executes when a flow run enters a `Crashed` state.           |
| `on_running`                                   | ✓    | -    | Executes when a flow run enters a `Running` state.           |

<Note>
  Note that the `on_rollback` hook for tasks is *not* a proper state change hook but instead
  is a transaction lifecycle hook.
  Rollback hooks accept one argument representing the transaction for the task.
</Note>

### Send a notification when a workflow run fails

To send a notification when a flow or task run fails, you can specify a `on_failure` hook.

```python
from prefect import flow
from prefect.blocks.core import Block
from prefect.settings import get_current_settings


@flow(retries=1)
def failing_flow():
    raise ValueError("oops!")


@failing_flow.on_failure
def notify_slack(flow, flow_run, state):
    slack_webhook_block = Block.load(
        "slack-webhook/my-slack-webhook"
    )

    PREFECT_API_URL = get_current_settings().api.url

    slack_webhook_block.notify(
        (
            f"Your job {flow_run.name} entered {state.name} "
            f"with message:\n\n"
            f"See <https://{PREFECT_API_URL}/flow-runs/"
            f"flow-run/{flow_run.id}|the flow run in the UI>\n\n"
            f"Tags: {flow_run.tags}\n\n"
            f"Scheduled start: {flow_run.expected_start_time}"
        )
    )

if __name__ == "__main__":
    failing_flow()
```

Retries are configured in this example, so the `on_failure` hook will not run until all `retries` have completed and the flow run enters a `Failed` state.

<Warning>
  **State change hooks execute client side**

  State change hooks run in the same process as your workflow and execution cannot be guaranteed. For more robust execution of logic in response to state changes, use an Automation.
</Warning>

### Pass `kwargs` to state change hooks

You can compose the `with_options` method to effectively pass arbitrary `**kwargs` to your hooks:

```python
from functools import partial
from prefect import flow, task

data = {}

def my_hook(task, task_run, state, **kwargs):
    data.update(state=state, **kwargs)

@task
def bad_task():
    raise ValueError("meh")

@flow
def ok_with_failure_flow(x: str = "foo", y: int = 42):
    bad_task_with_a_hook = bad_task.with_options(
        on_failure=[partial(my_hook, **dict(x=x, y=y))]
    )
    # return a tuple of "bar" and the task run state
    # to avoid raising the task's exception
    return "bar", bad_task_with_a_hook(return_state=True)

_, task_run_state = ok_with_failure_flow()

assert data == {"x": "foo", "y": 42, "state": task_run_state}
```


# How to limit concurrent task runs with tags
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/tag-based-concurrency-limits

Prevent too many tasks from running simultaneously using tags.

Use task tags to limit how many tasks can run at the same time. This is useful when tasks interact with shared resources like databases or external APIs.

```python
from prefect import flow, task

@task(tags=["database"])
def fetch_data():
    # This task will respect the "database" tag's concurrency limit
    return "data"

@flow
def my_workflow():
    fetch_data()
```

For more details on how tag-based concurrency limits work, see the [tag-based concurrency limits concept page](/v3/concepts/tag-based-concurrency-limits).

<Note>
  As of Prefect 3.4.19, tag-based concurrency limits are backed by [global concurrency limits](/v3/how-to-guides/workflows/global-concurrency-limits). When you create a tag-based limit, you'll see a corresponding global concurrency limit with the name `tag:{tag_name}`.
</Note>

## Set concurrency limits on tags

Tags without concurrency limits allow unlimited concurrent runs. Once you set a limit, only that many tasks with the tag can run simultaneously.

```python
from prefect import flow, task

@task(tags=["database"])
def query_database(query: str):
    # Simulate database work
    return f"Results for {query}"

@flow
def data_pipeline():
    # These will respect the "database" tag limit
    query_database("SELECT * FROM users")
    query_database("SELECT * FROM orders")
    query_database("SELECT * FROM products")
```

## Apply multiple tags to a task

When a task has multiple tags, it must have available concurrency slots for **all** tags to run.

```python
from prefect import task

@task(tags=["database", "analytics"])
def complex_query():
    # This task needs available slots in both "database" AND "analytics" limits
    return "complex results"
```

## Configure concurrency limits

You can configure limits using the CLI, Python client, API, Terraform, or the Prefect UI.

### CLI

```bash
# Set a limit of 10 for the "database" tag
prefect concurrency-limit create database 10

# View all concurrency limits
prefect concurrency-limit ls

# View details about a specific tag's limit
prefect concurrency-limit inspect database

# Delete a concurrency limit
prefect concurrency-limit delete database
```

### Python client

```python
from prefect import get_client

async with get_client() as client:
    # Set a concurrency limit of 10 on the "database" tag
    await client.create_concurrency_limit(
        tag="database",
        concurrency_limit=10
    )

    # Read current limit for a tag
    limit = await client.read_concurrency_limit_by_tag(tag="database")

    # Delete a concurrency limit
    await client.delete_concurrency_limit_by_tag(tag="database")

    # View all concurrency limits
    limits = await client.read_concurrency_limits()
```

### API

```bash
# Create a concurrency limit
curl -X POST "http://localhost:4200/api/concurrency_limits/" \
  -H "Content-Type: application/json" \
  -d '{"tag": "database", "concurrency_limit": 10}'

# Get all concurrency limits
curl "http://localhost:4200/api/concurrency_limits/"
```

### Terraform

```hcl
resource "prefect_concurrency_limit" "database_limit" {
  tag               = "database"
  concurrency_limit = 10
}
```

## Configure globally

When a task is delayed due to a concurrency limit, it will wait for a set wait time before retrying. You can set the wait time for when tasks are delayed due to concurrency limits:

```bash
prefect config set PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS=60
```

Note: this setting needs to be set on the Prefect server, not the Prefect client.


# How to test workflows
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/test-workflows

Learn about writing tests for Prefect flows and tasks.

### Isolate tests with an ephemeral backend

Prefect provides a simple context manager for unit tests that allows you to run flows and tasks against a temporary local SQLite database.

```python
from prefect import flow
from prefect.testing.utilities import prefect_test_harness

@flow
def my_favorite_flow():
    return 42

def test_my_favorite_flow():
  with prefect_test_harness():
      # run the flow against a temporary testing database
      assert my_favorite_flow() == 42
```

For more extensive testing, use `prefect_test_harness` as a fixture in your unit testing framework. For example, when using `pytest`:

```python
from prefect import flow
import pytest
from prefect.testing.utilities import prefect_test_harness

@pytest.fixture(autouse=True, scope="session")
def prefect_test_fixture():
    with prefect_test_harness():
        yield

@flow
def my_favorite_flow():
    return 42

def test_my_favorite_flow():
    assert my_favorite_flow() == 42
```

<Note>
  **Session scoped fixture**

  In this example, the fixture is scoped to run once for the entire test session. In most cases, you do not need a clean database for each test. Just isolate your test runs to a test database. Creating a new test database per test creates significant overhead, so we recommend scoping the fixture to the session. If you need to isolate some tests fully, use the test harness again to create a fresh database.
</Note>

### Unit testing underlying functions

To test the function decorated with `@task` or `@flow`, use `.fn` to call the wrapped function directly:

```python
from prefect import flow, task

@task
def my_favorite_task():
    return 42

@flow
def my_favorite_flow():
    val = my_favorite_task()
    return val

def test_my_favorite_task():
    assert my_favorite_task.fn() == 42
```

If your flow or task uses a logger, you can disable the logger to avoid the `RuntimeError` raised from a missing flow context.

```python
from prefect.logging import disable_run_logger

def test_my_favorite_task():
    with disable_run_logger():
        assert my_favorite_task.fn() == 42
```


# How to write and run a workflow
Source: https://docs-3.prefect.io/v3/how-to-guides/workflows/write-and-run



### Define a workflow

Make a Python function a workflow by adding the `@flow` decorator to it:

```python
from prefect import flow


@flow
def my_workflow() -> str:
    return "Hello, world!"
```

Run the workflow by calling it like a normal Python function:

{/* pmd-metadata: continuation */}

```python
my_workflow()
```

You can create a workflow from a method on a class:

```python
from prefect import flow


class MyClass:

    @flow
    def my_instance_method(self):
        return "Hello, from an instance method!"


    @flow
    @classmethod
    def my_class_method(cls):
        return "Hello, from a class method!"


    @flow
    @staticmethod
    def my_static_method():
        return "Hello, from a static method!"


MyClass().my_instance_method()
MyClass.my_class_method()
MyClass.my_static_method()
```

or from a generator function:

```python
from prefect import flow


@flow
def generator():
    for i in range(10):
        yield i


for val in generator():
    print(val)
```

You can view all workflow runs in the Prefect UI.

### Create tasks and child workflows

You can create tasks and child flows to organize your workflow logic.

```python
from prefect import flow, task


@task
def generate_a_number():
    return random.randint(0, 100)


@flow
def is_number_even(number: int):
    return number % 2 == 0


@flow
def even_or_odd():
    number = generate_a_number()
    if is_number_even(number):
        print("The number is even")
    else:
        print("The number is odd")
```

Each task and child flow is a separate unit of work and is displayed in the Prefect UI.

### Cancel a workflow if it runs for too long

To apply a timeout to a flow or task to prevent it from running for too long, use the `timeout_seconds` keyword argument.

```python
from prefect import flow
import time

@flow(timeout_seconds=1, log_prints=True)
def show_timeouts():
    print("I will execute")
    time.sleep(5)
    print("I will not execute")
```

## Configure flows and tasks

### Flow configuration

All flows can be configured by passing arguments to the decorator. Flows accept the following optional settings:

| Argument                                           | Description                                                                                                                                                                                                          |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description`                                      | An optional string description for the flow. If not provided, the description is pulled from the docstring for the decorated function.                                                                               |
| `name`                                             | An optional name for the flow. If not provided, the name is inferred from the function.                                                                                                                              |
| `retries`                                          | An optional number of times to retry on flow run failure.                                                                                                                                                            |
| <span class="no-wrap">`retry_delay_seconds`</span> | An optional number of seconds to wait before retrying the flow after failure. This is only applicable if `retries` is nonzero.                                                                                       |
| `flow_run_name`                                    | An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables; you can also provide this name as a function that returns a string.       |
| `task_runner`                                      | An optional [task runner](/v3/concepts/task-runners/) to use for task execution within the flow when you `.submit()` tasks. If not provided and you `.submit()` tasks, the `ThreadPoolTaskRunner` is used.           |
| `timeout_seconds`                                  | An optional number of seconds indicating a maximum runtime for the flow. If the flow exceeds this runtime, it is marked as failed. Flow execution may continue until the next task is called.                        |
| `validate_parameters`                              | Boolean indicating whether parameters passed to flows are validated by Pydantic. Default is `True`.                                                                                                                  |
| `version`                                          | An optional version string for the flow. If not provided, we will attempt to create a version string as a hash of the file containing the wrapped function. If the file cannot be located, the version will be null. |

### Task configuration

Tasks allow for customization through optional arguments that can be provided to the [task decorator](https://reference.prefect.io/prefect/tasks/#prefect.tasks.task).

| Argument              | Description                                                                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                | An optional name for the task. If not provided, the name is inferred from the function name.                                                                                                                               |
| `description`         | An optional string description for the task. If not provided, the description is pulled from the docstring for the decorated function.                                                                                     |
| `tags`                | An optional set of tags associated with runs of this task. These tags are combined with any tags defined by a `prefect.tags` context at task runtime.                                                                      |
| `timeout_seconds`     | An optional number of seconds indicating a maximum runtime for the task. If the task exceeds this runtime, it will be marked as failed.                                                                                    |
| `cache_key_fn`        | An optional callable that, given the task run context and call parameters, generates a string key. If the key matches a previous completed state, that state result is restored instead of running the task again.         |
| `cache_policy`        | An optional policy that determines what information is used to generate cache keys. Available policies include `INPUTS`, `TASK_SOURCE`, `RUN_ID`, `FLOW_PARAMETERS`, and `NO_CACHE`. Can be combined using the + operator. |
| `cache_expiration`    | An optional amount of time indicating how long cached states for this task are restorable; if not provided, cached states will never expire.                                                                               |
| `retries`             | An optional number of times to retry on task run failure.                                                                                                                                                                  |
| `retry_delay_seconds` | An optional number of seconds to wait before retrying the task after failure. This is only applicable if `retries` is nonzero.                                                                                             |
| `log_prints`          | An optional boolean indicating whether to log print statements.                                                                                                                                                            |

See all possible options in the [Python SDK docs](https://reference.prefect.io/prefect/tasks/#prefect.tasks.task).

For example, provide optional `name` and `description` arguments to a task:

```python
from prefect import task


@task(name="hello-task", description="This task says hello.")
def my_task():
    print("Hello, I'm a task")
```

Distinguish runs of this task by providing a `task_run_name`.\
Python's standard string formatting syntax applies:

```python
import datetime
from prefect import flow, task


@task(name="My Example Task", 
      description="An example task for a tutorial.",
      task_run_name="hello-{name}-on-{date:%A}")
def my_task(name, date):
    pass


@flow
def my_flow():
    # creates a run with a name like "hello-marvin-on-Thursday"
    my_task(name="marvin", date=datetime.datetime.now(datetime.timezone.utc))

if __name__ == "__main__":
    my_flow()
```

Additionally, this setting accepts a function that returns a string for the task run name:

```python
import datetime
from prefect import flow, task


def generate_task_name():
    date = datetime.datetime.now(datetime.timezone.utc)
    return f"{date:%A}-is-a-lovely-day"


@task(name="My Example Task",
      description="An example task for the docs.",
      task_run_name=generate_task_name)
def my_task(name):
    pass


@flow
def my_flow():
    # creates a run with a name like "Thursday-is-a-lovely-day"
    my_task(name="marvin")


if __name__ == "__main__":
    my_flow()  
```


# Release Notes
Source: https://docs-3.prefect.io/v3/release-notes/index



Browse release notes for Prefect OSS, Integrations, and Prefect Cloud.

## Prefect OSS

Release notes for the open-source Prefect orchestration engine.

### Available Versions

* [Version 3.4](/v3/release-notes/oss/version-3-4)
* [Version 3.3](/v3/release-notes/oss/version-3-3)
* [Version 3.2](/v3/release-notes/oss/version-3-2)
* [Version 3.1](/v3/release-notes/oss/version-3-1)
* [Version 3.0](/v3/release-notes/oss/version-3-0)

## Integrations

Release notes for Prefect integrations.

* [prefect-aws](/v3/release-notes/integrations/prefect-aws)
* [prefect-redis](/v3/release-notes/integrations/prefect-redis)

## Prefect Cloud

Release notes for Prefect Cloud features and updates.

*Coming soon*


# 3.0
Source: https://docs-3.prefect.io/v3/release-notes/oss/version-3-0



## 3.0.11 - Thread Carefully

*Released on October 25, 2024*

**Enhancements ➕➕**

* Add setting to configure default max workers for `ThreadPoolTaskRunner` by [@soamicharan](https://github.com/soamicharan) in [#15719](https://github.com/PrefectHQ/prefect/pull/15719)
* Improve handling of interrupts to `serve` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15727](https://github.com/PrefectHQ/prefect/pull/15727)
* Checks for active workers when deploying by [@jeanluciano](https://github.com/jeanluciano) in [#15632](https://github.com/PrefectHQ/prefect/pull/15632)
* Highlight `Cached` state in console logs by [@zzstoatzz](https://github.com/zzstoatzz) in [#15801](https://github.com/PrefectHQ/prefect/pull/15801)

**Bug Fixes 🐞**

* Fix origin repo check that bypasses Docker Login on PRs originating from forks by [@kzvezdarov](https://github.com/kzvezdarov) in [#15724](https://github.com/PrefectHQ/prefect/pull/15724)
* Fix capture of pod logs for `run_namespaced_job` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15732](https://github.com/PrefectHQ/prefect/pull/15732)
* Add `/api` to `PREFECT_UI_API_URL` in default case by [@zzstoatzz](https://github.com/zzstoatzz) in [#15736](https://github.com/PrefectHQ/prefect/pull/15736)
* Pass lowercase log level to uvicorn server by [@gigaverse-oz](https://github.com/gigaverse-oz) in [#15680](https://github.com/PrefectHQ/prefect/pull/15680)
* Fix handling of Dask DataFrame and other Awaitables passed to `run_coro_as_sync` by [@kzvezdarov](https://github.com/kzvezdarov) in [#15687](https://github.com/PrefectHQ/prefect/pull/15687)
* Wraps `run_dbt_` functions in `sync_compatible` by [@EmilRex](https://github.com/EmilRex) in [#15740](https://github.com/PrefectHQ/prefect/pull/15740)
* Fix custom task run name rendering by [@zzstoatzz](https://github.com/zzstoatzz) in [#15773](https://github.com/PrefectHQ/prefect/pull/15773)
* Fix incorrect import in agents to workers guide by [@zzstoatzz](https://github.com/zzstoatzz) in [#15789](https://github.com/PrefectHQ/prefect/pull/15789)
* Soft wrap deployment link by [@zzstoatzz](https://github.com/zzstoatzz) in [#15787](https://github.com/PrefectHQ/prefect/pull/15787)
* Fix worker filter param by [@zangell44](https://github.com/zangell44) in [#15804](https://github.com/PrefectHQ/prefect/pull/15804)
* Include env defaults from `variables.properties.env` in deep merge by [@kevingrismore](https://github.com/kevingrismore) in [#15692](https://github.com/PrefectHQ/prefect/pull/15692)
* Fix wrong exception in lazy import **getattr** by [@protagonyist](https://github.com/protagonyist) in [#15741](https://github.com/PrefectHQ/prefect/pull/15741)

**Integrations & Dependencies 🤝**

* Set minimum version of `pydantic-settings` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15797](https://github.com/PrefectHQ/prefect/pull/15797)

**`prefect-gcp`**

* Support CloudSQL volumes for cloud run jobs by [@matmiad](https://github.com/matmiad) in [#15778](https://github.com/PrefectHQ/prefect/pull/15778)

**`prefect-dbt`**

* Fix dbt CLI argument parsing for multipart commands by [@e1337us3r](https://github.com/e1337us3r) in [#15714](https://github.com/PrefectHQ/prefect/pull/15714)

**`prefect-kubernetes`**

* Avoid crashing flows when job watch exits but container is still running by [@soamicharan](https://github.com/soamicharan) in [#15728](https://github.com/PrefectHQ/prefect/pull/15728)
* Add `_request_timeout` to Kubernetes watches by [@kevingrismore](https://github.com/kevingrismore) in [#15744](https://github.com/PrefectHQ/prefect/pull/15744)

**Development & Tidiness 🧹**

* Create settings models for CLI and client settings by [@desertaxle](https://github.com/desertaxle) in [#15640](https://github.com/PrefectHQ/prefect/pull/15640)
* Create settings models for cloud, deployments, and logging  by [@desertaxle](https://github.com/desertaxle) in [#15749](https://github.com/PrefectHQ/prefect/pull/15749)
* Create settings models for flows, results, and runners by [@desertaxle](https://github.com/desertaxle) in [#15754](https://github.com/PrefectHQ/prefect/pull/15754)
* Create server settings models by [@desertaxle](https://github.com/desertaxle) in [#15758](https://github.com/PrefectHQ/prefect/pull/15758)
* Create settings submodules by [@desertaxle](https://github.com/desertaxle) in [#15772](https://github.com/PrefectHQ/prefect/pull/15772)
* Create settings models for services, events, tasks, and the flow run graph by [@desertaxle](https://github.com/desertaxle) in [#15776](https://github.com/PrefectHQ/prefect/pull/15776)
* Create worker, tasks, testing, and UI settings models by [@desertaxle](https://github.com/desertaxle) in [#15784](https://github.com/PrefectHQ/prefect/pull/15784)
* Fix failing work queue test by [@desertaxle](https://github.com/desertaxle) in [#15709](https://github.com/PrefectHQ/prefect/pull/15709)
* Split out runner and worker tests to avoid hanging test suite by [@desertaxle](https://github.com/desertaxle) in [#15715](https://github.com/PrefectHQ/prefect/pull/15715)
* Only authenticate with Docker when running on a branch by [@desertaxle](https://github.com/desertaxle) in [#15708](https://github.com/PrefectHQ/prefect/pull/15708)
* Give more time for integration serve flow by [@zzstoatzz](https://github.com/zzstoatzz) in [#15720](https://github.com/PrefectHQ/prefect/pull/15720)
* De-flake serve integration test by [@zzstoatzz](https://github.com/zzstoatzz) in [#15726](https://github.com/PrefectHQ/prefect/pull/15726)
* Add code coverage generation and upload for Python tests by [@desertaxle](https://github.com/desertaxle) in [#15690](https://github.com/PrefectHQ/prefect/pull/15690)
* Remove `setuptools` and update `pip` pin in Docker build by [@desertaxle](https://github.com/desertaxle) in [#15759](https://github.com/PrefectHQ/prefect/pull/15759)
* Improve map typing by [@zzstoatzz](https://github.com/zzstoatzz) in [#15757](https://github.com/PrefectHQ/prefect/pull/15757)
* Ignore errors when cleaning up after deploy integration test by [@desertaxle](https://github.com/desertaxle) in [#15768](https://github.com/PrefectHQ/prefect/pull/15768)
* Disable automatic markdown tests by [@zzstoatzz](https://github.com/zzstoatzz) in [#15782](https://github.com/PrefectHQ/prefect/pull/15782)
* Fix typing for triggers schemas by [@zzstoatzz](https://github.com/zzstoatzz) in [#15792](https://github.com/PrefectHQ/prefect/pull/15792)
* Update instructions on bug report issue template by [@desertaxle](https://github.com/desertaxle) in [#15795](https://github.com/PrefectHQ/prefect/pull/15795)
* Format example code in `README.md` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15807](https://github.com/PrefectHQ/prefect/pull/15807)
* Fix typo in prefect-databricks by [@aaazzam](https://github.com/aaazzam) in [#15800](https://github.com/PrefectHQ/prefect/pull/15800)
* Fix links to 3.0 docs that are missing a leading slash by [@sam-phinizy](https://github.com/sam-phinizy) in [#15704](https://github.com/PrefectHQ/prefect/pull/15704)
* Add a few notes to Docker docs page by [@discdiver](https://github.com/discdiver) in [#15706](https://github.com/PrefectHQ/prefect/pull/15706)
* Improve table formatting in docs by [@discdiver](https://github.com/discdiver) in [#15700](https://github.com/PrefectHQ/prefect/pull/15700)
* Fix docs links for integrations by [@discdiver](https://github.com/discdiver) in [#15702](https://github.com/PrefectHQ/prefect/pull/15702)
* More accessible wording for job variable overrides docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#15669](https://github.com/PrefectHQ/prefect/pull/15669)
* Fix `automation-assement.py` by [@jakekaplan](https://github.com/jakekaplan) in [#15710](https://github.com/PrefectHQ/prefect/pull/15710)
* Give more time for state to integration flow to finish by [@jakekaplan](https://github.com/jakekaplan) in [#15723](https://github.com/PrefectHQ/prefect/pull/15723)
* Fix a few spelling issues in docs by [@discdiver](https://github.com/discdiver) in [#15737](https://github.com/PrefectHQ/prefect/pull/15737)
* Updated Docker push step in docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#15748](https://github.com/PrefectHQ/prefect/pull/15748)
* Clear up namespace selection in Kubernetes guide by [@zzstoatzz](https://github.com/zzstoatzz) in [#15765](https://github.com/PrefectHQ/prefect/pull/15765)
* Update Docker image reference in aci\_worker docs page by [@discdiver](https://github.com/discdiver) in [#15745](https://github.com/PrefectHQ/prefect/pull/15745)
* Fix minor typo on "Deploy overview" page. by [@Noah-Haf](https://github.com/Noah-Haf) in [#15771](https://github.com/PrefectHQ/prefect/pull/15771)
* Add note about schedule kwargs change from 2.x to 3.x by [@zzstoatzz](https://github.com/zzstoatzz) in [#15803](https://github.com/PrefectHQ/prefect/pull/15803)
* Update @prefecthq/prefect-ui-library to version 3.11.3 by [@marvin-robot](https://github.com/marvin-robot) in [#15717](https://github.com/PrefectHQ/prefect/pull/15717)
* Update @prefecthq/prefect-ui-library to version 3.11.4 by [@marvin-robot](https://github.com/marvin-robot) in [#15738](https://github.com/PrefectHQ/prefect/pull/15738)
* Update @prefecthq/prefect-ui-library to version 3.11.7 by [@marvin-robot](https://github.com/marvin-robot) in [#15756](https://github.com/PrefectHQ/prefect/pull/15756)
* Update @prefecthq/prefect-design to version 2.13.3 by [@marvin-robot](https://github.com/marvin-robot) in [#15721](https://github.com/PrefectHQ/prefect/pull/15721)
* Update @prefecthq/prefect-design to version 2.13.4 by [@marvin-robot](https://github.com/marvin-robot) in [#15742](https://github.com/PrefectHQ/prefect/pull/15742)
* Update @prefecthq/prefect-design to version 2.13.5 by [@marvin-robot](https://github.com/marvin-robot) in [#15785](https://github.com/PrefectHQ/prefect/pull/15785)
* Update @prefecthq/prefect-ui-library to version 3.11.5 by [@marvin-robot](https://github.com/marvin-robot) in [#15743](https://github.com/PrefectHQ/prefect/pull/15743)
* Update @prefecthq/prefect-ui-library to version 3.11.6 by [@marvin-robot](https://github.com/marvin-robot) in [#15746](https://github.com/PrefectHQ/prefect/pull/15746)
* Bump tailwindcss from 3.4.13 to 3.4.14 in /ui by [@dependabot](https://github.com/dependabot) in [#15767](https://github.com/PrefectHQ/prefect/pull/15767)
* Bump vite from 5.4.8 to 5.4.9 in /ui by [@dependabot](https://github.com/dependabot) in [#15766](https://github.com/PrefectHQ/prefect/pull/15766)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.10...3.0.11](https://github.com/PrefectHQ/prefect/compare/3.0.10...3.0.11)

***

## 3.0.10 - Serve returned

*Released on October 15, 2024*

This release fixes an issue where served flows would exit early and continues our reorganization of settings with `pydantic-settings`.

**Bug Fixes 🐞**

* Fix bug where `.serve` exits early and add integration test by [@zzstoatzz](https://github.com/zzstoatzz) in [#15691](https://github.com/PrefectHQ/prefect/pull/15691)

**Development**

* Add `APISettings` setting group by [@desertaxle](https://github.com/desertaxle) in [#15701](https://github.com/PrefectHQ/prefect/pull/15701)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.9...3.0.10](https://github.com/PrefectHQ/prefect/compare/3.0.9...3.0.10)

***

## 3.0.9 - There's no place like home

*Released on October 15, 2024*

**Enhancements ✨**

* dont ask to confirm non-existent deployment by [@zzstoatzz](https://github.com/zzstoatzz) in [#15653](https://github.com/PrefectHQ/prefect/pull/15653)

**Bug Fixes 🐞**

* create `PREFECT_HOME` in `root_settings_context` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15696](https://github.com/PrefectHQ/prefect/pull/15696)
* correctly await `config.load_kube_config` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15655](https://github.com/PrefectHQ/prefect/pull/15655)
* Do not delete flow runs awaiting retry on deployment changes by [@kevingrismore](https://github.com/kevingrismore) in [#15688](https://github.com/PrefectHQ/prefect/pull/15688)
* Ensure `TaskWorker` creates a `anyio.TaskGroup` in an `async` context by [@desertaxle](https://github.com/desertaxle) in [#15684](https://github.com/PrefectHQ/prefect/pull/15684)

**Development & Tidiness 🧹**

* Add tests to verify all settings via environment variables by [@desertaxle](https://github.com/desertaxle) in [#15657](https://github.com/PrefectHQ/prefect/pull/15657)
* Update `versioneer.py` to ignore uncommitted changes by [@desertaxle](https://github.com/desertaxle) in [#15672](https://github.com/PrefectHQ/prefect/pull/15672)
* Bump vue from 3.5.10 to 3.5.12 in /ui by [@dependabot](https://github.com/dependabot) in [#15675](https://github.com/PrefectHQ/prefect/pull/15675)
* Add tests for specifying each setting via a profile by [@desertaxle](https://github.com/desertaxle) in [#15670](https://github.com/PrefectHQ/prefect/pull/15670)
* Add tests to verify all supported settings can be set via a `.env` file by [@desertaxle](https://github.com/desertaxle) in [#15682](https://github.com/PrefectHQ/prefect/pull/15682)
* Update @prefecthq/prefect-ui-library to version 3.11.2 by [@marvin-robot](https://github.com/marvin-robot) in [#15695](https://github.com/PrefectHQ/prefect/pull/15695)
* Bump typescript from 5.6.2 to 5.6.3 in /ui by [@dependabot](https://github.com/dependabot) in [#15676](https://github.com/PrefectHQ/prefect/pull/15676)
* Update @prefecthq/vue-compositions to version 1.11.5 by [@marvin-robot](https://github.com/marvin-robot) in [#15699](https://github.com/PrefectHQ/prefect/pull/15699)
* remove note from 3.x docs about using `pydantic<2` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15642](https://github.com/PrefectHQ/prefect/pull/15642)
* Update reference to name of profile in example by [@discdiver](https://github.com/discdiver) in [#15644](https://github.com/PrefectHQ/prefect/pull/15644)
* follow on suggestion: simplify phrasing by [@zzstoatzz](https://github.com/zzstoatzz) in [#15651](https://github.com/PrefectHQ/prefect/pull/15651)
* Edits to dbt integration page by [@discdiver](https://github.com/discdiver) in [#15540](https://github.com/PrefectHQ/prefect/pull/15540)
* Minor updates to deploy overview by [@discdiver](https://github.com/discdiver) in [#15606](https://github.com/PrefectHQ/prefect/pull/15606)
* chore: update secret ref by [@jamiezieziula](https://github.com/jamiezieziula) in [#15641](https://github.com/PrefectHQ/prefect/pull/15641)
* Add link to release notes on What's new docs page by [@discdiver](https://github.com/discdiver) in [#15662](https://github.com/PrefectHQ/prefect/pull/15662)
* Docs note about accessing flow run logs by [@EmilRex](https://github.com/EmilRex) in [#15683](https://github.com/PrefectHQ/prefect/pull/15683)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.8...3.0.9](https://github.com/PrefectHQ/prefect/compare/3.0.8...3.0.9)

***

## 3.0.8 - Revert a settings bug

*Released on October 10, 2024*

This release reverts a change that caused a loss of "set" environment variables in runtime environments.

* Revert "Create `APISettings` to group to group API-specific client settings" by [@zzstoatzz](https://github.com/zzstoatzz) in [#15648](https://github.com/PrefectHQ/prefect/pull/15648)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.7...3.0.8](https://github.com/PrefectHQ/prefect/compare/3.0.7...3.0.8)

***

## 3.0.7 - Version of a down bug

*Released on October 10, 2024*

This release includes a couple of bug fixes, including a fix for generating the Docker image name for the installed version of `prefect`.

**Enhancements ➕➕**

* Link to docs on starting temporary server by [@zzstoatzz](https://github.com/zzstoatzz) in [#15636](https://github.com/PrefectHQ/prefect/pull/15636)

**Bug Fixes 🐞**

* Fix PagerDuty notification formatting by [@kevingrismore](https://github.com/kevingrismore) in [#15584](https://github.com/PrefectHQ/prefect/pull/15584)
* Fix version parsing error when generating Docker image name by [@zzstoatzz](https://github.com/zzstoatzz) in [#15638](https://github.com/PrefectHQ/prefect/pull/15638)

**Development & Tidiness 🧹**

* Use the recommend approach for shallow dumping `pydantic` models by [@zzstoatzz](https://github.com/zzstoatzz) in [#15634](https://github.com/PrefectHQ/prefect/pull/15634)
* Add note about actively developed version to enhancement request form by [@zzstoatzz](https://github.com/zzstoatzz) in [#15600](https://github.com/PrefectHQ/prefect/pull/15600)
* Create `APISettings` to group to group API-specific client settings by [@desertaxle](https://github.com/desertaxle) in [#15580](https://github.com/PrefectHQ/prefect/pull/15580)
* Update image in Quickstart  by [@discdiver](https://github.com/discdiver) in [#15635](https://github.com/PrefectHQ/prefect/pull/15635)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.6...3.0.7](https://github.com/PrefectHQ/prefect/compare/3.0.6...3.0.7)

***

## 3.0.6 - Client, know thyself

*Released on October 09, 2024*

This update focuses on fixing `prefect-client` compatibility checks. Key changes include adding version information to `prefect-client` and adjusting task logging levels.

**Enhancements ➕➕**

* Updated task creation and submission log level to `DEBUG` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15631](https://github.com/PrefectHQ/prefect/pull/15631)

**Bug Fixes 🐞**

* Eliminated date range filter from Flow page by [@dylanbhughes](https://github.com/dylanbhughes) in [#15630](https://github.com/PrefectHQ/prefect/pull/15630)
* Accurately populate `__version__` for `prefect_client` by [@desertaxle](https://github.com/desertaxle) in [#15624](https://github.com/PrefectHQ/prefect/pull/15624)

**Development & Tidiness 🧹**

* Maintain typing information in `PrefectFuture` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15625](https://github.com/PrefectHQ/prefect/pull/15625)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.5...3.0.6](https://github.com/PrefectHQ/prefect/compare/3.0.5...3.0.6)

***

## 3.0.5 - Take care of the .environment

*Released on October 08, 2024*

This release introduces support for loading settings from `.env` files, offering greater flexibility and ease of use in managing your Prefect configurations between projects.

**New Features 🎉**

* Allow specifying settings overrides in a `.env` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15565](https://github.com/PrefectHQ/prefect/pull/15565)

**Enhancements ➕➕**

* Update settings to use `pydantic-settings` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15412](https://github.com/PrefectHQ/prefect/pull/15412)
* Add a helpful message on 404 with deployment by name by [@zzstoatzz](https://github.com/zzstoatzz) in [#15578](https://github.com/PrefectHQ/prefect/pull/15578)

**Bug Fixes 🐞**

* Changed `TaskSource` key computation to handle `OSError("source not available")` by [@kzvezdarov](https://github.com/kzvezdarov) in [#15583](https://github.com/PrefectHQ/prefect/pull/15583)
* Fail correctly if `lookup_type` throws a `KeyError` in `BaseResult.__new__` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15596](https://github.com/PrefectHQ/prefect/pull/15596)
* Fix issue where transaction parent look up fails in rollback hooks by [@desertaxle](https://github.com/desertaxle) in [#15599](https://github.com/PrefectHQ/prefect/pull/15599)
* Fix flow run parameters literally named `keys` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15611](https://github.com/PrefectHQ/prefect/pull/15611)
* Ensure dynamic default values for settings are considered unset by `pydantic` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15613](https://github.com/PrefectHQ/prefect/pull/15613)
* Fix errors when using `run_deployment` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15615](https://github.com/PrefectHQ/prefect/pull/15615)
* Fix errors loading settings when profiles file can't be read by [@desertaxle](https://github.com/desertaxle) in [#15602](https://github.com/PrefectHQ/prefect/pull/15602)

**Integrations & Dependencies 🤝**

* Make database parameter optional in `ConnectionComponents`  #15511 by [@Ben-Taarit](https://github.com/Ben-Taarit) in [#15553](https://github.com/PrefectHQ/prefect/pull/15553)
* Update `AwsClientParameters` validation for `verify` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15574](https://github.com/PrefectHQ/prefect/pull/15574)

**Development & Tidiness 🧹**

* Fix check to prerelease tag to allow nightly builds to publish Docker images by [@desertaxle](https://github.com/desertaxle) in [#15563](https://github.com/PrefectHQ/prefect/pull/15563)
* Update format for nightly dev release names by [@desertaxle](https://github.com/desertaxle) in [#15568](https://github.com/PrefectHQ/prefect/pull/15568)
* Add a note that deployments delegate ACLs to work pools by [@abrookins](https://github.com/abrookins) in [#15383](https://github.com/PrefectHQ/prefect/pull/15383)
* Remove `await` for task submissions in global concurrency limits example by [@biancaines](https://github.com/biancaines) in [#15581](https://github.com/PrefectHQ/prefect/pull/15581)
* Flow code storage docs improvements by [@discdiver](https://github.com/discdiver) in [#15519](https://github.com/PrefectHQ/prefect/pull/15519)
* Update the store flow code docs  by [@discdiver](https://github.com/discdiver) in [#15604](https://github.com/PrefectHQ/prefect/pull/15604)
* Update first docs example by [@discdiver](https://github.com/discdiver) in [#15605](https://github.com/PrefectHQ/prefect/pull/15605)
* Add documentation for `.env` file support by [@zzstoatzz](https://github.com/zzstoatzz) in [#15617](https://github.com/PrefectHQ/prefect/pull/15617)
* Update @prefecthq/prefect-design to version 2.13.2 by [@marvin-robot](https://github.com/marvin-robot) in [#15579](https://github.com/PrefectHQ/prefect/pull/15579)
* Update @prefecthq/prefect-design to version 2.13.1 by [@marvin-robot](https://github.com/marvin-robot) in [#15576](https://github.com/PrefectHQ/prefect/pull/15576)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.4...3.0.5](https://github.com/PrefectHQ/prefect/compare/3.0.4...3.0.5)

***

## 3.0.4 - It's been.. one week since you updated me

*Released on October 01, 2024*

**Enhancements ➕➕**

* update `prefect deployment ls` to show work pool by [@zzstoatzz](https://github.com/zzstoatzz) in [#15454](https://github.com/PrefectHQ/prefect/pull/15454)
* Add --collision-strategy to `prefect deploy` CLI. by [@collincchoy](https://github.com/collincchoy) in [#15468](https://github.com/PrefectHQ/prefect/pull/15468)
* Don't prompt custom image build for managed pools in `prefect deploy` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15484](https://github.com/PrefectHQ/prefect/pull/15484)
* Deploy docs overview improvements by [@discdiver](https://github.com/discdiver) in [#15494](https://github.com/PrefectHQ/prefect/pull/15494)
* Enforces deployment concurrency with orchestration polices. by [@jeanluciano](https://github.com/jeanluciano) in [#15504](https://github.com/PrefectHQ/prefect/pull/15504)
* add `get_current_workspace` cloud client method by [@zzstoatzz](https://github.com/zzstoatzz) in [#15542](https://github.com/PrefectHQ/prefect/pull/15542)
* Enhancement: Add `end_time` to flow run filters by [@znicholasbrown](https://github.com/znicholasbrown) in [#15502](https://github.com/PrefectHQ/prefect/pull/15502)
* Write raw results from flows by [@desertaxle](https://github.com/desertaxle) in [#15434](https://github.com/PrefectHQ/prefect/pull/15434)
* Update `transaction` context manager to default `write_on_commit` to `True` by [@desertaxle](https://github.com/desertaxle) in [#15515](https://github.com/PrefectHQ/prefect/pull/15515)

**Bug Fixes 🐞**

* Use correct JSON schema dialect for param validation by [@GfxKai](https://github.com/GfxKai) in [#15483](https://github.com/PrefectHQ/prefect/pull/15483)
* Fix block reference load in async flow by [@GalLadislav](https://github.com/GalLadislav) in [#15487](https://github.com/PrefectHQ/prefect/pull/15487)
* Add regression test for arbitrary state data by [@desertaxle](https://github.com/desertaxle) in [#15506](https://github.com/PrefectHQ/prefect/pull/15506)
* Update tasks to inherit the lock manager from a parent transaction if present by [@desertaxle](https://github.com/desertaxle) in [#15505](https://github.com/PrefectHQ/prefect/pull/15505)
* override `_coerce_env` for k8s worker by [@zzstoatzz](https://github.com/zzstoatzz) in [#15522](https://github.com/PrefectHQ/prefect/pull/15522)

**Integrations & Dependencies 🤝**

* Bumps `pytest` and `pytest-asyncio` to the latest versions by [@chrisguidry](https://github.com/chrisguidry) in [#15523](https://github.com/PrefectHQ/prefect/pull/15523)
* Avoid shutting down Ray driver when running on a Ray worker by [@desertaxle](https://github.com/desertaxle) in [#15552](https://github.com/PrefectHQ/prefect/pull/15552)
* Fix dbt source freshness fail state by [@e1337us3r](https://github.com/e1337us3r) in [#15510](https://github.com/PrefectHQ/prefect/pull/15510)
* Allow oracle connection urls by [@zzstoatzz](https://github.com/zzstoatzz) in [#15496](https://github.com/PrefectHQ/prefect/pull/15496)
* Use `ConnectionComponents` components from `prefect-sqlalchemy` in `prefect-dbt` by [@westford14](https://github.com/westford14) in [#15499](https://github.com/PrefectHQ/prefect/pull/15499)

**Development & Tidiness 🧹**

* Improve docstring `state.result` for when used with `run_deployment` by [@benjamincerigo](https://github.com/benjamincerigo) in [#15509](https://github.com/PrefectHQ/prefect/pull/15509)
* Fix use of deprecated field on `websockets.exceptions.ConnectionClosedError` by [@desertaxle](https://github.com/desertaxle) in [#15467](https://github.com/PrefectHQ/prefect/pull/15467)
* Set up pytest-markdown-docs for documentation testing by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15457](https://github.com/PrefectHQ/prefect/pull/15457)
* fix test by [@zzstoatzz](https://github.com/zzstoatzz) in [#15480](https://github.com/PrefectHQ/prefect/pull/15480)
* one small type fix by [@zzstoatzz](https://github.com/zzstoatzz) in [#15479](https://github.com/PrefectHQ/prefect/pull/15479)
* use internal logger for `get_lost_followers` retries by [@zzstoatzz](https://github.com/zzstoatzz) in [#15518](https://github.com/PrefectHQ/prefect/pull/15518)
* Update weekly RC workflow to a nightly development workflow by [@desertaxle](https://github.com/desertaxle) in [#15545](https://github.com/PrefectHQ/prefect/pull/15545)
* add note on terminal unawaited coro by [@zzstoatzz](https://github.com/zzstoatzz) in [#15439](https://github.com/PrefectHQ/prefect/pull/15439)
* Add docs on securing webhooks with service accounts by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15481](https://github.com/PrefectHQ/prefect/pull/15481)
* Fix README code example by [@OverShifted](https://github.com/OverShifted) in [#15492](https://github.com/PrefectHQ/prefect/pull/15492)
* Fixes ugly table formatting from bash output in docs by [@discdiver](https://github.com/discdiver) in [#15495](https://github.com/PrefectHQ/prefect/pull/15495)
* Update global concurrency limits docs for removed create\_if\_missing behavior by [@collincchoy](https://github.com/collincchoy) in [#15517](https://github.com/PrefectHQ/prefect/pull/15517)
* Warn if websocket connection can't be made by [@jakekaplan](https://github.com/jakekaplan) in [#15261](https://github.com/PrefectHQ/prefect/pull/15261)
* Fix flow typing when passing return\_state to a coroutine by [@williamjamir](https://github.com/williamjamir) in [#15528](https://github.com/PrefectHQ/prefect/pull/15528)
* Docs for deployment concurrency limits by [@collincchoy](https://github.com/collincchoy) in [#15527](https://github.com/PrefectHQ/prefect/pull/15527)
* Fix automations-triggers doc tests by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15514](https://github.com/PrefectHQ/prefect/pull/15514)
* Remove worker and runner handling for deployment concurrency by [@jeanluciano](https://github.com/jeanluciano) in [#15497](https://github.com/PrefectHQ/prefect/pull/15497)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.3...3.0.4](https://github.com/PrefectHQ/prefect/compare/3.0.3...3.0.4)

***

## 3.0.3 - Cache Rules Everything Around Me

*Released on September 20, 2024*

This release introduces improvements to cache policy configuration, offering developers more control and flexibility in managing task result caching:

* Customizable Storage Location: Specify where cache entries are stored using the `key_storage` parameter.
* Configurable Isolation Level: Set the isolation level for cache access with the `isolation_level` parameter.
* Locking Mechanism: Implement concurrent access control using the `lock_manager` parameter.

These enhancements allow for more sophisticated caching strategies, improving performance and resource management in complex workflows.

To learn more about these changes, check out the [task caching docs](https://docs.prefect.io/3.0/develop/task-caching#customizing-the-cache).

**New Features 🎉**

* Add `key_storage`, `isolation_level` and `lock_manager` configuration to cache policies by [@desertaxle](https://github.com/desertaxle) in [#15382](https://github.com/PrefectHQ/prefect/pull/15382)

**Enhancements ➕➕**

* Adds settings to control server CORS configuration by [@desertaxle](https://github.com/desertaxle) in [#15396](https://github.com/PrefectHQ/prefect/pull/15396)
* Add ability to specify `ConcurrencyOptions` by [@jeanluciano](https://github.com/jeanluciano) in [#15291](https://github.com/PrefectHQ/prefect/pull/15291)
* Add `concurrency_limit` field to `flow.serve` by [@jeanluciano](https://github.com/jeanluciano) in [#15376](https://github.com/PrefectHQ/prefect/pull/15376)
* Allow a rich object to be passed to `concurrency_limit` in client methods by [@jeanluciano](https://github.com/jeanluciano) in [#15425](https://github.com/PrefectHQ/prefect/pull/15425)
* Add support for insecure webhooks by [@westford14](https://github.com/westford14) in [#15402](https://github.com/PrefectHQ/prefect/pull/15402)
* Improve deployment concurrency GCL management by [@collincchoy](https://github.com/collincchoy) in [#15426](https://github.com/PrefectHQ/prefect/pull/15426)

**Bug Fixes 🐞**

* Preserve `flow.name` with `RunnerDeployment.from_storage` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15393](https://github.com/PrefectHQ/prefect/pull/15393)
* Lazy import `ray` to fix server startup issues by [@desertaxle](https://github.com/desertaxle) in [#15392](https://github.com/PrefectHQ/prefect/pull/15392)
* Handle unnamed lambdas for consistency by [@zzstoatzz](https://github.com/zzstoatzz) in [#15400](https://github.com/PrefectHQ/prefect/pull/15400)
* Fix task linking by [@desertaxle](https://github.com/desertaxle) in [#15418](https://github.com/PrefectHQ/prefect/pull/15418)
* Fix ephemeral server start command for Windows by [@desertaxle](https://github.com/desertaxle) in [#15421](https://github.com/PrefectHQ/prefect/pull/15421)
* Fix task run count when a task is configured with `retry_delay_seconds` by [@desertaxle](https://github.com/desertaxle) in [#15424](https://github.com/PrefectHQ/prefect/pull/15424)
* Fix bug where task cache storage is misconfigured by [@desertaxle](https://github.com/desertaxle) in [#15433](https://github.com/PrefectHQ/prefect/pull/15433)
* Update task engine to increment `run_count` when entering `RUNNING` state by [@desertaxle](https://github.com/desertaxle) in [#15436](https://github.com/PrefectHQ/prefect/pull/15436)

**Integrations & Dependencies 🤝**

* Add environment variables from GCP secrets to cloud run job v2 workers by [@Ultramann](https://github.com/Ultramann) in [#15423](https://github.com/PrefectHQ/prefect/pull/15423)
* Prepare `prefect-redis` for `0.2.0` release by [@desertaxle](https://github.com/desertaxle) in [#15409](https://github.com/PrefectHQ/prefect/pull/15409)
* Add `AzureBlobStorageContainer.list_blobs` method by [@westford14](https://github.com/westford14) in [#15390](https://github.com/PrefectHQ/prefect/pull/15390)
* Add `oracledb` driver support in `prefect-sqlalchemy` by [@Ben-Taarit](https://github.com/Ben-Taarit) in [#15385](https://github.com/PrefectHQ/prefect/pull/15385)

**Development & Tidiness 🧹**

* Add docs for configuring storage and isolation for cache policies by [@desertaxle](https://github.com/desertaxle) in [#15397](https://github.com/PrefectHQ/prefect/pull/15397)
* Improve type hinting docs for sync\_compatible by [@benjamincerigo](https://github.com/benjamincerigo) in [#15327](https://github.com/PrefectHQ/prefect/pull/15327)
* Refactors `__add__` and `__sub__` on cache policies by [@desertaxle](https://github.com/desertaxle) in [#15379](https://github.com/PrefectHQ/prefect/pull/15379)
* Add `mypy` type checking to `/models` by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15062](https://github.com/PrefectHQ/prefect/pull/15062)
* Only load collections once by [@abrookins](https://github.com/abrookins) in [#15344](https://github.com/PrefectHQ/prefect/pull/15344)
* Bump vue from 3.5.4 to 3.5.5 in /ui by [@dependabot](https://github.com/dependabot) in [#15386](https://github.com/PrefectHQ/prefect/pull/15386)
* Bump typescript from 5.5.4 to 5.6.2 in /ui by [@dependabot](https://github.com/dependabot) in [#15387](https://github.com/PrefectHQ/prefect/pull/15387)
* Bump tailwindcss from 3.4.10 to 3.4.11 in /ui by [@dependabot](https://github.com/dependabot) in [#15388](https://github.com/PrefectHQ/prefect/pull/15388)
* Bump vite from 5.4.2 to 5.4.5 in /ui by [@dependabot](https://github.com/dependabot) in [#15372](https://github.com/PrefectHQ/prefect/pull/15372)
* Bump vue-router from 4.4.3 to 4.4.5 in /ui by [@dependabot](https://github.com/dependabot) in [#15389](https://github.com/PrefectHQ/prefect/pull/15389)
* Update @prefecthq/prefect-ui-library to version 3.9.5 by [@marvin-robot](https://github.com/marvin-robot) in [#15411](https://github.com/PrefectHQ/prefect/pull/15411)
* Bump vite from 5.4.5 to 5.4.6 in /ui by [@dependabot](https://github.com/dependabot) in [#15410](https://github.com/PrefectHQ/prefect/pull/15410)
* Update @prefecthq/prefect-ui-library to version 3.10.0 by [@marvin-robot](https://github.com/marvin-robot) in [#15419](https://github.com/PrefectHQ/prefect/pull/15419)
  **Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.2...3.0.3](https://github.com/PrefectHQ/prefect/compare/3.0.2...3.0.3)

***

## 3.0.2 - Groundlog day, tomorrow finally came

*Released on September 13, 2024*

**New Features 🎉**

* Add a ResumeFlowRun automations action by [@abrookins](https://github.com/abrookins) in [#15269](https://github.com/PrefectHQ/prefect/pull/15269)

**Enhancements ➕➕**

* Notification security controls by [@cicdw](https://github.com/cicdw) in [#15272](https://github.com/PrefectHQ/prefect/pull/15272)
* Create `FilesystemLockManager` by [@desertaxle](https://github.com/desertaxle) in [#15307](https://github.com/PrefectHQ/prefect/pull/15307)
* Concurrency limit UX enhancements: add `strict` mode by [@cicdw](https://github.com/cicdw) in [#15297](https://github.com/PrefectHQ/prefect/pull/15297)
* Make `prefect_test_harness` startup timeout configurable by [@desertaxle](https://github.com/desertaxle) in [#15354](https://github.com/PrefectHQ/prefect/pull/15354)
* Fix deployment-concurrency-limiting-GCL lifecycle management by [@collincchoy](https://github.com/collincchoy) in [#15365](https://github.com/PrefectHQ/prefect/pull/15365)
* `Runner` enforces `Deployment.concurrency_limit`  by [@jeanluciano](https://github.com/jeanluciano) in [#15085](https://github.com/PrefectHQ/prefect/pull/15085)
* Disable HTTP2 by default by [@zangell44](https://github.com/zangell44) in [#15311](https://github.com/PrefectHQ/prefect/pull/15311)

**Bug Fixes 🐞**

* Move expensive filter to AND by [@cicdw](https://github.com/cicdw) in [#15286](https://github.com/PrefectHQ/prefect/pull/15286)
* Fix deep merge for existing `env` on work-pools by [@zzstoatzz](https://github.com/zzstoatzz) in [#15325](https://github.com/PrefectHQ/prefect/pull/15325)
* Ensure all tags are used in concurrency limiter by [@cicdw](https://github.com/cicdw) in [#15349](https://github.com/PrefectHQ/prefect/pull/15349)
* Set propagate to false for extra loggers by [@cicdw](https://github.com/cicdw) in [#15348](https://github.com/PrefectHQ/prefect/pull/15348)
* Allow child transactions to access parent values set after child transaction opens by [@desertaxle](https://github.com/desertaxle) in [#15342](https://github.com/PrefectHQ/prefect/pull/15342)
* Fix resolution of implicit relative import when using `safe_load_namespace` by [@desertaxle](https://github.com/desertaxle) in [#15358](https://github.com/PrefectHQ/prefect/pull/15358)
* Correctly handles recurring automations and future events by [@chrisguidry](https://github.com/chrisguidry) in [#15355](https://github.com/PrefectHQ/prefect/pull/15355)

**Integrations & Dependencies 🤝**

* reintroduce job model for `prefect-databricks` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15313](https://github.com/PrefectHQ/prefect/pull/15313)
* Update `DbtCoreOperation` docstring by [@zzstoatzz](https://github.com/zzstoatzz) in [#15317](https://github.com/PrefectHQ/prefect/pull/15317)
* Move import from `google` into import guard by [@desertaxle](https://github.com/desertaxle) in [#15334](https://github.com/PrefectHQ/prefect/pull/15334)
* fix `S3Bucket.download_object_to_path` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15293](https://github.com/PrefectHQ/prefect/pull/15293)
* Fix issue where `DaskTaskRunner` was attempting to create a duplicate cluster by [@desertaxle](https://github.com/desertaxle) in [#15341](https://github.com/PrefectHQ/prefect/pull/15341)

**Development & Tidiness 🧹**

* Add dedicated enhancements section by [@cicdw](https://github.com/cicdw) in [#15265](https://github.com/PrefectHQ/prefect/pull/15265)
* Fix labeler job by [@cicdw](https://github.com/cicdw) in [#15114](https://github.com/PrefectHQ/prefect/pull/15114)
* Update @prefecthq/prefect-ui-library to version 3.8.2 by [@marvin-robot](https://github.com/marvin-robot) in [#15283](https://github.com/PrefectHQ/prefect/pull/15283)
* Refactor some concurrency utilities to be sync\_compatible by [@cicdw](https://github.com/cicdw) in [#15273](https://github.com/PrefectHQ/prefect/pull/15273)
* Add some more nuance to labeler by [@cicdw](https://github.com/cicdw) in [#15288](https://github.com/PrefectHQ/prefect/pull/15288)
* Use `ResultStore` by default for task transactions by [@desertaxle](https://github.com/desertaxle) in [#15264](https://github.com/PrefectHQ/prefect/pull/15264)
* Update @prefecthq/prefect-ui-library to version 3.8.3 by [@marvin-robot](https://github.com/marvin-robot) in [#15305](https://github.com/PrefectHQ/prefect/pull/15305)
* Remove feature flag for nested task runs on the run graph by [@pleek91](https://github.com/pleek91) in [#15304](https://github.com/PrefectHQ/prefect/pull/15304)
* Add deprecation warnings to all `RecordStore` implementations by [@desertaxle](https://github.com/desertaxle) in [#15314](https://github.com/PrefectHQ/prefect/pull/15314)
* Remove some ancient deprecations by [@cicdw](https://github.com/cicdw) in [#15310](https://github.com/PrefectHQ/prefect/pull/15310)
* Update @prefecthq/prefect-ui-library to version 3.9.1 by [@marvin-robot](https://github.com/marvin-robot) in [#15335](https://github.com/PrefectHQ/prefect/pull/15335)
* Replace `RedisRecordStore` with `RedisLockManager` by [@desertaxle](https://github.com/desertaxle) in [#15320](https://github.com/PrefectHQ/prefect/pull/15320)
* Add deprecation warnings to results classes and methods by [@desertaxle](https://github.com/desertaxle) in [#15323](https://github.com/PrefectHQ/prefect/pull/15323)
* Update @prefecthq/prefect-ui-library to version 3.9.2 by [@marvin-robot](https://github.com/marvin-robot) in [#15346](https://github.com/PrefectHQ/prefect/pull/15346)
* Update @prefecthq/prefect-ui-library to version 3.9.4 by [@marvin-robot](https://github.com/marvin-robot) in [#15356](https://github.com/PrefectHQ/prefect/pull/15356)
* Bump vue from 3.4.38 to 3.5.4 in /ui by [@dependabot](https://github.com/dependabot) in [#15306](https://github.com/PrefectHQ/prefect/pull/15306)
* Bump @vitejs/plugin-vue from 5.1.2 to 5.1.3 in /ui by [@dependabot](https://github.com/dependabot) in [#15173](https://github.com/PrefectHQ/prefect/pull/15173)
* Bump vue-tsc from 2.0.29 to 2.1.6 in /ui by [@dependabot](https://github.com/dependabot) in [#15281](https://github.com/PrefectHQ/prefect/pull/15281)
* Update transactions docs  by [@discdiver](https://github.com/discdiver) in [#15299](https://github.com/PrefectHQ/prefect/pull/15299)
* Add unit test for accessing `self` as normal arg when setting task run name by [@jlowin](https://github.com/jlowin) in [#15324](https://github.com/PrefectHQ/prefect/pull/15324)
* add `for_each` trigger example by [@zzstoatzz](https://github.com/zzstoatzz) in [#15326](https://github.com/PrefectHQ/prefect/pull/15326)
* Update logging.mdx to fix title display by [@discdiver](https://github.com/discdiver) in [#15360](https://github.com/PrefectHQ/prefect/pull/15360)
* quote type checked value by [@zzstoatzz](https://github.com/zzstoatzz) in [#15362](https://github.com/PrefectHQ/prefect/pull/15362)
* fix: move the github conditional to the appropriate level by [@jamiezieziula](https://github.com/jamiezieziula) in [#15366](https://github.com/PrefectHQ/prefect/pull/15366)
* Fix broken image link and update formatting in prefect-dbt by [@discdiver](https://github.com/discdiver) in [#15367](https://github.com/PrefectHQ/prefect/pull/15367)
* Update integrations docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#15303](https://github.com/PrefectHQ/prefect/pull/15303)
* Rewrite block page in docs by [@cicdw](https://github.com/cicdw) in [#15254](https://github.com/PrefectHQ/prefect/pull/15254)
* chore: only trigger helm release workflows on 3.x.x version releases by [@jamiezieziula](https://github.com/jamiezieziula) in [#15268](https://github.com/PrefectHQ/prefect/pull/15268)
* better common error section by [@zzstoatzz](https://github.com/zzstoatzz) in [#15271](https://github.com/PrefectHQ/prefect/pull/15271)
* fix inconsistent word in upgrade guide by [@zzstoatzz](https://github.com/zzstoatzz) in [#15277](https://github.com/PrefectHQ/prefect/pull/15277)
* Minor edits to the upgrade and what's new docs by [@discdiver](https://github.com/discdiver) in [#15285](https://github.com/PrefectHQ/prefect/pull/15285)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.1...3.0.2](https://github.com/PrefectHQ/prefect/compare/3.0.1...3.0.2)

***

## 3.0.1 - The Director's Cut

*Released on September 06, 2024*

This release contains a large collection of relatively small improvements and bug fixes on the back of our major 3.0.0 release.  One particular set of improvements that I'd like to focus on are enhancements to server side logging and event handling.  We received [a few reports](https://github.com/PrefectHQ/prefect/issues/15153) of task run states not showing up in the UI/API.  It's important to note that events - and now task run states! - require a websocket connection to the API (the good news is that this will *not* disrupt workflow execution).  Websockets are sometimes blocked by default in firewalls and network configuration, so we are working to raise failures to establish such a connection more prominently and potentially allow for alternative configurations.  If you notice any issues with this, [please let us know](https://github.com/PrefectHQ/prefect/issues/new/choose)!

**Enhancements ➕➕**

* update `prompt_select_from_table`  by [@zzstoatzz](https://github.com/zzstoatzz) in [#15202](https://github.com/PrefectHQ/prefect/pull/15202)
* Adds ability to write result metadata separate from data when using `ResultStore` by [@desertaxle](https://github.com/desertaxle) in [#15214](https://github.com/PrefectHQ/prefect/pull/15214)
* Remove `CausalOrdering` from `task-run-recorder` by [@jakekaplan](https://github.com/jakekaplan) in [#15244](https://github.com/PrefectHQ/prefect/pull/15244)
* Disable griffe logging entirely when used by [@cicdw](https://github.com/cicdw) in [#15193](https://github.com/PrefectHQ/prefect/pull/15193)
* Allow using a `ResultStore` with a `Transaction` by [@desertaxle](https://github.com/desertaxle) in [#15247](https://github.com/PrefectHQ/prefect/pull/15247)
* Introduce `LockManager` protocol and add locking abilities to `ResultStore` by [@desertaxle](https://github.com/desertaxle) in [#15225](https://github.com/PrefectHQ/prefect/pull/15225)
* check api compatibility when entering a client context by [@jakekaplan](https://github.com/jakekaplan) in [#15252](https://github.com/PrefectHQ/prefect/pull/15252)
* Add debug logging for server side event handling by [@jakekaplan](https://github.com/jakekaplan) in [#15245](https://github.com/PrefectHQ/prefect/pull/15245)

**Bug Fixes 🐞**

* Fix task key comp by [@cicdw](https://github.com/cicdw) in [#15190](https://github.com/PrefectHQ/prefect/pull/15190)
* Fix for Github clone on Windows by [@WWM-jschuba](https://github.com/WWM-jschuba) in [#15143](https://github.com/PrefectHQ/prefect/pull/15143)
* remove duplicate `pull_code` instruction by [@zzstoatzz](https://github.com/zzstoatzz) in [#15215](https://github.com/PrefectHQ/prefect/pull/15215)
* add function name to `prefect-docker` cache key by [@zzstoatzz](https://github.com/zzstoatzz) in [#15262](https://github.com/PrefectHQ/prefect/pull/15262)
* Deployment.concurrency\_limit cannot be zero. by [@collincchoy](https://github.com/collincchoy) in [#15228](https://github.com/PrefectHQ/prefect/pull/15228)

**Integrations & Dependencies 🤝**

* Add `KeepAliveClientRequest` class for k8s async client by [@kevingrismore](https://github.com/kevingrismore) in [#15220](https://github.com/PrefectHQ/prefect/pull/15220)
* Kubernetes worker uses `enable_socket_keep_alive` by [@jeanluciano](https://github.com/jeanluciano) in [#15142](https://github.com/PrefectHQ/prefect/pull/15142)
* `prefect-kubernetes`: add missing config loaders by [@srsapient](https://github.com/srsapient) in [#15209](https://github.com/PrefectHQ/prefect/pull/15209)
* fix `prefect-azure` tests by [@zzstoatzz](https://github.com/zzstoatzz) in [#15211](https://github.com/PrefectHQ/prefect/pull/15211)

**Development & Tidiness 🧹**

* Fix test flake and add `uv` dev dependency by [@cicdw](https://github.com/cicdw) in [#15251](https://github.com/PrefectHQ/prefect/pull/15251)
* Fix release pipeline for integration packages by [@desertaxle](https://github.com/desertaxle) in [#15189](https://github.com/PrefectHQ/prefect/pull/15189)
* Touch up variable class inheritance by [@cicdw](https://github.com/cicdw) in [#15188](https://github.com/PrefectHQ/prefect/pull/15188)
* Update @prefecthq/prefect-ui-library to version 3.8.1 by [@marvin-robot](https://github.com/marvin-robot) in [#15243](https://github.com/PrefectHQ/prefect/pull/15243)
* Fix test failures for `pydantic==2.9.0` by [@desertaxle](https://github.com/desertaxle) in [#15249](https://github.com/PrefectHQ/prefect/pull/15249)
* use `is not` for type comparison instead of `!=` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15253](https://github.com/PrefectHQ/prefect/pull/15253)
* Updates the worker integration tests for post-GA by [@chrisguidry](https://github.com/chrisguidry) in [#15199](https://github.com/PrefectHQ/prefect/pull/15199)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.0...3.0.1](https://github.com/PrefectHQ/prefect/compare/3.0.0...3.0.1)

***

## 3.0.0

*Released on September 03, 2024*

**Prefect 3.0.0**

For more information see [our blog post on 3.0](https://www.prefect.io/blog/prefect-3-generally-available-september-3).

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/2.19.0...3.0.0](https://github.com/PrefectHQ/prefect/compare/2.19.0...3.0.0)

***


# 3.1
Source: https://docs-3.prefect.io/v3/release-notes/oss/version-3-1



## 3.1.15 - The Numbers Are Made Up But The Features Are Real

*Released on January 30, 2025*

**Enhancements ➕➕**

* Trims Redis streams periodically while consuming by [@chrisguidry](https://github.com/chrisguidry) in [#16844](https://github.com/PrefectHQ/prefect/pull/16844)
* allow templating `schedules` in `prefect.yaml` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16867](https://github.com/PrefectHQ/prefect/pull/16867)
* Add `run_flow_in_subprocess` utility by [@desertaxle](https://github.com/desertaxle) in [#16802](https://github.com/PrefectHQ/prefect/pull/16802)
* expose ui/api urls in `prefect.runtime.task_run` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16879](https://github.com/PrefectHQ/prefect/pull/16879)
* Allow CLI to be invoked with `python -m prefect` by [@sky-code](https://github.com/sky-code) in [#16790](https://github.com/PrefectHQ/prefect/pull/16790)
* Add additional websocket debug logging by [@jakekaplan](https://github.com/jakekaplan) in [#16801](https://github.com/PrefectHQ/prefect/pull/16801)

**Bug Fixes 🐞**

* Add additional `validation_alias` to `SnowflakeConnector` by [@desertaxle](https://github.com/desertaxle) in [#16854](https://github.com/PrefectHQ/prefect/pull/16854)
* remove extra / old `prefect-dask` usage docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#16872](https://github.com/PrefectHQ/prefect/pull/16872)
* fix: check the type of dbt result when converting to markdown by [@dominictarro](https://github.com/dominictarro) in [#16869](https://github.com/PrefectHQ/prefect/pull/16869)
* Exclude `site-packages` from scanned dirs in `prefect deploy` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16885](https://github.com/PrefectHQ/prefect/pull/16885)
* Add missing overload for `Task.__call__` by [@desertaxle](https://github.com/desertaxle) in [#16891](https://github.com/PrefectHQ/prefect/pull/16891)
* use task groups for concurrent queue consumers by [@zzstoatzz](https://github.com/zzstoatzz) in [#16850](https://github.com/PrefectHQ/prefect/pull/16850)
* Upgrades `kubernetes-asyncio` version by [@jeanluciano](https://github.com/jeanluciano) in [#16841](https://github.com/PrefectHQ/prefect/pull/16841)
* Respect TLS\_SKIP\_VERIFY setting in websocket clients by [@cicdw](https://github.com/cicdw) in [#16908](https://github.com/PrefectHQ/prefect/pull/16908)
* Add event resources to the event cleanup cycle by [@NobisIndustries](https://github.com/NobisIndustries) in [#16907](https://github.com/PrefectHQ/prefect/pull/16907)
* Add section on UI settings for proxies by [@cicdw](https://github.com/cicdw) in [#16912](https://github.com/PrefectHQ/prefect/pull/16912)

**Integrations & Dependencies 🤝**

* Update typer requirement from !=0.12.2,`<0.14.0,>=0.12.0` to `>=0.12.0`,!=0.12.2,`<0.16.0` by [@dependabot](https://github.com/dependabot) in [#16205](https://github.com/PrefectHQ/prefect/pull/16205)
* Fix async dispatch for `prefect_aws` tasks by [@desertaxle](https://github.com/desertaxle) in [#16851](https://github.com/PrefectHQ/prefect/pull/16851)
* Add `PrefectDbtSettings` to `prefect-dbt` by [@kevingrismore](https://github.com/kevingrismore) in [#16834](https://github.com/PrefectHQ/prefect/pull/16834)
* Add support for secure Mattermost notifications by [@sochotnicky](https://github.com/sochotnicky) in [#16884](https://github.com/PrefectHQ/prefect/pull/16884)

**Development & Tidiness 🧹**

* Add `Flow.ato_deployment`, `Flow.afrom_source`, and `Runner.afrom_storage` by [@desertaxle](https://github.com/desertaxle) in [#16897](https://github.com/PrefectHQ/prefect/pull/16897)
* Move `pyright` checks to CI by [@desertaxle](https://github.com/desertaxle) in [#16843](https://github.com/PrefectHQ/prefect/pull/16843)
* rm deprecation warning for `schedule` key by [@zzstoatzz](https://github.com/zzstoatzz) in [#16847](https://github.com/PrefectHQ/prefect/pull/16847)
* Update CODEOWNERS for /docs by [@aaazzam](https://github.com/aaazzam) in [#16880](https://github.com/PrefectHQ/prefect/pull/16880)
* Fixes typing of `run_flow_in_subprocess` by [@desertaxle](https://github.com/desertaxle) in [#16883](https://github.com/PrefectHQ/prefect/pull/16883)
* Remove `[@sync](https://github.com/sync)_compatible` from `prefect.artifacts` by [@desertaxle](https://github.com/desertaxle) in [#16877](https://github.com/PrefectHQ/prefect/pull/16877)
* Update @prefecthq/prefect-ui-library to version 3.11.37 by [@marvin-robot](https://github.com/marvin-robot) in [#16894](https://github.com/PrefectHQ/prefect/pull/16894)
* Update @prefecthq/prefect-ui-library to version 3.11.38 by [@marvin-robot](https://github.com/marvin-robot) in [#16905](https://github.com/PrefectHQ/prefect/pull/16905)
* Introduces a `Service` base class to cover loop and other services by [@chrisguidry](https://github.com/chrisguidry) in [#16898](https://github.com/PrefectHQ/prefect/pull/16898)

**Experimental 🔬**

* \[Experimental] Enhancement: Lineage interface event names and context resource registration by [@znicholasbrown](https://github.com/znicholasbrown) in [#16842](https://github.com/PrefectHQ/prefect/pull/16842)
* \[Experimental] Include tags as related resources on lineage events by [@kevingrismore](https://github.com/kevingrismore) in [#16895](https://github.com/PrefectHQ/prefect/pull/16895)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.14...3.1.15](https://github.com/PrefectHQ/prefect/compare/3.1.14...3.1.15)

***

## 3.1.14 - Addition by Subtraction

*Released on January 23, 2025*

**Bug Fixes 🐞**

* respect `PREFECT_SERVER_LOGGING_LEVEL` in `prefect server start` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16765](https://github.com/PrefectHQ/prefect/pull/16765)
* don't make extra calls to cloud in `prefect dashboard open` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16768](https://github.com/PrefectHQ/prefect/pull/16768)
* Fix configuring loggers found in 'PREFECT\_LOGGING\_EXTRA\_LOGGERS' by [@estasney](https://github.com/estasney) in [#16652](https://github.com/PrefectHQ/prefect/pull/16652)
* Ensure multiple `Inputs` cache policies are consolidated when used in a `CompoundCachePolicy` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16785](https://github.com/PrefectHQ/prefect/pull/16785)
* Add missing function body import in client.find\_automation by [@aaazzam](https://github.com/aaazzam) in [#16824](https://github.com/PrefectHQ/prefect/pull/16824)
* Add auth string handling to server side client by [@cicdw](https://github.com/cicdw) in [#16833](https://github.com/PrefectHQ/prefect/pull/16833)
* Fix serialization for `FlowRunContext` for flow runs kicked off from a deployment by [@desertaxle](https://github.com/desertaxle) in [#16831](https://github.com/PrefectHQ/prefect/pull/16831)
* Fix subtraction logic on non-input cache policies by [@cicdw](https://github.com/cicdw) in [#16840](https://github.com/PrefectHQ/prefect/pull/16840)
* fix block cli error messages by [@aaazzam](https://github.com/aaazzam) in [#16787](https://github.com/PrefectHQ/prefect/pull/16787)

**Development & Tidiness 🧹**

* Fix typing of task decorator for retry\_condition\_fn argument by [@peterbygrave](https://github.com/peterbygrave) in [#16621](https://github.com/PrefectHQ/prefect/pull/16621)
* typing `cli.deploy` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16767](https://github.com/PrefectHQ/prefect/pull/16767)
* Fix all typing errors in `prefect.runner.runner` by [@desertaxle](https://github.com/desertaxle) in [#16797](https://github.com/PrefectHQ/prefect/pull/16797)
* Update @prefecthq/prefect-design to version 2.14.17 by [@marvin-robot](https://github.com/marvin-robot) in [#16830](https://github.com/PrefectHQ/prefect/pull/16830)
* No transaction in `TaskRunRecorder` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16829](https://github.com/PrefectHQ/prefect/pull/16829)
* Fix script to run server with local telemetry by [@zzstoatzz](https://github.com/zzstoatzz) in [#16794](https://github.com/PrefectHQ/prefect/pull/16794)
* Add the ability to pass context into the flow run engine by [@desertaxle](https://github.com/desertaxle) in [#16816](https://github.com/PrefectHQ/prefect/pull/16816)
* Ensures that the Redis messaging implementation works with event clients by [@chrisguidry](https://github.com/chrisguidry) in [#16832](https://github.com/PrefectHQ/prefect/pull/16832)
* start incremental `pendulum` consolidation by [@zzstoatzz](https://github.com/zzstoatzz) in [#16808](https://github.com/PrefectHQ/prefect/pull/16808)
* Add experimental function for connecting external lineage resources by [@kevingrismore](https://github.com/kevingrismore) in [#16820](https://github.com/PrefectHQ/prefect/pull/16820)
* Adds `prefect-redis` to the Prefect image by [@chrisguidry](https://github.com/chrisguidry) in [#16818](https://github.com/PrefectHQ/prefect/pull/16818)
* Stop making useless query by [@cicdw](https://github.com/cicdw) in [#16837](https://github.com/PrefectHQ/prefect/pull/16837)

**Documentation 📓**

* revamp integration contributor guide and clean up other sections by [@zzstoatzz](https://github.com/zzstoatzz) in [#16757](https://github.com/PrefectHQ/prefect/pull/16757)
* Update prefect-aws docs by [@seanpwlms](https://github.com/seanpwlms) in [#16639](https://github.com/PrefectHQ/prefect/pull/16639)
* Fix work pool types link in `Schedule a flow` tutorial by [@kevingrismore](https://github.com/kevingrismore) in [#16796](https://github.com/PrefectHQ/prefect/pull/16796)
* Add mini-history of Prefect to the introduction page of the docs by [@daniel-prefect](https://github.com/daniel-prefect) in [#16814](https://github.com/PrefectHQ/prefect/pull/16814)
* Add first draft of Coiled content to deployment documentation by [@mrocklin](https://github.com/mrocklin) in [#16805](https://github.com/PrefectHQ/prefect/pull/16805)
* docs(managed): add additional published ips by [@parkedwards](https://github.com/parkedwards) in [#16838](https://github.com/PrefectHQ/prefect/pull/16838)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.13...3.1.14](https://github.com/PrefectHQ/prefect/compare/3.1.13...3.1.14)

***

## 3.1.13 - type\_all\_the\_things: bool = True

*Released on January 17, 2025*

We're thrilled to announce a major milestone: `prefect` is now 100% type complete! 🎉  Every public interface in the library now includes comprehensive type annotations, bringing significant improvements to the developer experience. This means you'll enjoy:

* Enhanced autocompletion in your IDE, helping you write code faster and with fewer errors
* Robust static analysis through tools like `mypy` and `pyright`, catching potential issues before runtime
* Clear, unambiguous type signatures that serve as living documentation for the entire codebase

This achievement represents our commitment to building a more maintainable, reliable, and developer-friendly Python library.

**Enhancements ➕➕**

* Allow servers to start with no background services by [@cicdw](https://github.com/cicdw) in [#16693](https://github.com/PrefectHQ/prefect/pull/16693)
* Expose more SALAlchemy settings by [@cicdw](https://github.com/cicdw) in [#16742](https://github.com/PrefectHQ/prefect/pull/16742)
* Create model for SQLAlchemy connection arguments by [@cicdw](https://github.com/cicdw) in [#16762](https://github.com/PrefectHQ/prefect/pull/16762)
* Update SLA logic to use declarative endpoint by [@dylanbhughes](https://github.com/dylanbhughes) in [#16755](https://github.com/PrefectHQ/prefect/pull/16755)
* Add `prefect server services` CLI commands by [@zzstoatzz](https://github.com/zzstoatzz) in [#16706](https://github.com/PrefectHQ/prefect/pull/16706)
* Add provisioner for Coiled push work pools by [@ntabris](https://github.com/ntabris) in [#16736](https://github.com/PrefectHQ/prefect/pull/16736)

**Bug Fixes 🐞**

* Fix `SendgridEmail` code example by [@jakekaplan](https://github.com/jakekaplan) in [#16677](https://github.com/PrefectHQ/prefect/pull/16677)
* Fix connection string handling when individual components are provided via settings by [@desertaxle](https://github.com/desertaxle) in [#16680](https://github.com/PrefectHQ/prefect/pull/16680)
* Handles the instrumentation case where a future is only used to `wait_for` by [@chrisguidry](https://github.com/chrisguidry) in [#16709](https://github.com/PrefectHQ/prefect/pull/16709)
* Fix bug where a server can't be stopped and restarted without waiting several seconds by [@desertaxle](https://github.com/desertaxle) in [#15729](https://github.com/PrefectHQ/prefect/pull/15729)
* Fixes to Prefect Basic Auth by [@cicdw](https://github.com/cicdw) in [#16735](https://github.com/PrefectHQ/prefect/pull/16735)
* Switch `drain_all` call to be called from new thread instead of global loop thread by [@jeanluciano](https://github.com/jeanluciano) in [#16739](https://github.com/PrefectHQ/prefect/pull/16739)
* Ensures that `QueueService` instances are unique within types by [@chrisguidry](https://github.com/chrisguidry) in [#16751](https://github.com/PrefectHQ/prefect/pull/16751)

**Integrations & Dependencies 🤝**

* Bump lower bound on pydantic to 2.9 by [@cicdw](https://github.com/cicdw) in [#16691](https://github.com/PrefectHQ/prefect/pull/16691)

**Development & Tidiness 🧹**

* Remove DB interface from `_on_start` by [@cicdw](https://github.com/cicdw) in [#16687](https://github.com/PrefectHQ/prefect/pull/16687)
* Improve typing in `prefect.server.events` by [@desertaxle](https://github.com/desertaxle) in [#16692](https://github.com/PrefectHQ/prefect/pull/16692)
* Improve type completeness of `prefect.server.services` by [@desertaxle](https://github.com/desertaxle) in [#16701](https://github.com/PrefectHQ/prefect/pull/16701)
* Delete old create integrations cards script by [@desertaxle](https://github.com/desertaxle) in [#16704](https://github.com/PrefectHQ/prefect/pull/16704)
* Improve typing in `prefect.results` by [@desertaxle](https://github.com/desertaxle) in [#16714](https://github.com/PrefectHQ/prefect/pull/16714)
* Improve typing in server events - part deux by [@desertaxle](https://github.com/desertaxle) in [#16715](https://github.com/PrefectHQ/prefect/pull/16715)
* Improve typing of `prefect.settings` by [@desertaxle](https://github.com/desertaxle) in [#16719](https://github.com/PrefectHQ/prefect/pull/16719)
* Task engine typing by [@zzstoatzz](https://github.com/zzstoatzz) in [#16731](https://github.com/PrefectHQ/prefect/pull/16731)
* Raise type completeness on `prefect.inputs` to 100% by [@desertaxle](https://github.com/desertaxle) in [#16740](https://github.com/PrefectHQ/prefect/pull/16740)
* Raise type completeness to 95% by [@desertaxle](https://github.com/desertaxle) in [#16723](https://github.com/PrefectHQ/prefect/pull/16723)
* Raise type completeness of `prefect.server` to 100% by [@desertaxle](https://github.com/desertaxle) in [#16729](https://github.com/PrefectHQ/prefect/pull/16729)
* Raise type completeness to 99.8% by [@desertaxle](https://github.com/desertaxle) in [#16734](https://github.com/PrefectHQ/prefect/pull/16734)
* Add type completeness pre-commit hook by [@desertaxle](https://github.com/desertaxle) in [#16744](https://github.com/PrefectHQ/prefect/pull/16744)
* Add type hints to `CoiledPushProvisioner` by [@desertaxle](https://github.com/desertaxle) in [#16745](https://github.com/PrefectHQ/prefect/pull/16745)
* Deprecate custom `JsonPatch` implementation by [@desertaxle](https://github.com/desertaxle) in [#16743](https://github.com/PrefectHQ/prefect/pull/16743)

**Documentation 📓**

* Improve the intro to the quickstart tutorial by [@daniel-prefect](https://github.com/daniel-prefect) in [#16664](https://github.com/PrefectHQ/prefect/pull/16664)
* Update Intros in Docs by [@aaazzam](https://github.com/aaazzam) in [#16674](https://github.com/PrefectHQ/prefect/pull/16674)
* Update index.mdx by [@aaazzam](https://github.com/aaazzam) in [#16675](https://github.com/PrefectHQ/prefect/pull/16675)
* Remove the promise that the quickstart only takes five minutes to complete by [@daniel-prefect](https://github.com/daniel-prefect) in [#16669](https://github.com/PrefectHQ/prefect/pull/16669)
* Update prefect-yaml.mdx by [@adrianoresende](https://github.com/adrianoresende) in [#16688](https://github.com/PrefectHQ/prefect/pull/16688)
* Docs quickstart feedback by [@kevingrismore](https://github.com/kevingrismore) in [#16683](https://github.com/PrefectHQ/prefect/pull/16683)
* Fix silly typo by [@cicdw](https://github.com/cicdw) in [#16703](https://github.com/PrefectHQ/prefect/pull/16703)
* Move quickstart to immediately before the 'schedule a flow' tutorial in the docs by [@daniel-prefect](https://github.com/daniel-prefect) in [#16705](https://github.com/PrefectHQ/prefect/pull/16705)
* Add state transition table to 'Manage states' doc and link from the debug tutorial by [@daniel-prefect](https://github.com/daniel-prefect) in [#16668](https://github.com/PrefectHQ/prefect/pull/16668)
* Add an ML pipeline tutorial by [@daniel-prefect](https://github.com/daniel-prefect) in [#16632](https://github.com/PrefectHQ/prefect/pull/16632)
* Use Python 3.9 syntax and don't test 3rd-party dependencies by [@daniel-prefect](https://github.com/daniel-prefect) in [#16730](https://github.com/PrefectHQ/prefect/pull/16730)
* Add in documentation for Service Level Agreements by [@sam-phinizy](https://github.com/sam-phinizy) in [#16663](https://github.com/PrefectHQ/prefect/pull/16663)
* Use the flow from the quickstart as the basis for the deployment in the scheduling tutorial by [@daniel-prefect](https://github.com/daniel-prefect) in [#16721](https://github.com/PrefectHQ/prefect/pull/16721)
* Add correct probe config to `gcloud` example command by [@cicdw](https://github.com/cicdw) in [#16738](https://github.com/PrefectHQ/prefect/pull/16738)
* Docs: publish static outbound IP address for managed execution by [@parkedwards](https://github.com/parkedwards) in [#16741](https://github.com/PrefectHQ/prefect/pull/16741)
* Update settings docs with basic auth by [@cicdw](https://github.com/cicdw) in [#16753](https://github.com/PrefectHQ/prefect/pull/16753)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.12...3.1.13](https://github.com/PrefectHQ/prefect/compare/3.1.12...3.1.13)

***

## 3.1.12 - Winter Summit is Coming

*Released on January 09, 2025*

Please consider joining us virtually January 22-23 for our Winter Summit, where we'll be giving some exciting updates on our OSS community growth along with customer stories and updates on Prefect's roadmap! Check out the agenda and [register here](https://prefec.tv/4gLwglz).

**Enhancements ➕➕**

* rm `sync_compatible` from automations SDK by [@zzstoatzz](https://github.com/zzstoatzz) in [#16584](https://github.com/PrefectHQ/prefect/pull/16584)
* Log failures to load flow with flow run logger by [@cicdw](https://github.com/cicdw) in [#16647](https://github.com/PrefectHQ/prefect/pull/16647)
* Proposal: rename NONE cache\_policy to NO\_CACHE by [@cicdw](https://github.com/cicdw) in [#16650](https://github.com/PrefectHQ/prefect/pull/16650)
* Reduces the minimum memory requirement for Prefect Server by [@chrisguidry](https://github.com/chrisguidry) in [#16644](https://github.com/PrefectHQ/prefect/pull/16644)
* Reduces the memory requirement of a standalone Prefect server again by [@chrisguidry](https://github.com/chrisguidry) in [#16651](https://github.com/PrefectHQ/prefect/pull/16651)
* Deployment SLA Definitions by [@dylanbhughes](https://github.com/dylanbhughes) in [#16574](https://github.com/PrefectHQ/prefect/pull/16574)
* Add work pool type to related resource  by [@jakekaplan](https://github.com/jakekaplan) in [#16636](https://github.com/PrefectHQ/prefect/pull/16636)

**Bug Fixes 🐞**

* fix redis link by [@zzstoatzz](https://github.com/zzstoatzz) in [#16594](https://github.com/PrefectHQ/prefect/pull/16594)
* consolidate hook calling in flow engine by [@zzstoatzz](https://github.com/zzstoatzz) in [#16596](https://github.com/PrefectHQ/prefect/pull/16596)
* handle setting `enforce_parameter_schema` in `prefect.yaml` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16607](https://github.com/PrefectHQ/prefect/pull/16607)
* call `FlowRunContext.model_rebuild()` in `hydrate_context` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16628](https://github.com/PrefectHQ/prefect/pull/16628)
* Worker removes flow\_run id if fails to submit. by [@jeanluciano](https://github.com/jeanluciano) in [#16561](https://github.com/PrefectHQ/prefect/pull/16561)

**Integrations & Dependencies 🤝**

* Update croniter requirement from `<6.0.0,>=1.0.12` to `>=1.0.12,<7.0.0` by [@dependabot](https://github.com/dependabot) in [#16431](https://github.com/PrefectHQ/prefect/pull/16431)

**Development & Tidiness 🧹**

* server side type cleaning by [@zzstoatzz](https://github.com/zzstoatzz) in [#16583](https://github.com/PrefectHQ/prefect/pull/16583)
* Tune CI for efficiency by [@desertaxle](https://github.com/desertaxle) in [#16631](https://github.com/PrefectHQ/prefect/pull/16631)
* Add some tests for failure hooks and retries by [@cicdw](https://github.com/cicdw) in [#16642](https://github.com/PrefectHQ/prefect/pull/16642)
* Improve typing in `prefect.blocks` by [@desertaxle](https://github.com/desertaxle) in [#16630](https://github.com/PrefectHQ/prefect/pull/16630)
* Fix logging.yml comment by [@estasney](https://github.com/estasney) in [#16634](https://github.com/PrefectHQ/prefect/pull/16634)
* Refactor Deployment CRUD methods in client by [@aaazzam](https://github.com/aaazzam) in [#16576](https://github.com/PrefectHQ/prefect/pull/16576)
* Refactor Automations CRUD methods in client by [@aaazzam](https://github.com/aaazzam) in [#16579](https://github.com/PrefectHQ/prefect/pull/16579)
* cleanup a few refs by [@aaazzam](https://github.com/aaazzam) in [#16586](https://github.com/PrefectHQ/prefect/pull/16586)
* Refactor Flow and FlowRun CRUD methods in client by [@aaazzam](https://github.com/aaazzam) in [#16581](https://github.com/PrefectHQ/prefect/pull/16581)
* Refactor BlockType, BlockDocument, and BlockSchema CRUD methods in client  by [@aaazzam](https://github.com/aaazzam) in [#16587](https://github.com/PrefectHQ/prefect/pull/16587)
* Remove import dregs from client by [@aaazzam](https://github.com/aaazzam) in [#16604](https://github.com/PrefectHQ/prefect/pull/16604)
* small type fixes by [@zzstoatzz](https://github.com/zzstoatzz) in [#16646](https://github.com/PrefectHQ/prefect/pull/16646)

**Documentation 📓**

* remove hardcoded docs link to localhost:3000 by [@aaazzam](https://github.com/aaazzam) in [#16591](https://github.com/PrefectHQ/prefect/pull/16591)
* Remove code snippet from docs homepage by [@aaazzam](https://github.com/aaazzam) in [#16593](https://github.com/PrefectHQ/prefect/pull/16593)
* remove some integrations from docs by [@aaazzam](https://github.com/aaazzam) in [#16598](https://github.com/PrefectHQ/prefect/pull/16598)
* docs intro by [@aaazzam](https://github.com/aaazzam) in [#16601](https://github.com/PrefectHQ/prefect/pull/16601)
* add main features to docs index by [@aaazzam](https://github.com/aaazzam) in [#16603](https://github.com/PrefectHQ/prefect/pull/16603)
* Install `otel` extras in docker image and remove experimental flag setting by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16412](https://github.com/PrefectHQ/prefect/pull/16412)
* Update docs nav first links order  by [@discdiver](https://github.com/discdiver) in [#16624](https://github.com/PrefectHQ/prefect/pull/16624)
* Update runner docstring for clarity of their universality by [@cicdw](https://github.com/cicdw) in [#16662](https://github.com/PrefectHQ/prefect/pull/16662)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.11...3.1.12](https://github.com/PrefectHQ/prefect/compare/3.1.11...3.1.12)

***

## 3.1.11 - Flow-verload

*Released on January 02, 2025*

**Enhancements ➕➕**

* Sparse checkout for git pulls by [@tetracionist](https://github.com/tetracionist) in [#15824](https://github.com/PrefectHQ/prefect/pull/15824)
* Add a "limit" option prefect flow serve CLI by [@pwl](https://github.com/pwl) in [#16527](https://github.com/PrefectHQ/prefect/pull/16527)

**Bug Fixes 🐞**

* log rendered custom `flow_run_name` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16517](https://github.com/PrefectHQ/prefect/pull/16517)
* Server should exit with non-0 on error by [@martimors](https://github.com/martimors) in [#16476](https://github.com/PrefectHQ/prefect/pull/16476)
* Private submodule support for `GitRepository`  by [@jakekaplan](https://github.com/jakekaplan) in [#16518](https://github.com/PrefectHQ/prefect/pull/16518)
* Add support for `NO_PROXY` for websocket connections by [@jbw-vtl](https://github.com/jbw-vtl) in [#16538](https://github.com/PrefectHQ/prefect/pull/16538)
* Avoid `Path` interpreting `.` in deployment names as the beginning of a file extension by [@zzstoatzz](https://github.com/zzstoatzz) in [#16553](https://github.com/PrefectHQ/prefect/pull/16553)
* Fix task overload for decorator kwargs by [@zzstoatzz](https://github.com/zzstoatzz) in [#16540](https://github.com/PrefectHQ/prefect/pull/16540)
* RunTelemetry start span uses run name instead of flow/task name by [@jeanluciano](https://github.com/jeanluciano) in [#16389](https://github.com/PrefectHQ/prefect/pull/16389)

**Integrations & Dependencies 🤝**

* Fix `TypeError` in `SnowflakeConnector.fetch_all` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16511](https://github.com/PrefectHQ/prefect/pull/16511)
* Fix `fetch_one` and `fetch_many` in `prefect-snowflake` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16554](https://github.com/PrefectHQ/prefect/pull/16554)
* Add redis streams messaging to `redis-streams` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16432](https://github.com/PrefectHQ/prefect/pull/16432)

**Development & Tidiness 🧹**

* \[typing] prefect.concurrency by [@mjpieters](https://github.com/mjpieters) in [#16441](https://github.com/PrefectHQ/prefect/pull/16441)
* \[typing] prefect.\_internal, prefect.server.utilities by [@mjpieters](https://github.com/mjpieters) in [#16497](https://github.com/PrefectHQ/prefect/pull/16497)
* \[typing] - `prefect.cli` part 1 by [@desertaxle](https://github.com/desertaxle) in [#16546](https://github.com/PrefectHQ/prefect/pull/16546)
* Fix overloads for `wait_for` and `return_state` in  `Task.__call__` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16547](https://github.com/PrefectHQ/prefect/pull/16547)
* Add local-telemetry stack for investigating server performance by [@zzstoatzz](https://github.com/zzstoatzz) in [#16483](https://github.com/PrefectHQ/prefect/pull/16483)
* Refactor Client's Artifact CRUD methods into Mixin by [@aaazzam](https://github.com/aaazzam) in [#16496](https://github.com/PrefectHQ/prefect/pull/16496)
* Refactor Variable CRUD methods in client by [@aaazzam](https://github.com/aaazzam) in [#16564](https://github.com/PrefectHQ/prefect/pull/16564)
* Refactor Log CRUD methods in client by [@aaazzam](https://github.com/aaazzam) in [#16565](https://github.com/PrefectHQ/prefect/pull/16565)
* Correct link to contribution guidelines by [@jbw-vtl](https://github.com/jbw-vtl) in [#16539](https://github.com/PrefectHQ/prefect/pull/16539)
* Label all resources in lineage events by [@abrookins](https://github.com/abrookins) in [#16471](https://github.com/PrefectHQ/prefect/pull/16471)
* update readme by [@zzstoatzz](https://github.com/zzstoatzz) in [#16519](https://github.com/PrefectHQ/prefect/pull/16519)
* Remove deprecated result fields and classes and associated utilities by [@cicdw](https://github.com/cicdw) in [#16552](https://github.com/PrefectHQ/prefect/pull/16552)
* Add typing to model\_config by [@aaazzam](https://github.com/aaazzam) in [#16562](https://github.com/PrefectHQ/prefect/pull/16562)
* Refactor ConcurrencyLimit CRUD methods in client  by [@aaazzam](https://github.com/aaazzam) in [#16567](https://github.com/PrefectHQ/prefect/pull/16567)

**Documentation 📓**

* Update snowflake integration docs by [@seanpwlms](https://github.com/seanpwlms) in [#16556](https://github.com/PrefectHQ/prefect/pull/16556)

**v2 UI**

* feat: Updating tags and groups for ui-v2 dependabot by [@devinvillarosa](https://github.com/devinvillarosa) in [#16499](https://github.com/PrefectHQ/prefect/pull/16499)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.10...3.1.11](https://github.com/PrefectHQ/prefect/compare/3.1.10...3.1.11)

***

## 3.1.10 - Not a CPU was stirring, not even in prod

*Released on December 25, 2024*

*'Twas the night before Christmas, when through every cloud
Not a CPU was stirring, not even in prod*

**Bug Fixes 🐞**

* Remove FastAPI from prefect.flow's default import path. by [@aaazzam](https://github.com/aaazzam) in [#16473](https://github.com/PrefectHQ/prefect/pull/16473)
* fix incorrect use of `getattr` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16498](https://github.com/PrefectHQ/prefect/pull/16498)

**Development & Tidiness 🧹**

* \[typing] misc prefect modules by [@mjpieters](https://github.com/mjpieters) in [#16468](https://github.com/PrefectHQ/prefect/pull/16468)
* \[typing] update `prefect.futures` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16381](https://github.com/PrefectHQ/prefect/pull/16381)
* Bump astral-sh/setup-uv from 4 to 5 by [@dependabot](https://github.com/dependabot) in [#16478](https://github.com/PrefectHQ/prefect/pull/16478)
* address typing nits by [@zzstoatzz](https://github.com/zzstoatzz) in [#16495](https://github.com/PrefectHQ/prefect/pull/16495)
* Ensure client tests don't run with SQLite by [@desertaxle](https://github.com/desertaxle) in [#16488](https://github.com/PrefectHQ/prefect/pull/16488)

**Documentation 📓**

* fix link to `serve` docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#16475](https://github.com/PrefectHQ/prefect/pull/16475)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.9...3.1.10](https://github.com/PrefectHQ/prefect/compare/3.1.9...3.1.10)

***

## 3.1.9 - All I Want for Christmas is Queue

*Released on December 20, 2024*

**Enhancements ➕➕**

* Log exceptions when run submission fails in both the runner and worker by [@cicdw](https://github.com/cicdw) in [#16424](https://github.com/PrefectHQ/prefect/pull/16424)
* Refactor `prefect.flow` decorator by [@mjpieters](https://github.com/mjpieters) in [#16405](https://github.com/PrefectHQ/prefect/pull/16405)

**Bug Fixes 🐞**

* use correct async method on storage blocks by [@zzstoatzz](https://github.com/zzstoatzz) in [#16445](https://github.com/PrefectHQ/prefect/pull/16445)
* fix passing `enforce_parameter_schema` in `prefect deploy` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16418](https://github.com/PrefectHQ/prefect/pull/16418)
* make `from_source` safe to use concurrently by [@zzstoatzz](https://github.com/zzstoatzz) in [#16458](https://github.com/PrefectHQ/prefect/pull/16458)
* pass auth headers to `/csrf` by [@aaazzam](https://github.com/aaazzam) in [#16464](https://github.com/PrefectHQ/prefect/pull/16464)

**Integrations & Dependencies 🤝**

* fix `MattermostWebhook` tests  by [@zzstoatzz](https://github.com/zzstoatzz) in [#16433](https://github.com/PrefectHQ/prefect/pull/16433)
* Add redis causal ordering implementation by [@zangell44](https://github.com/zangell44) in [#16416](https://github.com/PrefectHQ/prefect/pull/16416)
* Wrap `OTLPLogExporter` and `OTLPSpanExporter` in a `QueueService` to pull them out of the main thread by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16439](https://github.com/PrefectHQ/prefect/pull/16439)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-ui-library to version 3.11.28 by [@marvin-robot](https://github.com/marvin-robot) in [#16437](https://github.com/PrefectHQ/prefect/pull/16437)
* Update worker to use orchestration client for updating labels by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16426](https://github.com/PrefectHQ/prefect/pull/16426)
* \[typing] Remove overload from inject\_client by [@mjpieters](https://github.com/mjpieters) in [#16463](https://github.com/PrefectHQ/prefect/pull/16463)
* \[typing] prefect.exceptions by [@mjpieters](https://github.com/mjpieters) in [#16456](https://github.com/PrefectHQ/prefect/pull/16456)
* \[typing] Annotate all getattr\_migration callsites by [@mjpieters](https://github.com/mjpieters) in [#16457](https://github.com/PrefectHQ/prefect/pull/16457)
* \[typing] clean up prefect **init**.py by [@mjpieters](https://github.com/mjpieters) in [#16451](https://github.com/PrefectHQ/prefect/pull/16451)
* Update @prefecthq/prefect-ui-library to version 3.11.30 by [@marvin-robot](https://github.com/marvin-robot) in [#16470](https://github.com/PrefectHQ/prefect/pull/16470)

**Documentation 📓**

* Add an example for creating an automation to mark zombie flow runs as crashed by [@desertaxle](https://github.com/desertaxle) in [#16425](https://github.com/PrefectHQ/prefect/pull/16425)
* Add a tutorial showing how to set up an email alert in Prefect Cloud by [@daniel-prefect](https://github.com/daniel-prefect) in [#16345](https://github.com/PrefectHQ/prefect/pull/16345)
* Add tutorials to the overview page of the docs by [@daniel-prefect](https://github.com/daniel-prefect) in [#16454](https://github.com/PrefectHQ/prefect/pull/16454)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.8...3.1.9](https://github.com/PrefectHQ/prefect/compare/3.1.8...3.1.9)

***

## 3.1.8 - A Tale of Two Features

*Released on December 17, 2024*

**Runner Heartbeats for Flow Run Monitoring**

Flow runs can now emit heartbeat events to detect infrastructure failures (crashed machines, evicted containers, etc). When enabled, an automation can automatically mark flows as crashed when heartbeats stop, preventing stuck "zombie" flows in the running state.

Enable with:

* Set `PREFECT_RUNNER_HEARTBEAT_FREQUENCY` (requires Prefect 3.1.8+)
* Deploy the provided automation script to update flow states when heartbeats stop

```python
from prefect.automations import Automation
from prefect.client.schemas.objects import StateType
from prefect.events.actions import ChangeFlowRunState
from prefect.events.schemas.automations import EventTrigger, Posture

my_automation = Automation(
    name="Crash zombie flows",
    trigger=EventTrigger(
        after={"prefect.flow-run.heartbeat"},
        expect={
            "prefect.flow-run.heartbeat",
            "prefect.flow-run.Completed",
            "prefect.flow-run.Failed",
            "prefect.flow-run.Cancelled",
            "prefect.flow-run.Crashed",
        },
        match={"prefect.resource.id": ["prefect.flow-run.*"]},
        for_each={"prefect.resource.id"},
        posture=Posture.Proactive,
        threshold=1,
        within=90,
    ),
    actions=[
        ChangeFlowRunState(
            state=StateType.CRASHED,
            message="Flow run marked as crashed due to missing heartbeats.",
        )
    ],
)

my_automation.create()
```

**Basic Authentication**

We have also added a long requested feature: basic authentication support for the Prefect API. Enable by setting an auth string:

Start a protected server:

```bash
PREFECT_SERVER_API_AUTH_STRING="admin:admin" prefect server start
```

Authenticate client operations:

```bash
PREFECT_API_AUTH_STRING="admin:admin" python flow_script.py
```

**Enhancements ➕➕**

* Add working implementation of basic auth to server and client by [@cicdw](https://github.com/cicdw) in [#16408](https://github.com/PrefectHQ/prefect/pull/16408)
* Add basic auth UI by [@aaazzam](https://github.com/aaazzam) in [#16411](https://github.com/PrefectHQ/prefect/pull/16411)
* Enhance `Runner` to send heartbeat events for flow runs by [@desertaxle](https://github.com/desertaxle) in [#16410](https://github.com/PrefectHQ/prefect/pull/16410)

**Integrations & Dependencies 🤝**

* add async redis client utils to `prefect-redis` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16417](https://github.com/PrefectHQ/prefect/pull/16417)

**Documentation 📓**

* Add state change diagram by [@mthatt](https://github.com/mthatt) in [#16421](https://github.com/PrefectHQ/prefect/pull/16421)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.7...3.1.8](https://github.com/PrefectHQ/prefect/compare/3.1.7...3.1.8)

***

## 3.1.7 - Straight outta Half Moon Bay

*Released on December 16, 2024*

**Enhancements ➕➕**

* Support http proxies for websockets by [@jakekaplan](https://github.com/jakekaplan) in [#16326](https://github.com/PrefectHQ/prefect/pull/16326)
* update contributor dev instructions by [@zzstoatzz](https://github.com/zzstoatzz) in [#16376](https://github.com/PrefectHQ/prefect/pull/16376)

**Bug Fixes 🐞**

* Fix missing terminal state timings for TimedOut tasks by [@GalLadislav](https://github.com/GalLadislav) in [#16328](https://github.com/PrefectHQ/prefect/pull/16328)
* Early error on bad retry delay types by [@cicdw](https://github.com/cicdw) in [#16369](https://github.com/PrefectHQ/prefect/pull/16369)
* \[typing] add overload for empty `[@task](https://github.com/task)` decorator by [@zzstoatzz](https://github.com/zzstoatzz) in [#16386](https://github.com/PrefectHQ/prefect/pull/16386)
* Use `websocket_connect` utility in `Subscriptions` by [@jakekaplan](https://github.com/jakekaplan) in [#16388](https://github.com/PrefectHQ/prefect/pull/16388)
* dont ask to confirm deletion of non-existent gcl by [@zzstoatzz](https://github.com/zzstoatzz) in [#16379](https://github.com/PrefectHQ/prefect/pull/16379)

**Development & Tidiness 🧹**

* Add `Block.aload` method and remove `[@sync](https://github.com/sync)_compatible` from `Block.load` by [@desertaxle](https://github.com/desertaxle) in [#16341](https://github.com/PrefectHQ/prefect/pull/16341)
* Exclude UI v2 PRs from the release notes auto-generation by [@desertaxle](https://github.com/desertaxle) in [#16344](https://github.com/PrefectHQ/prefect/pull/16344)
* remove `sync_compatible` from `git_clone` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16340](https://github.com/PrefectHQ/prefect/pull/16340)
* \[typing] `prefect.serializers` by [@desertaxle](https://github.com/desertaxle) in [#16331](https://github.com/PrefectHQ/prefect/pull/16331)
* remove `sync_compatible` from `prefect.variables` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16349](https://github.com/PrefectHQ/prefect/pull/16349)
* Consolidate use of `DateTime` to `prefect.types` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16356](https://github.com/PrefectHQ/prefect/pull/16356)
* Fix type analysis check for PRs from forks by [@desertaxle](https://github.com/desertaxle) in [#16359](https://github.com/PrefectHQ/prefect/pull/16359)
* improve `Dockerfile` build time and add CI to catch future slow downs by [@zzstoatzz](https://github.com/zzstoatzz) in [#16348](https://github.com/PrefectHQ/prefect/pull/16348)
* Add buffer to type completeness check by [@desertaxle](https://github.com/desertaxle) in [#16361](https://github.com/PrefectHQ/prefect/pull/16361)
* only run docker build bench on push to main by [@zzstoatzz](https://github.com/zzstoatzz) in [#16365](https://github.com/PrefectHQ/prefect/pull/16365)
* \[typing] `prefect.tasks` and `prefect.task_worker` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16332](https://github.com/PrefectHQ/prefect/pull/16332)
* update `entrypoint.sh` to use `uv` for `EXTRA_PIP_PACKAGES` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16291](https://github.com/PrefectHQ/prefect/pull/16291)
* update example output for `prefect work-pool inspect` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16378](https://github.com/PrefectHQ/prefect/pull/16378)
* \[typing] prefect.server.utilities.database by [@mjpieters](https://github.com/mjpieters) in [#16368](https://github.com/PrefectHQ/prefect/pull/16368)
* Pick up trace context from run labels by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16346](https://github.com/PrefectHQ/prefect/pull/16346)
* Refactor db\_injector decorator by [@mjpieters](https://github.com/mjpieters) in [#16390](https://github.com/PrefectHQ/prefect/pull/16390)
* Correctly maintain span hierarchy when instrumenting nested tasks/flows by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16384](https://github.com/PrefectHQ/prefect/pull/16384)

**Documentation 📓**

* Remove missing page from the nav by [@daniel-prefect](https://github.com/daniel-prefect) in [#16351](https://github.com/PrefectHQ/prefect/pull/16351)
* Update flow run instrumentation to use `RunTelemetry` class by [@jeanluciano](https://github.com/jeanluciano) in [#16233](https://github.com/PrefectHQ/prefect/pull/16233)
* Add experimental support for emitting lineage events by [@abrookins](https://github.com/abrookins) in [#16242](https://github.com/PrefectHQ/prefect/pull/16242)
* update tutorial for clarity by [@zzstoatzz](https://github.com/zzstoatzz) in [#16354](https://github.com/PrefectHQ/prefect/pull/16354)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.6...3.1.7](https://github.com/PrefectHQ/prefect/compare/3.1.6...3.1.7)

***

## 3.1.6 - list\[type\[Improvements]]

*Released on December 11, 2024*

This release begins a concerted effort to improve our public interface's type completeness; we hope that this will make the experience of authoring Prefect flows within IDEs more robust and allow for better autocomplete. We welcome all contributions to this effort - [follow along with this issue to get involved](https://github.com/PrefectHQ/prefect/issues/16292)!

**Enhancements ➕➕**

* expose `job_variables` in `runtime.flow_run` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16124](https://github.com/PrefectHQ/prefect/pull/16124)
* Add `aserve` utility for serving multiple flows from an asynchronous context by [@GitAlexxx](https://github.com/GitAlexxx) in [#15972](https://github.com/PrefectHQ/prefect/pull/15972)
* Add work-pool id/name to labels donated by worker to flow run by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16252](https://github.com/PrefectHQ/prefect/pull/16252)
* Raise informative errors when failing to bootstrap telemetry by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16253](https://github.com/PrefectHQ/prefect/pull/16253)
* remove `sync_compatible` from `build_server` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16314](https://github.com/PrefectHQ/prefect/pull/16314)

**Bug Fixes 🐞**

* Fix setting task states with duplicate timestamps by [@GalLadislav](https://github.com/GalLadislav) in [#16145](https://github.com/PrefectHQ/prefect/pull/16145)
* fix `__getattr__` conflict in `prefect.docker.__init__` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16172](https://github.com/PrefectHQ/prefect/pull/16172)
* Fix result store serialization to include all necessary attributes by [@desertaxle](https://github.com/desertaxle) in [#16189](https://github.com/PrefectHQ/prefect/pull/16189)
* Support flow deletion in Prefect Python client by [@paulusaptus](https://github.com/paulusaptus) in [#16308](https://github.com/PrefectHQ/prefect/pull/16308)

**Integrations & Dependencies 🤝**

* bump required minor versions of core by [@zzstoatzz](https://github.com/zzstoatzz) in [#16192](https://github.com/PrefectHQ/prefect/pull/16192)
* Instrument task runs by [@jeanluciano](https://github.com/jeanluciano) in [#15955](https://github.com/PrefectHQ/prefect/pull/15955)

**Development & Tidiness 🧹**

* clean up repo root by [@zzstoatzz](https://github.com/zzstoatzz) in [#16177](https://github.com/PrefectHQ/prefect/pull/16177)
* rm discourse references by [@zzstoatzz](https://github.com/zzstoatzz) in [#16176](https://github.com/PrefectHQ/prefect/pull/16176)
* limit event name length by [@zzstoatzz](https://github.com/zzstoatzz) in [#16097](https://github.com/PrefectHQ/prefect/pull/16097)
* Add `from_profiles_yml` to dbt `TargetConfigs` by [@kevingrismore](https://github.com/kevingrismore) in [#16178](https://github.com/PrefectHQ/prefect/pull/16178)
* Rename `prefect.server.database.migrations` to `prefect.server.database._migrations` by [@desertaxle](https://github.com/desertaxle) in [#16214](https://github.com/PrefectHQ/prefect/pull/16214)
* Improve typing completeness of internal base models by [@desertaxle](https://github.com/desertaxle) in [#16217](https://github.com/PrefectHQ/prefect/pull/16217)
* update typing in `blocks.abstract` and `concurrency` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16212](https://github.com/PrefectHQ/prefect/pull/16212)
* strict type client modules by [@zzstoatzz](https://github.com/zzstoatzz) in [#16223](https://github.com/PrefectHQ/prefect/pull/16223)
* Bring ORM models and Alembic migrations in sync by [@mjpieters](https://github.com/mjpieters) in [#16221](https://github.com/PrefectHQ/prefect/pull/16221)
* Include info about registering built-in blocks by [@pypae](https://github.com/pypae) in [#16244](https://github.com/PrefectHQ/prefect/pull/16244)
* Move UI pre-commit hooks from `husky` to `pre-commit` by [@desertaxle](https://github.com/desertaxle) in [#16246](https://github.com/PrefectHQ/prefect/pull/16246)
* make `flow` and `task` decorators pass strict typing by [@zzstoatzz](https://github.com/zzstoatzz) in [#16251](https://github.com/PrefectHQ/prefect/pull/16251)
* use `uv` to install dependencies in the `Dockerfile` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16235](https://github.com/PrefectHQ/prefect/pull/16235)
* fruitful typing scouring by [@zzstoatzz](https://github.com/zzstoatzz) in [#16255](https://github.com/PrefectHQ/prefect/pull/16255)
* \[typing] prefect.client by [@mjpieters](https://github.com/mjpieters) in [#16265](https://github.com/PrefectHQ/prefect/pull/16265)
* OTEL flow run context propagation with Labels by [@jeanluciano](https://github.com/jeanluciano) in [#16122](https://github.com/PrefectHQ/prefect/pull/16122)
* Link Docker build `NODE_VERSION` to `.nvmrc` by [@desertaxle](https://github.com/desertaxle) in [#16282](https://github.com/PrefectHQ/prefect/pull/16282)
* fix typing and route in flow run logs download api ref by [@zzstoatzz](https://github.com/zzstoatzz) in [#16281](https://github.com/PrefectHQ/prefect/pull/16281)
* avoiding timing issue in flaky test by [@zzstoatzz](https://github.com/zzstoatzz) in [#16275](https://github.com/PrefectHQ/prefect/pull/16275)
* Add a new tutorial which shows how to debug a failing pipeline by [@daniel-prefect](https://github.com/daniel-prefect) in [#16225](https://github.com/PrefectHQ/prefect/pull/16225)
* Adds note to rate limits doc linking to client settings by [@EmilRex](https://github.com/EmilRex) in [#16286](https://github.com/PrefectHQ/prefect/pull/16286)
* \[typing] fix typing related to `prefect.main` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16288](https://github.com/PrefectHQ/prefect/pull/16288)
* 3.9 compat for `debug.mdx` tutorial by [@zzstoatzz](https://github.com/zzstoatzz) in [#16296](https://github.com/PrefectHQ/prefect/pull/16296)
* Include more helpful output in type completeness check by [@desertaxle](https://github.com/desertaxle) in [#16327](https://github.com/PrefectHQ/prefect/pull/16327)
* Temporarily disable passing worker labels to flow run by [@jakekaplan](https://github.com/jakekaplan) in [#16339](https://github.com/PrefectHQ/prefect/pull/16339)
* Add type completeness check to CI by [@desertaxle](https://github.com/desertaxle) in [#16194](https://github.com/PrefectHQ/prefect/pull/16194)
* improve typing of variables.py by [@aaazzam](https://github.com/aaazzam) in [#16216](https://github.com/PrefectHQ/prefect/pull/16216)
* Use SQLAlchemy 2.0 style for ORM models, make typing complete by [@mjpieters](https://github.com/mjpieters) in [#16230](https://github.com/PrefectHQ/prefect/pull/16230)
* \[typing] highlighters.py by [@aaazzam](https://github.com/aaazzam) in [#16259](https://github.com/PrefectHQ/prefect/pull/16259)
* \[typing] Update migration.py by [@aaazzam](https://github.com/aaazzam) in [#16261](https://github.com/PrefectHQ/prefect/pull/16261)
* \[typing] effect by [@aaazzam](https://github.com/aaazzam) in [#16266](https://github.com/PrefectHQ/prefect/pull/16266)
* \[typing] Use correct type narrowing construct by [@mjpieters](https://github.com/mjpieters) in [#16269](https://github.com/PrefectHQ/prefect/pull/16269)
* \[typing] prefect.utilities by [@mjpieters](https://github.com/mjpieters) in [#16298](https://github.com/PrefectHQ/prefect/pull/16298)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.5...3.1.6](https://github.com/PrefectHQ/prefect/compare/3.1.5...3.1.6)

***

## 3.1.5 - Like Leftovers, But Async (No More Pi)

*Released on December 03, 2024*

**Enhancements ➕➕**

* allow filtering by flow run tags via `any_` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16072](https://github.com/PrefectHQ/prefect/pull/16072)
* migrate `prefect_aws.s3` async tasks to `async_dispatch` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16096](https://github.com/PrefectHQ/prefect/pull/16096)
* Add debug log for global concurrency limit wait by [@EmilRex](https://github.com/EmilRex) in [#16077](https://github.com/PrefectHQ/prefect/pull/16077)
* Asyncify the flow run engine by [@desertaxle](https://github.com/desertaxle) in [#16095](https://github.com/PrefectHQ/prefect/pull/16095)
* Improve scheduled flows query by [@desertaxle](https://github.com/desertaxle) in [#16132](https://github.com/PrefectHQ/prefect/pull/16132)

**Bug Fixes 🐞**

* Fallback to default profile when profiles file is empty by [@desertaxle](https://github.com/desertaxle) in [#16119](https://github.com/PrefectHQ/prefect/pull/16119)
* Fix error when listing workspaces without an active workspace by [@desertaxle](https://github.com/desertaxle) in [#16130](https://github.com/PrefectHQ/prefect/pull/16130)
* fix ssl verify and update tests by [@zzstoatzz](https://github.com/zzstoatzz) in [#16149](https://github.com/PrefectHQ/prefect/pull/16149)
* Stop running all services in ephemeral app by [@cicdw](https://github.com/cicdw) in [#16120](https://github.com/PrefectHQ/prefect/pull/16120)

**Integrations & Dependencies 🤝**

* migrate `prefect_aws.client_waiter` off `sync_compatible` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16082](https://github.com/PrefectHQ/prefect/pull/16082)
* migrate `prefect_aws.lambda_function` off `sync_compatible` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16083](https://github.com/PrefectHQ/prefect/pull/16083)
* revert `pydantic==2.10.0` workaround given upstream fix by [@zzstoatzz](https://github.com/zzstoatzz) in [#16087](https://github.com/PrefectHQ/prefect/pull/16087)
* migrate `prefect_aws.secrets_manager` off `sync_compatible` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16169](https://github.com/PrefectHQ/prefect/pull/16169)

**Development & Tidiness 🧹**

* \[UI v2] Move delete variable mutation to variable hooks module by [@desertaxle](https://github.com/desertaxle) in [#16141](https://github.com/PrefectHQ/prefect/pull/16141)
* \[UI v2] feat: Introducing declarative useSet custom hook and replacing selected tags state for this hook by [@devinvillarosa](https://github.com/devinvillarosa) in [#16143](https://github.com/PrefectHQ/prefect/pull/16143)
* \[UI v2] feat: Use queryOptions API to define queries by [@devinvillarosa](https://github.com/devinvillarosa) in [#16133](https://github.com/PrefectHQ/prefect/pull/16133)
* \[UI v2] dev: Adds tanstack query eslint rules and updates docs for variable mutations by [@devinvillarosa](https://github.com/devinvillarosa) in [#16157](https://github.com/PrefectHQ/prefect/pull/16157)
* Minor docs IA clean up by [@daniel-prefect](https://github.com/daniel-prefect) in [#16073](https://github.com/PrefectHQ/prefect/pull/16073)
* Implement `labels` field on Flow, Deployment, FlowRun, and TaskRun by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16050](https://github.com/PrefectHQ/prefect/pull/16050)
* Fix redirect by [@discdiver](https://github.com/discdiver) in [#16092](https://github.com/PrefectHQ/prefect/pull/16092)
* Create `BaseFlowRunEngine` and `AsyncFlowRunEngine` shell by [@desertaxle](https://github.com/desertaxle) in [#16091](https://github.com/PrefectHQ/prefect/pull/16091)
* \[UI v2] Edit variables by [@desertaxle](https://github.com/desertaxle) in [#16035](https://github.com/PrefectHQ/prefect/pull/16035)
* \[UI v2] Refactor parts of variables components by [@desertaxle](https://github.com/desertaxle) in [#16084](https://github.com/PrefectHQ/prefect/pull/16084)
* added noZoom tag to integration images by [@markupboy](https://github.com/markupboy) in [#16107](https://github.com/PrefectHQ/prefect/pull/16107)
* \[UI v2] feat: Adds tanstack query dev tools for development mode by [@devinvillarosa](https://github.com/devinvillarosa) in [#16131](https://github.com/PrefectHQ/prefect/pull/16131)
* \[UI v2] feat: Have UX related mutation callbacks be handled in the UX layer by [@devinvillarosa](https://github.com/devinvillarosa) in [#16136](https://github.com/PrefectHQ/prefect/pull/16136)
* rm docs referencing `incidents` by [@aaazzam](https://github.com/aaazzam) in [#16139](https://github.com/PrefectHQ/prefect/pull/16139)
* \[UI v2] feat: simplifies invalidating all variable queries by [@devinvillarosa](https://github.com/devinvillarosa) in [#16140](https://github.com/PrefectHQ/prefect/pull/16140)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.4...3.1.5](https://github.com/PrefectHQ/prefect/compare/3.1.4...3.1.5)

***

## 3.1.4 - Schrödinger's Labels

*Released on November 21, 2024*

**Enhancements ➕➕**

* Omit empty tags in `RunnerDeployment` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16075](https://github.com/PrefectHQ/prefect/pull/16075)

**Bug Fixes 🐞**

* Cast `None -> {}` in `KeyValueLabels` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16067](https://github.com/PrefectHQ/prefect/pull/16067)
* Fix `pydantic==2.10` compatibility by [@zzstoatzz](https://github.com/zzstoatzz) in [#16076](https://github.com/PrefectHQ/prefect/pull/16076)

**Integrations & Dependencies 🤝**

* Update `prefect` pin to `>=3.1.3` in `prefect-aws` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16064](https://github.com/PrefectHQ/prefect/pull/16064)
* Update `AzureBlobStorageCredentials` to close default credentials when used as a context manager by [@desertaxle](https://github.com/desertaxle) in [#16071](https://github.com/PrefectHQ/prefect/pull/16071)

**Development & Tidiness 🧹**

* New author tutorials by [@daniel-prefect](https://github.com/daniel-prefect) in [#15990](https://github.com/PrefectHQ/prefect/pull/15990)
* Update broken internal links in the docs by [@discdiver](https://github.com/discdiver) in [#16063](https://github.com/PrefectHQ/prefect/pull/16063)
* Remove last remaining links to `/docs/3.0` by [@daniel-prefect](https://github.com/daniel-prefect) in [#16058](https://github.com/PrefectHQ/prefect/pull/16058)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.3...3.1.4](https://github.com/PrefectHQ/prefect/compare/3.1.3...3.1.4)

***

## 3.1.3 - Queue The Improvements

*Released on November 19, 2024*

**Enhancements ➕➕**

* helpful error on unhashable parameters by [@zzstoatzz](https://github.com/zzstoatzz) in [#16049](https://github.com/PrefectHQ/prefect/pull/16049)
* Add `new` action to `OpsGenieWebhook` for `apprise==1.9.0` compatibility by [@kevingrismore](https://github.com/kevingrismore) in [#16030](https://github.com/PrefectHQ/prefect/pull/16030)

**Bug Fixes 🐞**

* Adds a dead-letter queue to memory subscriptions to avoid infinite loops by [@desertaxle](https://github.com/desertaxle) in [#16051](https://github.com/PrefectHQ/prefect/pull/16051)
* make sure workers emit stop events by [@zzstoatzz](https://github.com/zzstoatzz) in [#16002](https://github.com/PrefectHQ/prefect/pull/16002)
* handle UNC paths for windows by [@zzstoatzz](https://github.com/zzstoatzz) in [#16005](https://github.com/PrefectHQ/prefect/pull/16005)
* fix worker not releasing limit slot on failed propose pending state by [@jdjfisher](https://github.com/jdjfisher) in [#16012](https://github.com/PrefectHQ/prefect/pull/16012)
* refactor: gcp cloud run v2 extend env vars and fix cloud sql by [@matmiad](https://github.com/matmiad) in [#16026](https://github.com/PrefectHQ/prefect/pull/16026)
* Fix env var deep merge order on worker by [@kevingrismore](https://github.com/kevingrismore) in [#16045](https://github.com/PrefectHQ/prefect/pull/16045)
* Prevent workers from running flow runs scheduled for in process retry by [@desertaxle](https://github.com/desertaxle) in [#15482](https://github.com/PrefectHQ/prefect/pull/15482)

**Integrations & Dependencies 🤝**

* fix: `prefect_redis` use of `async` by [@teocns](https://github.com/teocns) in [#15967](https://github.com/PrefectHQ/prefect/pull/15967)
* Update croniter requirement from `<5.0.0,>=1.0.12` to `>=1.0.12,<6.0.0` by [@dependabot](https://github.com/dependabot) in [#15856](https://github.com/PrefectHQ/prefect/pull/15856)
* Add Flow run OTEL instrumentation by [@collincchoy](https://github.com/collincchoy) in [#16010](https://github.com/PrefectHQ/prefect/pull/16010)
* refactor `async_dispatch` to enable forcing behavior for instance methods by [@zzstoatzz](https://github.com/zzstoatzz) in [#15996](https://github.com/PrefectHQ/prefect/pull/15996)
* Bump cross-spawn from 7.0.3 to 7.0.6 in /ui-v2 by [@dependabot](https://github.com/dependabot) in [#16048](https://github.com/PrefectHQ/prefect/pull/16048)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-design to version 2.14.10 by [@marvin-robot](https://github.com/marvin-robot) in [#16004](https://github.com/PrefectHQ/prefect/pull/16004)
* Fix formatting for output file tree structure in customize.mdx by [@discdiver](https://github.com/discdiver) in [#16006](https://github.com/PrefectHQ/prefect/pull/16006)
* Update @prefecthq/prefect-design to version 2.14.11 by [@marvin-robot](https://github.com/marvin-robot) in [#16028](https://github.com/PrefectHQ/prefect/pull/16028)
* Remove experimental worker logs setting by [@abrookins](https://github.com/abrookins) in [#16024](https://github.com/PrefectHQ/prefect/pull/16024)
* Update @prefecthq/prefect-ui-library to version 3.11.19 by [@marvin-robot](https://github.com/marvin-robot) in [#16029](https://github.com/PrefectHQ/prefect/pull/16029)
* Update links in blocks to not point to docs from archived repositories by [@discdiver](https://github.com/discdiver) in [#16031](https://github.com/PrefectHQ/prefect/pull/16031)
* Move installation notes to bottom of self-host doc by [@jlowin](https://github.com/jlowin) in [#16034](https://github.com/PrefectHQ/prefect/pull/16034)
* Briefly explain how to update deployment with `prefect.yaml` by [@discdiver](https://github.com/discdiver) in [#15812](https://github.com/PrefectHQ/prefect/pull/15812)
* Bump tailwindcss from 3.4.14 to 3.4.15 in /ui by [@dependabot](https://github.com/dependabot) in [#16040](https://github.com/PrefectHQ/prefect/pull/16040)
* Bump @vitejs/plugin-vue from 5.1.4 to 5.2.0 in /ui by [@dependabot](https://github.com/dependabot) in [#16039](https://github.com/PrefectHQ/prefect/pull/16039)
* Bump vite from 5.4.10 to 5.4.11 in /ui by [@dependabot](https://github.com/dependabot) in [#16038](https://github.com/PrefectHQ/prefect/pull/16038)
* Bump cross-spawn from 7.0.3 to 7.0.6 in /ui by [@dependabot](https://github.com/dependabot) in [#16047](https://github.com/PrefectHQ/prefect/pull/16047)
* Bump vue from 3.5.12 to 3.5.13 in /ui by [@dependabot](https://github.com/dependabot) in [#16041](https://github.com/PrefectHQ/prefect/pull/16041)
* Improve instructions for connecting to Cloud by [@discdiver](https://github.com/discdiver) in [#16037](https://github.com/PrefectHQ/prefect/pull/16037)
* Update docs version selector and urls  by [@discdiver](https://github.com/discdiver) in [#15923](https://github.com/PrefectHQ/prefect/pull/15923)
* Update docs redirects and settings reference path by [@discdiver](https://github.com/discdiver) in [#16055](https://github.com/PrefectHQ/prefect/pull/16055)
* fix agents -> workers doc examples that reference non-existent code by [@zzstoatzz](https://github.com/zzstoatzz) in [#16052](https://github.com/PrefectHQ/prefect/pull/16052)
* remove unused import by [@zzstoatzz](https://github.com/zzstoatzz) in [#16061](https://github.com/PrefectHQ/prefect/pull/16061)
* migrate `prefect_aws.batch` off `sync_compatible` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16053](https://github.com/PrefectHQ/prefect/pull/16053)
* Remove rc suffixes from all internal dependencies by [@cicdw](https://github.com/cicdw) in [#16018](https://github.com/PrefectHQ/prefect/pull/16018)
* Remove Discourse from README by [@olearycrew](https://github.com/olearycrew) in [#16023](https://github.com/PrefectHQ/prefect/pull/16023)
* Categorize docs in release notes by [@cicdw](https://github.com/cicdw) in [#15997](https://github.com/PrefectHQ/prefect/pull/15997)

**New OSS UI 📊**

* \[UI v2] Fix tab order in variable create dialog by [@desertaxle](https://github.com/desertaxle) in [#16014](https://github.com/PrefectHQ/prefect/pull/16014)
* \[UI v2] Setup Storybook by [@evan-liu](https://github.com/evan-liu) in [#16003](https://github.com/PrefectHQ/prefect/pull/16003)
* \[UI v2] Variables table - part 1 by [@desertaxle](https://github.com/desertaxle) in [#15985](https://github.com/PrefectHQ/prefect/pull/15985)
* \[UI v2] Variables table - part 2 by [@desertaxle](https://github.com/desertaxle) in [#16025](https://github.com/PrefectHQ/prefect/pull/16025)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.2...3.1.3](https://github.com/PrefectHQ/prefect/compare/3.1.2...3.1.3)

***

## 3.1.2 - Bug Fixes, Chicago Style, Hold the Ketchup

*Released on November 12, 2024*

**Bug Fixes 🐞**

* Fixes the arguments for the url generation in BaseWorker by [@sam-phinizy](https://github.com/sam-phinizy) in [#15982](https://github.com/PrefectHQ/prefect/pull/15982)
* Fix formatting of `list` and `set` settings values when marshaling to environment variables by [@GalLadislav](https://github.com/GalLadislav) in [#15979](https://github.com/PrefectHQ/prefect/pull/15979)
* fix delete block type prompt by [@zzstoatzz](https://github.com/zzstoatzz) in [#15989](https://github.com/PrefectHQ/prefect/pull/15989)
* Ensure `.env` files load only Prefect environment variables by [@desertaxle](https://github.com/desertaxle) in [#15975](https://github.com/PrefectHQ/prefect/pull/15975)
* Fix bugs in precedence of settings sources for settings with multiple validation aliases by [@desertaxle](https://github.com/desertaxle) in [#15995](https://github.com/PrefectHQ/prefect/pull/15995)
* Persist failed data at random locations by [@cicdw](https://github.com/cicdw) in [#15991](https://github.com/PrefectHQ/prefect/pull/15991)
* Fixes the worker url slug by [@sam-phinizy](https://github.com/sam-phinizy) in [#15964](https://github.com/PrefectHQ/prefect/pull/15964)
* Add in ability to pass additional formatting kwargs to `url_for` by [@sam-phinizy](https://github.com/sam-phinizy) in [#15974](https://github.com/PrefectHQ/prefect/pull/15974)
* Fix the key for worker metadata: it's is just "metadata" by [@abrookins](https://github.com/abrookins) in [#15965](https://github.com/PrefectHQ/prefect/pull/15965)

**Integrations & Dependencies 🤝**

* adopt `async_dispatch` for slack collection by [@zzstoatzz](https://github.com/zzstoatzz) in [#15973](https://github.com/PrefectHQ/prefect/pull/15973)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-design to version 2.14.9 by [@marvin-robot](https://github.com/marvin-robot) in [#15961](https://github.com/PrefectHQ/prefect/pull/15961)
* Update @prefecthq/prefect-ui-library to version 3.11.16 by [@marvin-robot](https://github.com/marvin-robot) in [#15956](https://github.com/PrefectHQ/prefect/pull/15956)
* handle possible `None` value by [@zzstoatzz](https://github.com/zzstoatzz) in [#15966](https://github.com/PrefectHQ/prefect/pull/15966)
* Add sidebar to v2 UI by [@desertaxle](https://github.com/desertaxle) in [#15925](https://github.com/PrefectHQ/prefect/pull/15925)
* \[UI v2] Add ability to create new variables by [@desertaxle](https://github.com/desertaxle) in [#15962](https://github.com/PrefectHQ/prefect/pull/15962)
* update `asyncio_default_fixture_loop_scope` in all collections by [@zzstoatzz](https://github.com/zzstoatzz) in [#15976](https://github.com/PrefectHQ/prefect/pull/15976)
* Update @prefecthq/prefect-ui-library to version 3.11.18 by [@marvin-robot](https://github.com/marvin-robot) in [#15994](https://github.com/PrefectHQ/prefect/pull/15994)
* Update worker to give worker labels to flow runs during submittal by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15983](https://github.com/PrefectHQ/prefect/pull/15983)
* clarify state hook docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#15977](https://github.com/PrefectHQ/prefect/pull/15977)
* Fix documentation link to deployment concept by [@sandertan](https://github.com/sandertan) in [#15988](https://github.com/PrefectHQ/prefect/pull/15988)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.1...3.1.2](https://github.com/PrefectHQ/prefect/compare/3.1.1...3.1.2)

***

## 3.1.1 - Around the Codebase in 80 PRs

*Released on November 08, 2024*

**Enhancements ➕➕**

* Hook `prefect-kubernetes` into setting framework by [@desertaxle](https://github.com/desertaxle) in [#15888](https://github.com/PrefectHQ/prefect/pull/15888)
* Enable PREFECT\_PROFILES\_PATH in source files by [@GalLadislav](https://github.com/GalLadislav) in [#15914](https://github.com/PrefectHQ/prefect/pull/15914)
* Include worker ID with worker-originated flow run logs by [@abrookins](https://github.com/abrookins) in [#15941](https://github.com/PrefectHQ/prefect/pull/15941)

**Bug Fixes 🐞**

* fix `wait_for` for `DaskTaskRunner` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15909](https://github.com/PrefectHQ/prefect/pull/15909)
* fix extra loggers parsing by [@zzstoatzz](https://github.com/zzstoatzz) in [#15913](https://github.com/PrefectHQ/prefect/pull/15913)
* Fix `prefect config view` not showing .env file settings by [@GalLadislav](https://github.com/GalLadislav) in [#15922](https://github.com/PrefectHQ/prefect/pull/15922)
* fix sqlite migration by [@zzstoatzz](https://github.com/zzstoatzz) in [#15917](https://github.com/PrefectHQ/prefect/pull/15917)
* fix flow run graph endpoint for nested task runs by [@jakekaplan](https://github.com/jakekaplan) in [#15939](https://github.com/PrefectHQ/prefect/pull/15939)

**Integrations & Dependencies 🤝**

* Update typer requirement from !=0.12.2,`<0.13.0,>=0.12.0` to `>=0.12.0`,!=0.12.2,`<0.14.0` by [@dependabot](https://github.com/dependabot) in [#15949](https://github.com/PrefectHQ/prefect/pull/15949)
* Setup OpenTelemetry exporters when initializing prefect by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15946](https://github.com/PrefectHQ/prefect/pull/15946)

**Development & Tidiness 🧹**

* add internal `async_dispatch` util by [@zzstoatzz](https://github.com/zzstoatzz) in [#15813](https://github.com/PrefectHQ/prefect/pull/15813)
* Update @prefecthq/prefect-ui-library to version 3.11.14 by [@marvin-robot](https://github.com/marvin-robot) in [#15921](https://github.com/PrefectHQ/prefect/pull/15921)
* Bump vue-tsc from 2.1.8 to 2.1.10 in /ui by [@dependabot](https://github.com/dependabot) in [#15916](https://github.com/PrefectHQ/prefect/pull/15916)
* Begin replatform of UI to React by [@desertaxle](https://github.com/desertaxle) in [#15907](https://github.com/PrefectHQ/prefect/pull/15907)
* Set `COVERAGE_CORE=sysmon` to speed up test on 3.12 by [@desertaxle](https://github.com/desertaxle) in [#15905](https://github.com/PrefectHQ/prefect/pull/15905)
* Update docs for task results persistence param by [@frances720](https://github.com/frances720) in [#15931](https://github.com/PrefectHQ/prefect/pull/15931)
* Add in WorkerAPILogger and related functionality by [@sam-phinizy](https://github.com/sam-phinizy) in [#15864](https://github.com/PrefectHQ/prefect/pull/15864)
* Send worker metadata with first heartbeat by [@abrookins](https://github.com/abrookins) in [#15898](https://github.com/PrefectHQ/prefect/pull/15898)
* Fix the direction of our integration string replacement by [@abrookins](https://github.com/abrookins) in [#15959](https://github.com/PrefectHQ/prefect/pull/15959)
* Add in a link to the worker logs page by [@sam-phinizy](https://github.com/sam-phinizy) in [#15958](https://github.com/PrefectHQ/prefect/pull/15958)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.0...3.1.1](https://github.com/PrefectHQ/prefect/compare/3.1.0...3.1.1)

***

## 3.1.0 - Configuro, ergo sum

*Released on October 31, 2024*

We're excited to unveil a major overhaul of Prefect's configuration system. At the heart of this release is a complete refactor of our settings architecture, now powered by `pydantic-settings` for enhanced organization and clarity. You can now define your settings in either a dedicated `prefect.toml` file or your existing `pyproject.toml` file, streamlining the configuration experience and making it more portable across environments.

To learn more about new settings capabilities, check out the updated [settings documentation](https://docs.prefect.io/3.0/develop/settings-and-profiles/) or watch [@zzstoatzz](https://github.com/zzstoatzz)'s [instructional demo on YouTube](https://www.youtube.com/watch?v=aeWCT_fqdEY).

**New Features 🎉**

* Add support for defining settings via a `prefect.toml` file by [@desertaxle](https://github.com/desertaxle) in [#15788](https://github.com/PrefectHQ/prefect/pull/15788)
* Add support for defining settings via a `pyproject.toml` file by [@desertaxle](https://github.com/desertaxle) in [#15875](https://github.com/PrefectHQ/prefect/pull/15875)

**Enhancements ➕➕**

* Pass through kwargs for `run_shell_process` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15817](https://github.com/PrefectHQ/prefect/pull/15817)
* Remove `jit="off"` setting for Postgres DBs by [@desertaxle](https://github.com/desertaxle) in [#15854](https://github.com/PrefectHQ/prefect/pull/15854)
* Add setting to allow turning off persistence for tasks globally by [@desertaxle](https://github.com/desertaxle) in [#15881](https://github.com/PrefectHQ/prefect/pull/15881)

**Bug Fixes 🐞**

* Don't cache on any key computation errors and log for visibility by [@cicdw](https://github.com/cicdw) in [#15868](https://github.com/PrefectHQ/prefect/pull/15868)
* Fix logging for FastAPI and Uvicorn by [@desertaxle](https://github.com/desertaxle) in [#15871](https://github.com/PrefectHQ/prefect/pull/15871)
* Allow for unpersisted 2.x result payloads in states by [@cicdw](https://github.com/cicdw) in [#15878](https://github.com/PrefectHQ/prefect/pull/15878)
* Update `Settings.copy_with_update` to ignore sources when restoring default settings by [@desertaxle](https://github.com/desertaxle) in [#15884](https://github.com/PrefectHQ/prefect/pull/15884)
* Don't reuse exception name in nested exception handling by [@cicdw](https://github.com/cicdw) in [#15894](https://github.com/PrefectHQ/prefect/pull/15894)

**Integrations & Dependencies 🤝**

**`prefect-dbt`**

* Add `DbtCloudJob` block to top level import by [@cicdw](https://github.com/cicdw) in [#15880](https://github.com/PrefectHQ/prefect/pull/15880)

**Dependencies**

* Update croniter requirement from `<4.0.0,>=1.0.12` to `>=1.0.12,<5.0.0` by [@dependabot](https://github.com/dependabot) in [#15839](https://github.com/PrefectHQ/prefect/pull/15839)
* Update @prefecthq/prefect-design to version 2.14.1 by [@marvin-robot](https://github.com/marvin-robot) in [#15834](https://github.com/PrefectHQ/prefect/pull/15834)
* Update @prefecthq/prefect-ui-library to version 3.11.8 by [@marvin-robot](https://github.com/marvin-robot) in [#15835](https://github.com/PrefectHQ/prefect/pull/15835)
* Update @prefecthq/prefect-design to version 2.14.2 by [@marvin-robot](https://github.com/marvin-robot) in [#15837](https://github.com/PrefectHQ/prefect/pull/15837)
* Bump vue-tsc from 2.1.6 to 2.1.8 in /ui by [@dependabot](https://github.com/dependabot) in [#15819](https://github.com/PrefectHQ/prefect/pull/15819)
* Bump vite from 5.4.9 to 5.4.10 in /ui by [@dependabot](https://github.com/dependabot) in [#15820](https://github.com/PrefectHQ/prefect/pull/15820)
* Update @prefecthq/prefect-design to version 2.14.3 by [@marvin-robot](https://github.com/marvin-robot) in [#15844](https://github.com/PrefectHQ/prefect/pull/15844)
* Update @prefecthq/prefect-ui-library to version 3.11.11 by [@marvin-robot](https://github.com/marvin-robot) in [#15887](https://github.com/PrefectHQ/prefect/pull/15887)
* Update @prefecthq/prefect-design to version 2.14.4 by [@marvin-robot](https://github.com/marvin-robot) in [#15852](https://github.com/PrefectHQ/prefect/pull/15852)
* Update @prefecthq/prefect-ui-library to version 3.11.12 by [@marvin-robot](https://github.com/marvin-robot) in [#15891](https://github.com/PrefectHQ/prefect/pull/15891)
* Add opentelementry requirements by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15867](https://github.com/PrefectHQ/prefect/pull/15867)

**Development & Tidiness 🧹**

* Remove old GitHub Actions workflow by [@zzstoatzz](https://github.com/zzstoatzz) in [#15822](https://github.com/PrefectHQ/prefect/pull/15822)
* Fix sorting of tags to determine nightly release version by [@desertaxle](https://github.com/desertaxle) in [#15825](https://github.com/PrefectHQ/prefect/pull/15825)
* Add `prefect.toml` to `.gitignore` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15846](https://github.com/PrefectHQ/prefect/pull/15846)
* Fix non `soft_wrap` link in `prefect block register` by [@zzstoatzz](https://github.com/zzstoatzz) in [#15876](https://github.com/PrefectHQ/prefect/pull/15876)
* Moves `experimental_warn` setting to `experiments` model and removes `async_fetch_state_result` by [@desertaxle](https://github.com/desertaxle) in [#15885](https://github.com/PrefectHQ/prefect/pull/15885)
* Fix documentation link to task settings by [@jmbhughes](https://github.com/jmbhughes) in [#15809](https://github.com/PrefectHQ/prefect/pull/15809)
* Serve in container docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#15814](https://github.com/PrefectHQ/prefect/pull/15814)
* Update mermaid.js diagram styling in docs by [@discdiver](https://github.com/discdiver) in [#15811](https://github.com/PrefectHQ/prefect/pull/15811)
* Fixes broken image links in ACI worker guide by [@discdiver](https://github.com/discdiver) in [#15831](https://github.com/PrefectHQ/prefect/pull/15831)
* Add in a settings.experiments module by [@sam-phinizy](https://github.com/sam-phinizy) in [#15845](https://github.com/PrefectHQ/prefect/pull/15845)
* Auto-generate settings reference documentation by [@desertaxle](https://github.com/desertaxle) in [#15830](https://github.com/PrefectHQ/prefect/pull/15830)
* Update 'Configure settings and profiles' documentation to include `prefect.toml` support by [@desertaxle](https://github.com/desertaxle) in [#15847](https://github.com/PrefectHQ/prefect/pull/15847)
* Adds in the ability for the client to get a remote\_id from the server by [@sam-phinizy](https://github.com/sam-phinizy) in [#15849](https://github.com/PrefectHQ/prefect/pull/15849)
* Adds in the worker\_id to the LogCreate schema by [@sam-phinizy](https://github.com/sam-phinizy) in [#15851](https://github.com/PrefectHQ/prefect/pull/15851)
* Fix errors in markdown and codspeed workflows by [@desertaxle](https://github.com/desertaxle) in [#15841](https://github.com/PrefectHQ/prefect/pull/15841)
* Remove `max_active_runs` and `catchup` fields by [@zzstoatzz](https://github.com/zzstoatzz) in [#15810](https://github.com/PrefectHQ/prefect/pull/15810)
* Use released version of `pytest-markdown-docs` by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#15808](https://github.com/PrefectHQ/prefect/pull/15808)
* Update GitHub actions versions and formatting in CI/CD deploy docs page by [@discdiver](https://github.com/discdiver) in [#15667](https://github.com/PrefectHQ/prefect/pull/15667)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.0.11...3.1.0](https://github.com/PrefectHQ/prefect/compare/3.0.11...3.1.0)

***


# 3.2
Source: https://docs-3.prefect.io/v3/release-notes/oss/version-3-2



## 3.2.15 - Tempus Fugit

*Released on March 28, 2025*

Stay tuned, our next release will include Python 3.13 support!

**Enhancements ➕➕**

* delete all deployments cli by [@zzstoatzz](https://github.com/zzstoatzz) in [#17568](https://github.com/PrefectHQ/prefect/pull/17568)
* Improve ad-hoc infrastructure submission error handling by [@desertaxle](https://github.com/desertaxle) in [#17564](https://github.com/PrefectHQ/prefect/pull/17564)
* Adds `prefect-client` images to the release and pre-release builds by [@chrisguidry](https://github.com/chrisguidry) in [#17600](https://github.com/PrefectHQ/prefect/pull/17600)
* Log ignored template variables when a task definition arn is supplied to the ECS worker by [@kevingrismore](https://github.com/kevingrismore) in [#17565](https://github.com/PrefectHQ/prefect/pull/17565)
* Fix `[@classmethod](https://github.com/classmethod)` and `[@staticmethod](https://github.com/staticmethod)` flows and tasks for Python 3.13 by [@desertaxle](https://github.com/desertaxle) in [#17583](https://github.com/PrefectHQ/prefect/pull/17583)

**Bug Fixes 🐞**

* bump `typing-extensions` lower bound by [@zzstoatzz](https://github.com/zzstoatzz) in [#17581](https://github.com/PrefectHQ/prefect/pull/17581)
* Gate on concurrency prior to entering a Running state by [@cicdw](https://github.com/cicdw) in [#17597](https://github.com/PrefectHQ/prefect/pull/17597)
* respect default namespace for docker `prefect.yaml` steps by [@zzstoatzz](https://github.com/zzstoatzz) in [#17607](https://github.com/PrefectHQ/prefect/pull/17607)
* Stable cache keys for pandas by [@cicdw](https://github.com/cicdw) in [#17611](https://github.com/PrefectHQ/prefect/pull/17611)
* Fix `mark_flow_run_as_cancelled` in worker still gets error by [@lelouvincx](https://github.com/lelouvincx) in [#17629](https://github.com/PrefectHQ/prefect/pull/17629)

**Development & Tidiness 🧹**

* Various typing improvements by [@desertaxle](https://github.com/desertaxle) in [#17569](https://github.com/PrefectHQ/prefect/pull/17569)
* Docker build for a `prefect-client`-only image by [@chrisguidry](https://github.com/chrisguidry) in [#17596](https://github.com/PrefectHQ/prefect/pull/17596)
* Includes more (and more current) files in the nightly release detection by [@chrisguidry](https://github.com/chrisguidry) in [#17605](https://github.com/PrefectHQ/prefect/pull/17605)
* Includes the .github workflows in the nightly release detection by [@chrisguidry](https://github.com/chrisguidry) in [#17606](https://github.com/PrefectHQ/prefect/pull/17606)
* Chooses the right Dockerfile for building `prefect-client` by [@chrisguidry](https://github.com/chrisguidry) in [#17608](https://github.com/PrefectHQ/prefect/pull/17608)
* Uses the right format for prefect-client pre-release tags by [@chrisguidry](https://github.com/chrisguidry) in [#17610](https://github.com/PrefectHQ/prefect/pull/17610)
* Add new deployment version table by [@cicdw](https://github.com/cicdw) in [#17532](https://github.com/PrefectHQ/prefect/pull/17532)
* Include `pytz` in the `prefect-client` dependencies by [@chrisguidry](https://github.com/chrisguidry) in [#17595](https://github.com/PrefectHQ/prefect/pull/17595)

**Documentation 📓**

* fix: cli login command in modal docs by [@Ben-Epstein](https://github.com/Ben-Epstein) in [#17582](https://github.com/PrefectHQ/prefect/pull/17582)
* Move settings ref to reference section by [@cicdw](https://github.com/cicdw) in [#17590](https://github.com/PrefectHQ/prefect/pull/17590)
* migrate mintlify to docs.json + light bikeshedding by [@aaazzam](https://github.com/aaazzam) in [#17591](https://github.com/PrefectHQ/prefect/pull/17591)
* Fix syntax in schedules example by [@zhen0](https://github.com/zhen0) in [#17614](https://github.com/PrefectHQ/prefect/pull/17614)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.14...3.2.15](https://github.com/PrefectHQ/prefect/compare/3.2.14...3.2.15)

***

## 3.2.14 - When Modules Pop Off: The Untold Story

*Released on March 21, 2025*

**Enhancements ➕➕**

* Adds new setting `PREFECT_TASKS_DEFAULT_NO_CACHE` to not cache by default by [@cicdw](https://github.com/cicdw) in [#17488](https://github.com/PrefectHQ/prefect/pull/17488)
* increase cloud run worker timeout by [@jeremy-thomas-roc](https://github.com/jeremy-thomas-roc) in [#17540](https://github.com/PrefectHQ/prefect/pull/17540)
* Add `prefect-docker`'s `DockerRegistryCredentials` as accepted type for ACI job configuration's `image_registry` by [@kevingrismore](https://github.com/kevingrismore) in [#17543](https://github.com/PrefectHQ/prefect/pull/17543)
* Add debug logging of ECS task definition differences when equality comparison fails by [@kevingrismore](https://github.com/kevingrismore) in [#17544](https://github.com/PrefectHQ/prefect/pull/17544)

**Bug Fixes 🐞**

* Only log at INFO level for final state by [@cicdw](https://github.com/cicdw) in [#17454](https://github.com/PrefectHQ/prefect/pull/17454)
* Bugfix: Paginated task runs route + client-side fix by [@znicholasbrown](https://github.com/znicholasbrown) in [#17407](https://github.com/PrefectHQ/prefect/pull/17407)
* Fix docker build with context arg when already set by [@thdtt](https://github.com/thdtt) in [#17535](https://github.com/PrefectHQ/prefect/pull/17535)
* Avoid inheriting `NullFilesystem` for transaction metadata storage by [@zzstoatzz](https://github.com/zzstoatzz) in [#17541](https://github.com/PrefectHQ/prefect/pull/17541)
* fix(flow-run): ensure state is consistent when cancelling by [@lelouvincx](https://github.com/lelouvincx) in [#17537](https://github.com/PrefectHQ/prefect/pull/17537)
* Don't pop the loader module by [@cicdw](https://github.com/cicdw) in [#17524](https://github.com/PrefectHQ/prefect/pull/17524)
* Convert strings to timezone-aware datetimes in the flow run graph API by [@cicdw](https://github.com/cicdw) in [#17552](https://github.com/PrefectHQ/prefect/pull/17552)
* Update ACI worker base job template with current docker registry block by [@kevingrismore](https://github.com/kevingrismore) in [#17549](https://github.com/PrefectHQ/prefect/pull/17549)
* Account for `_resolve_path` returning `None` by [@cicdw](https://github.com/cicdw) in [#17551](https://github.com/PrefectHQ/prefect/pull/17551)
* fix kubernetes job variables merge logic by [@zzstoatzz](https://github.com/zzstoatzz) in [#17512](https://github.com/PrefectHQ/prefect/pull/17512)

**Development & Tidiness 🧹**

* Update CODEOWNERS by [@zzstoatzz](https://github.com/zzstoatzz) in [#17510](https://github.com/PrefectHQ/prefect/pull/17510)
* Update CODEOWNERS for docs by [@aaazzam](https://github.com/aaazzam) in [#17516](https://github.com/PrefectHQ/prefect/pull/17516)
* rm pendulum from integrations by [@zzstoatzz](https://github.com/zzstoatzz) in [#17509](https://github.com/PrefectHQ/prefect/pull/17509)
* Get `pyright` check passing for `prefect.runner` submodules by [@desertaxle](https://github.com/desertaxle) in [#17502](https://github.com/PrefectHQ/prefect/pull/17502)
* update `Field` `examples` kwargs for gcp and databricks by [@zzstoatzz](https://github.com/zzstoatzz) in [#17526](https://github.com/PrefectHQ/prefect/pull/17526)
* Adds back telemetry service to all servers when enabled by [@cicdw](https://github.com/cicdw) in [#17528](https://github.com/PrefectHQ/prefect/pull/17528)
* Update @prefecthq/prefect-ui-library to version 3.11.51 by [@marvin-robot](https://github.com/marvin-robot) in [#17539](https://github.com/PrefectHQ/prefect/pull/17539)

**Documentation 📓**

* fix broken slack link in docs by [@aaazzam](https://github.com/aaazzam) in [#17491](https://github.com/PrefectHQ/prefect/pull/17491)
* add "API Reference" to docs by [@aaazzam](https://github.com/aaazzam) in [#17515](https://github.com/PrefectHQ/prefect/pull/17515)
* chore(docs): link to new ECS worker Terraform module by [@mitchnielsen](https://github.com/mitchnielsen) in [#17523](https://github.com/PrefectHQ/prefect/pull/17523)

**Experimental**

* schema changes for work pool storage config by [@zzstoatzz](https://github.com/zzstoatzz) in [#17527](https://github.com/PrefectHQ/prefect/pull/17527)
* Add experimental CLI for configuring work pool storage by [@desertaxle](https://github.com/desertaxle) in [#17548](https://github.com/PrefectHQ/prefect/pull/17548)
* Persist work pool and job variables for submitted ad-hoc flow runs by [@desertaxle](https://github.com/desertaxle) in [#17530](https://github.com/PrefectHQ/prefect/pull/17530)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.13...3.2.14](https://github.com/PrefectHQ/prefect/compare/3.2.13...3.2.14)

***

## 3.2.13 - Labels: Not Just for Jars

*Released on March 14, 2025*

**Enhancements ➕➕**

* Update workers to include work pool and worker labels by [@desertaxle](https://github.com/desertaxle) in [#17420](https://github.com/PrefectHQ/prefect/pull/17420)

**Bug Fixes 🐞**

* Disables run tracer with `PREFECT_CLOUD_ENABLE_ORCHESTRATION_TELEMETRY`  by [@jeanluciano](https://github.com/jeanluciano) in [#17417](https://github.com/PrefectHQ/prefect/pull/17417)
* Fix `disable_run_logger` context manager by [@desertaxle](https://github.com/desertaxle) in [#17443](https://github.com/PrefectHQ/prefect/pull/17443)
* Fix `serve` deployment name truncation by [@zzstoatzz](https://github.com/zzstoatzz) in [#17447](https://github.com/PrefectHQ/prefect/pull/17447)
* Fix race condition in Kubernetes worker by [@desertaxle](https://github.com/desertaxle) in [#17462](https://github.com/PrefectHQ/prefect/pull/17462)
* Ensure base `prefect.yaml` template is included in built package by [@desertaxle](https://github.com/desertaxle) in [#17472](https://github.com/PrefectHQ/prefect/pull/17472)
* Add caching to `create_api_app` to fix errors when using server-side orchestration client by [@desertaxle](https://github.com/desertaxle) in [#17474](https://github.com/PrefectHQ/prefect/pull/17474)

**Development & Tidiness 🧹**

* Remove unused yaml files and refs by [@cicdw](https://github.com/cicdw) in [#17470](https://github.com/PrefectHQ/prefect/pull/17470)
* Add overloads for `run_task` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17448](https://github.com/PrefectHQ/prefect/pull/17448)

**Documentation 📓**

* Update ray url by [@hongbo-miao](https://github.com/hongbo-miao) in [#17440](https://github.com/PrefectHQ/prefect/pull/17440)
* Move Modal tutorial to the Dynamic infrastructure examples section by [@daniel-prefect](https://github.com/daniel-prefect) in [#17464](https://github.com/PrefectHQ/prefect/pull/17464)
* Create a new section for self-hosted server examples (CLI, Docker, Helm) by [@daniel-prefect](https://github.com/daniel-prefect) in [#17468](https://github.com/PrefectHQ/prefect/pull/17468)
* Remove dangling tutorial references by [@daniel-prefect](https://github.com/daniel-prefect) in [#17469](https://github.com/PrefectHQ/prefect/pull/17469)
* Add example using the Terraform provider by [@parkedwards](https://github.com/parkedwards) in [#17479](https://github.com/PrefectHQ/prefect/pull/17479)
* Fix pep8 in README.md by [@sobolevn](https://github.com/sobolevn) in [#17453](https://github.com/PrefectHQ/prefect/pull/17453)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.12...3.2.13](https://github.com/PrefectHQ/prefect/compare/3.2.12...3.2.13)

***

## 3.2.12 - Some Parameters Like It Cold

*Released on March 10, 2025*

This release contains a couple bug fixes (e.g. [https://github.com/PrefectHQ/prefect/issues/17409](https://github.com/PrefectHQ/prefect/issues/17409), [https://github.com/PrefectHQ/prefect/issues/17431](https://github.com/PrefectHQ/prefect/issues/17431), [https://github.com/PrefectHQ/prefect/issues/17434](https://github.com/PrefectHQ/prefect/issues/17434)) and adds a new `freeze` annotation to make certain deployment parameters read-only in the UI when creating a new flow run (see [#17374](https://github.com/PrefectHQ/prefect/pull/17374) for an example).

**Enhancements ➕➕**

* add `freeze` annotation by [@zzstoatzz](https://github.com/zzstoatzz) in [#17374](https://github.com/PrefectHQ/prefect/pull/17374)
* Improve eviction handling for flow runs started by the Kubernetes worker by [@desertaxle](https://github.com/desertaxle) in [#17412](https://github.com/PrefectHQ/prefect/pull/17412)

**Bug Fixes 🐞**

* Fix improper `await` of `RunnerDeployment` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17436](https://github.com/PrefectHQ/prefect/pull/17436)
* Do not target abstract class for Pydantic validation by [@thoec](https://github.com/thoec) in [#17356](https://github.com/PrefectHQ/prefect/pull/17356)
* Remove unnecessary prompt condition by [@cicdw](https://github.com/cicdw) in [#17410](https://github.com/PrefectHQ/prefect/pull/17410)
* Update optional dependencies in integration packages to use `[project.optional-dependencies]` by [@desertaxle](https://github.com/desertaxle) in [#17435](https://github.com/PrefectHQ/prefect/pull/17435)

**Documentation 📓**

* Add Prefect Server and Worker Helm Tutorial by [@prefectcboyd](https://github.com/prefectcboyd) in [#17362](https://github.com/PrefectHQ/prefect/pull/17362)
* Add inline arcades by [@biancaines](https://github.com/biancaines) in [#17393](https://github.com/PrefectHQ/prefect/pull/17393)
* chore(docs): Minor updates and fixes on the Helm deployment tutorial by [@jamiezieziula](https://github.com/jamiezieziula) in [#17411](https://github.com/PrefectHQ/prefect/pull/17411)

**Development ⚙️**

* Allow specifying the key for an existing Kubernetes worker API key secret by [@desertaxle](https://github.com/desertaxle) in [#17390](https://github.com/PrefectHQ/prefect/pull/17390)
* \[UI] Update packages by [@pleek91](https://github.com/pleek91) in [#17426](https://github.com/PrefectHQ/prefect/pull/17426)
* add k8s integration test harness by [@zzstoatzz](https://github.com/zzstoatzz) in [#17385](https://github.com/PrefectHQ/prefect/pull/17385)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.11...3.2.12](https://github.com/PrefectHQ/prefect/compare/3.2.11...3.2.12)

***

## 3.2.11 - OTEL me it's not true!

*Released on March 05, 2025*

This release includes a bug fix where import from `prefect.deployments.flow_runs` were failing without the `otel` extra installed.

**Bug Fixes 🐞**

* Add handling for extra install in `prefect.deployments.flow_runs` by [@desertaxle](https://github.com/desertaxle) in [#17392](https://github.com/PrefectHQ/prefect/pull/17392)

**Documentation 📓**

* Tidy up the Modal tutorial by [@daniel-prefect](https://github.com/daniel-prefect) in [#17367](https://github.com/PrefectHQ/prefect/pull/17367)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.10...3.2.11](https://github.com/PrefectHQ/prefect/compare/3.2.10...3.2.11)

***

## 3.2.10 - Entomologists HATE This One Weird Trick

*Released on March 05, 2025*

**Enhancements ➕➕**

* Add sigterm handling for `prefect flow-run execute` by [@desertaxle](https://github.com/desertaxle) in [#17352](https://github.com/PrefectHQ/prefect/pull/17352)
* Add debugging variables to Vertex AI Worker by [@jbrache](https://github.com/jbrache) in [#17335](https://github.com/PrefectHQ/prefect/pull/17335)

**Bug Fixes 🐞**

* fix `git_clone` where branch name has forward-slash by [@zzstoatzz](https://github.com/zzstoatzz) in [#17359](https://github.com/PrefectHQ/prefect/pull/17359)
* feat: ensure ui files are writeable by [@happysalada](https://github.com/happysalada) in [#17336](https://github.com/PrefectHQ/prefect/pull/17336)
* warn if `RunnerDeployment` with a `work_pool_name` given to `serve` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17349](https://github.com/PrefectHQ/prefect/pull/17349)
* Cancel runs if the deployment was deleted by [@cicdw](https://github.com/cicdw) in [#17313](https://github.com/PrefectHQ/prefect/pull/17313)
* Respect custom cert files in events client by [@cicdw](https://github.com/cicdw) in [#17364](https://github.com/PrefectHQ/prefect/pull/17364)
* Always use a new tmpdir when executing with the process worker by [@cicdw](https://github.com/cicdw) in [#17370](https://github.com/PrefectHQ/prefect/pull/17370)
* Fix bug causing duplicate flow run heartbeats with a process worker by [@desertaxle](https://github.com/desertaxle) in [#17375](https://github.com/PrefectHQ/prefect/pull/17375)
* Improve `Runner` exception handling by [@desertaxle](https://github.com/desertaxle) in [#17376](https://github.com/PrefectHQ/prefect/pull/17376)
* Print correct API URL when setting base path by [@cicdw](https://github.com/cicdw) in [#17386](https://github.com/PrefectHQ/prefect/pull/17386)
* Check if status.container\_status\[0] is not None by [@mcuelenaere](https://github.com/mcuelenaere) in [#17333](https://github.com/PrefectHQ/prefect/pull/17333)
* Propagate trace context from user app to `run_deployment` by [@fatih-acar](https://github.com/fatih-acar) in [#16812](https://github.com/PrefectHQ/prefect/pull/16812)

**Integrations & Dependencies 🤝**

* bump `prefect-kubernetes`'s dependency on `prefect` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17347](https://github.com/PrefectHQ/prefect/pull/17347)

**Development & Tidiness 🧹**

* fix 3.9 specific issues with BackgroundTasks by [@zzstoatzz](https://github.com/zzstoatzz) in [#17326](https://github.com/PrefectHQ/prefect/pull/17326)
* Update `ruff` settings in `pyproject.toml` by [@desertaxle](https://github.com/desertaxle) in [#17382](https://github.com/PrefectHQ/prefect/pull/17382)

**Documentation 📓**

* docs(prefect-ray): change to Ray support for Python 3.13 is experimental by [@hongbo-miao](https://github.com/hongbo-miao) in [#17339](https://github.com/PrefectHQ/prefect/pull/17339)
* Add New MLB Pipeline Tutorial Series by [@biancaines](https://github.com/biancaines) in [#17321](https://github.com/PrefectHQ/prefect/pull/17321)
* feat: Prefect on Modal tutorial documentation by [@Ben-Epstein](https://github.com/Ben-Epstein) in [#17345](https://github.com/PrefectHQ/prefect/pull/17345)
* chore(docs): remove Helm reference on ECS page by [@mitchnielsen](https://github.com/mitchnielsen) in [#17363](https://github.com/PrefectHQ/prefect/pull/17363)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.9...3.2.10](https://github.com/PrefectHQ/prefect/compare/3.2.9...3.2.10)

***

## 3.2.9 - Free Range Runners

*Released on February 28, 2025*

This release contains a fix for bug a where the default `Runner` limit would propagate to the `ProcessWorker`. The fix restores the default behavior for the `ProcessWorker` before the 3.2.8 release.

**Bug Fixes 🐞**

* Lift limit on `Runner` used by `ProcessWorker` by [@desertaxle](https://github.com/desertaxle) in [#17325](https://github.com/PrefectHQ/prefect/pull/17325)
* Fallback to system `uv` if Python interface isn't available by [@desertaxle](https://github.com/desertaxle) in [#17320](https://github.com/PrefectHQ/prefect/pull/17320)
* Remove extra example from Vertex AI worker by [@desertaxle](https://github.com/desertaxle) in [#17324](https://github.com/PrefectHQ/prefect/pull/17324)

**Integrations & Dependencies 🤝**

* Update Vertex AI worker to support rich scheduling parameters by [@jbrache](https://github.com/jbrache) in [#17266](https://github.com/PrefectHQ/prefect/pull/17266)

**Documentation 📓**

* Add instructions for running a Prefect server in a Docker container by [@zzstoatzz](https://github.com/zzstoatzz) in [#17306](https://github.com/PrefectHQ/prefect/pull/17306)
* Airflow migration guide by [@olearycrew](https://github.com/olearycrew) in [#17285](https://github.com/PrefectHQ/prefect/pull/17285)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.8...3.2.9](https://github.com/PrefectHQ/prefect/compare/3.2.8...3.2.9)

***

## 3.2.8 - "Runners Took My Job" - Process Workers, Probably

*Released on February 28, 2025*

**Enhancements ➕➕**

* Add handling to propagate dependencies for submitted flow runs by [@desertaxle](https://github.com/desertaxle) in [#17250](https://github.com/PrefectHQ/prefect/pull/17250)
* Subscribe to state changes in wait\_for\_flow\_run by [@bnaul](https://github.com/bnaul) in [#17243](https://github.com/PrefectHQ/prefect/pull/17243)

**Bug Fixes 🐞**

* Updates `ProcessWorker` to delegate flow run execution to a `Runner` by [@desertaxle](https://github.com/desertaxle) in [#17295](https://github.com/PrefectHQ/prefect/pull/17295)
* Add option to log warning when placeholder values is missing when templating by [@desertaxle](https://github.com/desertaxle) in [#17261](https://github.com/PrefectHQ/prefect/pull/17261)
* fix go back to acct for `prefect cloud login` and `prefect cloud workspace set` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17296](https://github.com/PrefectHQ/prefect/pull/17296)
* Refresh session when deleting schedules off a deployment by [@cicdw](https://github.com/cicdw) in [#17278](https://github.com/PrefectHQ/prefect/pull/17278)
* fix `profile use` switching by [@zzstoatzz](https://github.com/zzstoatzz) in [#17300](https://github.com/PrefectHQ/prefect/pull/17300)

**Integrations & Dependencies 🤝**

* dev group for all integrations by [@zzstoatzz](https://github.com/zzstoatzz) in [#17273](https://github.com/PrefectHQ/prefect/pull/17273)
* chore(deps-dev): bump vue-tsc from 2.1.10 to 2.2.4 in /ui by [@dependabot](https://github.com/dependabot) in [#17254](https://github.com/PrefectHQ/prefect/pull/17254)
* Upgrade websockets to v15 by [@sam-phinizy](https://github.com/sam-phinizy) in [#17274](https://github.com/PrefectHQ/prefect/pull/17274)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-ui-library to version 3.11.43 by [@marvin-robot](https://github.com/marvin-robot) in [#17309](https://github.com/PrefectHQ/prefect/pull/17309)
* Fix dependency installation for flow submission by [@desertaxle](https://github.com/desertaxle) in [#17289](https://github.com/PrefectHQ/prefect/pull/17289)
* Expose `KubernetesClusterConfig` at the top level of `prefect-kubernetes` by [@desertaxle](https://github.com/desertaxle) in [#17268](https://github.com/PrefectHQ/prefect/pull/17268)

**Documentation 📓**

* Remove broken link and add redirect for terraform provider by [@discdiver](https://github.com/discdiver) in [#17263](https://github.com/PrefectHQ/prefect/pull/17263)
* explain slugs in schedules docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#17029](https://github.com/PrefectHQ/prefect/pull/17029)
* Fix dbt docs typo by [@kevingrismore](https://github.com/kevingrismore) in [#17288](https://github.com/PrefectHQ/prefect/pull/17288)
* enhance mapping docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#17269](https://github.com/PrefectHQ/prefect/pull/17269)
* chore(API docs): link to related docs pages by [@mitchnielsen](https://github.com/mitchnielsen) in [#17276](https://github.com/PrefectHQ/prefect/pull/17276)

**Experimental**

* Add `KuberenetesWorker.submit` for ad-hoc submission to a Kubernetes work pool by [@desertaxle](https://github.com/desertaxle) in [#17218](https://github.com/PrefectHQ/prefect/pull/17218)
* Add `@kubernetes` decorator by [@desertaxle](https://github.com/desertaxle) in [#17248](https://github.com/PrefectHQ/prefect/pull/17248)
* remove unused experimental `bundles.types` file in `prefect-aws` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17241](https://github.com/PrefectHQ/prefect/pull/17241)
* Add `PrefectFuture` implementation for flow runs by [@desertaxle](https://github.com/desertaxle) in [#17234](https://github.com/PrefectHQ/prefect/pull/17234)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.7...3.2.8](https://github.com/PrefectHQ/prefect/compare/3.2.7...3.2.8)

***

## 3.2.7 - Background Services and Where to Find Them

*Released on February 21, 2025*

This release [fixes](\[#17240]\(https://github.com/PrefectHQ/prefect/pull/17240\)) a bug where the `EventPersister` was not running by default.

**Enhancements ➕➕**

* Add warning of potential client/server incompatibilities by [@desertaxle](https://github.com/desertaxle) in [#17210](https://github.com/PrefectHQ/prefect/pull/17210)
* Set `cache_ok` flag to true for UUIDList by [@cicdw](https://github.com/cicdw) in [#17232](https://github.com/PrefectHQ/prefect/pull/17232)
* Adds more database tuning settings for PostgreSQL by [@cicdw](https://github.com/cicdw) in [#17236](https://github.com/PrefectHQ/prefect/pull/17236)
* Surfaces pull step errors as independent log messages by [@chrisguidry](https://github.com/chrisguidry) in [#17214](https://github.com/PrefectHQ/prefect/pull/17214)

**Bug Fixes 🐞**

* improved `cancelled_flow_query ` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17095](https://github.com/PrefectHQ/prefect/pull/17095)
* respect aliases when loading custom `logging.yaml` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17162](https://github.com/PrefectHQ/prefect/pull/17162)
* Adds `PREFECT_SERVER_API_BASE_PATH` setting by [@cicdw](https://github.com/cicdw) in [#16967](https://github.com/PrefectHQ/prefect/pull/16967)
* Brings back `EventPersister` in discovery of background services by [@chrisguidry](https://github.com/chrisguidry) in [#17240](https://github.com/PrefectHQ/prefect/pull/17240)

**Integrations & Dependencies 🤝**

* experimental `prefect-aws` bundle steps by [@zzstoatzz](https://github.com/zzstoatzz) in [#17201](https://github.com/PrefectHQ/prefect/pull/17201)

**Development & Tidiness 🧹**

* Add `types-dateparser` to dev deps by [@sobolevn](https://github.com/sobolevn) in [#17212](https://github.com/PrefectHQ/prefect/pull/17212)
* cleaning unnecessary files from repo root by [@zzstoatzz](https://github.com/zzstoatzz) in [#17235](https://github.com/PrefectHQ/prefect/pull/17235)
* use `just` instead of `make` command runner and use uv by [@zzstoatzz](https://github.com/zzstoatzz) in [#17149](https://github.com/PrefectHQ/prefect/pull/17149)
* remove Makefile by [@zzstoatzz](https://github.com/zzstoatzz) in [#17233](https://github.com/PrefectHQ/prefect/pull/17233)

**Documentation 📓**

* \[Docs] Tweak timeline dates in Prefect History section by [@daniel-prefect](https://github.com/daniel-prefect) in [#17199](https://github.com/PrefectHQ/prefect/pull/17199)
* standardize names of step action slugs in docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#17223](https://github.com/PrefectHQ/prefect/pull/17223)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.6...3.2.7](https://github.com/PrefectHQ/prefect/compare/3.2.6...3.2.7)

***

## 3.2.6 - Ouroboros No More

*Released on February 19, 2025*

This release includes a fix for [https://github.com/PrefectHQ/prefect/issues/17197](https://github.com/PrefectHQ/prefect/issues/17197), where `poetry` users encountered errors when installing `prefect` due to a self-referential dependency.

**Bug Fixes 🐞**

* \#16397 - Fix quotes in DB migration by [@thomas-dresselhaus](https://github.com/thomas-dresselhaus) in [#17193](https://github.com/PrefectHQ/prefect/pull/17193)
* Removes `client` extras and moves them to top-level dependencies by [@desertaxle](https://github.com/desertaxle) in [#17202](https://github.com/PrefectHQ/prefect/pull/17202)

**Integrations & Dependencies 🤝**

* Add `performance_report_path` arg to DaskTaskRunner by [@bnaul](https://github.com/bnaul) in [#17195](https://github.com/PrefectHQ/prefect/pull/17195)

**Documentation 📓**

* Add links to CLI, API, Terraform, and Helm docs by [@mitchnielsen](https://github.com/mitchnielsen) in [#17142](https://github.com/PrefectHQ/prefect/pull/17142)
* Rename links to examples and add 'uv run' instructions by [@daniel-prefect](https://github.com/daniel-prefect) in [#17145](https://github.com/PrefectHQ/prefect/pull/17145)

**Experimental 🧪**

* Add utilities for creating and executing flow bundles by [@desertaxle](https://github.com/desertaxle) in [#17178](https://github.com/PrefectHQ/prefect/pull/17178)
* Add bundle execution capabilities to `Runner` by [@desertaxle](https://github.com/desertaxle) in [#17192](https://github.com/PrefectHQ/prefect/pull/17192)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.5...3.2.6](https://github.com/PrefectHQ/prefect/compare/3.2.5...3.2.6)

***

## 3.2.5 - Honey, I Shrunk the Dependencies

*Released on February 19, 2025*

This release includes a fix for [https://github.com/PrefectHQ/prefect/issues/17182](https://github.com/PrefectHQ/prefect/issues/17182), where `pull` steps were not correctly updated upon changes to a given deployment.

**Bug Fixes 🐞**

* Fix update logic to account for pull\_steps by [@cicdw](https://github.com/cicdw) in [#17185](https://github.com/PrefectHQ/prefect/pull/17185)

**Development & Tidiness 🧹**

* fix paths in GHAs by [@zzstoatzz](https://github.com/zzstoatzz) in [#17183](https://github.com/PrefectHQ/prefect/pull/17183)
* rm croniter dep by [@zzstoatzz](https://github.com/zzstoatzz) in [#17187](https://github.com/PrefectHQ/prefect/pull/17187)
* vendor croniter by [@zzstoatzz](https://github.com/zzstoatzz) in [#17165](https://github.com/PrefectHQ/prefect/pull/17165)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.4...3.2.5](https://github.com/PrefectHQ/prefect/compare/3.2.4...3.2.5)

***

## 3.2.4 - Every time we have a good release name, something goes wrong so here's a bad release name

*Released on February 18, 2025*

**fixes issue with `3.2.3`**
There was a packaging bug with 3.2.3 where the UI was not included in the published wheel due to project configuration changes, which this release resolves.

* Remove "Pod ... has started." log from `KubernetesWorker` by [@kevingrismore](https://github.com/kevingrismore) in [#17174](https://github.com/PrefectHQ/prefect/pull/17174)
* add `server/ui` to wheel by [@zzstoatzz](https://github.com/zzstoatzz) in [#17176](https://github.com/PrefectHQ/prefect/pull/17176)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.3...3.2.4](https://github.com/PrefectHQ/prefect/compare/3.2.3...3.2.4)

***

## 3.2.3 - The Config is Coming From Inside the pyproject.toml

*Released on February 18, 2025*

**Development & Tidiness 🧹**

* Migrate to `pyproject.toml` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17116](https://github.com/PrefectHQ/prefect/pull/17116)
* consolidate use of `pendulum` in `tests/`: part 1 by [@zzstoatzz](https://github.com/zzstoatzz) in [#17106](https://github.com/PrefectHQ/prefect/pull/17106)

**Documentation 📓**

* Fix link to dbt programmatic invocation by [@kevingrismore](https://github.com/kevingrismore) in [#17131](https://github.com/PrefectHQ/prefect/pull/17131)
* Update SDK docs links by [@seanpwlms](https://github.com/seanpwlms) in [#17138](https://github.com/PrefectHQ/prefect/pull/17138)
* Adds AWS PrivateLink documentation by [@prefectcboyd](https://github.com/prefectcboyd) in [#17076](https://github.com/PrefectHQ/prefect/pull/17076)

**Uncategorized**

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.2...3.2.3](https://github.com/PrefectHQ/prefect/compare/3.2.2...3.2.3)

***

## 3.2.2 - Time is a flat circle

*Released on February 13, 2025*

Notably, includes a [fix](\[#17123]\(https://github.com/PrefectHQ/prefect/pull/17123\)) for multiple schedules with the same interval and different parameters.

**Bug Fixes 🐞**

* update idempotency key for scheduled runs to disambiguate schedules by [@zzstoatzz](https://github.com/zzstoatzz) in [#17123](https://github.com/PrefectHQ/prefect/pull/17123)

**Integrations & Dependencies 🤝**

* fix sed command in integration release CI by [@zzstoatzz](https://github.com/zzstoatzz) in [#17083](https://github.com/PrefectHQ/prefect/pull/17083)
* `prefect-snowflake` - Bump snowflake dependency by [@seanpwlms](https://github.com/seanpwlms) in [#17098](https://github.com/PrefectHQ/prefect/pull/17098)

**Development & Tidiness 🧹**

* consolidate use of `pendulum` in `prefect.cli` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17078](https://github.com/PrefectHQ/prefect/pull/17078)
* pendulum consolidation in `prefect.client` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17099](https://github.com/PrefectHQ/prefect/pull/17099)
* pendulum consolidation in `prefect.concurrency` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17102](https://github.com/PrefectHQ/prefect/pull/17102)
* pendulum consolidation in several modules by [@zzstoatzz](https://github.com/zzstoatzz) in [#17103](https://github.com/PrefectHQ/prefect/pull/17103)

**Documentation 📓**

* Add `PrefectDbtRunner` docs by [@kevingrismore](https://github.com/kevingrismore) in [#17055](https://github.com/PrefectHQ/prefect/pull/17055)
* Update `prefect-dbt` prerelease install command with `-U` by [@kevingrismore](https://github.com/kevingrismore) in [#17088](https://github.com/PrefectHQ/prefect/pull/17088)
* Update formatting of Prefect History timeline  by [@discdiver](https://github.com/discdiver) in [#17114](https://github.com/PrefectHQ/prefect/pull/17114)
* Remove link in ECS Guide by [@discdiver](https://github.com/discdiver) in [#17119](https://github.com/PrefectHQ/prefect/pull/17119)
* Docs: Update GCP integration docs by [@seanpwlms](https://github.com/seanpwlms) in [#17097](https://github.com/PrefectHQ/prefect/pull/17097)
* change docs sidebar items by [@aaazzam](https://github.com/aaazzam) in [#17128](https://github.com/PrefectHQ/prefect/pull/17128)

**Uncategorized**

* Fix printing `flow_run_id` in Abort case of engine by [@peterbygrave](https://github.com/peterbygrave) in [#17087](https://github.com/PrefectHQ/prefect/pull/17087)
* consolidate `pendulum` use in `prefect._internal` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17072](https://github.com/PrefectHQ/prefect/pull/17072)
* Add missing `load_function_and_convert_to_flow` by [@jakekaplan](https://github.com/jakekaplan) in [#17086](https://github.com/PrefectHQ/prefect/pull/17086)
* Fix bug where schedules without a slug or active raise a 500 by [@desertaxle](https://github.com/desertaxle) in [#17091](https://github.com/PrefectHQ/prefect/pull/17091)
* Migrate some `pendulum` usage to internal shim by [@desertaxle](https://github.com/desertaxle) in [#17074](https://github.com/PrefectHQ/prefect/pull/17074)
* Consolidate `pendulum` usage in `prefect.server.services` by [@desertaxle](https://github.com/desertaxle) in [#17100](https://github.com/PrefectHQ/prefect/pull/17100)
* Consolidate `pendulum` usage in `prefect.server` by [@desertaxle](https://github.com/desertaxle) in [#17104](https://github.com/PrefectHQ/prefect/pull/17104)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.1...3.2.2](https://github.com/PrefectHQ/prefect/compare/3.2.1...3.2.2)

***

## 3.2.1 - Everything flows and nothing abides

*Released on February 10, 2025*

**Enhancements ➕➕**

* Automatically convert non-flows into flows by [@jakekaplan](https://github.com/jakekaplan) in [#17024](https://github.com/PrefectHQ/prefect/pull/17024)

**Bug Fixes 🐞**

* Infer `PREFECT_PROFILES_PATH` from `PREFECT_HOME` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17070](https://github.com/PrefectHQ/prefect/pull/17070)
* Fix bug where a flow's parameter schema is not included in deployment create/update requests when using `prefect deploy` by [@desertaxle](https://github.com/desertaxle) in [#17079](https://github.com/PrefectHQ/prefect/pull/17079)

**Integrations & Dependencies 🤝**

* Bump ruff from 0.9.4 to 0.9.5 by [@dependabot](https://github.com/dependabot) in [#17035](https://github.com/PrefectHQ/prefect/pull/17035)

**Development & Tidiness 🧹**

* Use newer `npm` version in Docker UI build by [@desertaxle](https://github.com/desertaxle) in [#17064](https://github.com/PrefectHQ/prefect/pull/17064)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.0...3.2.1](https://github.com/PrefectHQ/prefect/compare/3.2.0...3.2.1)

***

## 3.2.0 - Param-a-lama-ding-dong

*Released on February 08, 2025*

This release contains a lot! In particular, users can now specify parameters on a per-schedule basis. This is useful for flows with multiple schedules, for example:

{/* pmd-metadata: notest */}

```python
from prefect import flow
from prefect.schedules import Cron

@flow
def send_email(to: str, message: str = "Stop goofing off!"):
    print(f"Sending email to {to} with message: {message}")

send_email.serve(
  name="my-flow",
  schedules=[
    Cron(
      "0 8 * * *",
      parameters={"to": "jim.halpert@dundermifflin.com"}
    ),
    Cron(
      "5 8 * * *",
      parameters={
        "to": "dwight.schrute@dundermifflin.com",
        "message": "Stop goofing off! You're assistant _to_ the regional manager!"
      }
    )
  ]
)
```

See [the documentation](https://docs.prefect.io/v3/automate/add-schedules#associate-parameters-with-schedules) for more details.

**Enhancements ➕➕**

* Update deployments PATCH endpoint to make more targeted updates with slugs by [@desertaxle](https://github.com/desertaxle) in [#17027](https://github.com/PrefectHQ/prefect/pull/17027)
* Update deployment SDK to use slugs by [@desertaxle](https://github.com/desertaxle) in [#17043](https://github.com/PrefectHQ/prefect/pull/17043)
* Update the SDK to use `PATCH /deployments/{id}` endpoint for existing deployments by [@desertaxle](https://github.com/desertaxle) in [#17050](https://github.com/PrefectHQ/prefect/pull/17050)
* Add database migration that adds parameter fields to deployment schedules by [@cicdw](https://github.com/cicdw) in [#16947](https://github.com/PrefectHQ/prefect/pull/16947)
* Add non-public implementation of parametrized schedules by [@cicdw](https://github.com/cicdw) in [#16951](https://github.com/PrefectHQ/prefect/pull/16951)
* Allow definition of per-schedule parameter overrides via `prefect.yaml` by [@desertaxle](https://github.com/desertaxle) in [#16963](https://github.com/PrefectHQ/prefect/pull/16963)
* Allow definition of per-schedule parameters via `.serve` and `.deploy` by [@desertaxle](https://github.com/desertaxle) in [#16965](https://github.com/PrefectHQ/prefect/pull/16965)
* Use retry logic of underlying prefect client properly by [@cicdw](https://github.com/cicdw) in [#16992](https://github.com/PrefectHQ/prefect/pull/16992)
* Remove some log noise in pause and abort handling by [@cicdw](https://github.com/cicdw) in [#17014](https://github.com/PrefectHQ/prefect/pull/17014)
* Allow for updating a deployment's parameter openapi schema by [@cicdw](https://github.com/cicdw) in [#17016](https://github.com/PrefectHQ/prefect/pull/17016)
* Allow for pull step updates on deployments by [@cicdw](https://github.com/cicdw) in [#17045](https://github.com/PrefectHQ/prefect/pull/17045)

**Bug Fixes 🐞**

* Remove unused function by [@cicdw](https://github.com/cicdw) in [#16923](https://github.com/PrefectHQ/prefect/pull/16923)
* fix `create_markdown_artifact` usage in `prefect-dbt` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16926](https://github.com/PrefectHQ/prefect/pull/16926)
* Add fix for creating profile with default name conflict by [@cicdw](https://github.com/cicdw) in [#16932](https://github.com/PrefectHQ/prefect/pull/16932)
* Fix: Event cleaning without timeouts by [@NobisIndustries](https://github.com/NobisIndustries) in [#16921](https://github.com/PrefectHQ/prefect/pull/16921)
* fix handling for bad `host` with `prefect server start` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16960](https://github.com/PrefectHQ/prefect/pull/16960)
* Add suggestion to pause schedules prior to upgrading by [@cicdw](https://github.com/cicdw) in [#16970](https://github.com/PrefectHQ/prefect/pull/16970)
* Target `wait` warning to more specific circumstances by [@cicdw](https://github.com/cicdw) in [#16969](https://github.com/PrefectHQ/prefect/pull/16969)
* support anonymous volumes in `docker` work pool by [@zzstoatzz](https://github.com/zzstoatzz) in [#17022](https://github.com/PrefectHQ/prefect/pull/17022)
* pin core above `3.1.15` for `prefect-dbt` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17010](https://github.com/PrefectHQ/prefect/pull/17010)
* Refactor `to_state_create` by [@cicdw](https://github.com/cicdw) in [#17033](https://github.com/PrefectHQ/prefect/pull/17033)
* Reject task run state change if the cache key is too large by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#16914](https://github.com/PrefectHQ/prefect/pull/16914)

**Integrations & Dependencies 🤝**

* Bumps to `ruff==0.9.2` and `mypy==1.14.1` by [@chrisguidry](https://github.com/chrisguidry) in [#16916](https://github.com/PrefectHQ/prefect/pull/16916)
* Add dbt profiles utilities by [@kevingrismore](https://github.com/kevingrismore) in [#16889](https://github.com/PrefectHQ/prefect/pull/16889)
* Update pytz requirement from `<2025,>=2021.1` to `>=2021.1,<2026` by [@dependabot](https://github.com/dependabot) in [#16936](https://github.com/PrefectHQ/prefect/pull/16936)
* Bump ruff from 0.9.2 to 0.9.4 by [@dependabot](https://github.com/dependabot) in [#16935](https://github.com/PrefectHQ/prefect/pull/16935)
* Add `PrefectDbtRunner` by [@kevingrismore](https://github.com/kevingrismore) in [#16971](https://github.com/PrefectHQ/prefect/pull/16971)
* fix: include region\_name when creating aws clients by [@obendidi](https://github.com/obendidi) in [#16811](https://github.com/PrefectHQ/prefect/pull/16811)

**Development & Tidiness 🧹**

* more pendulum consolidation by [@zzstoatzz](https://github.com/zzstoatzz) in [#16911](https://github.com/PrefectHQ/prefect/pull/16911)
* fix `emit_event` docstring by [@zzstoatzz](https://github.com/zzstoatzz) in [#16918](https://github.com/PrefectHQ/prefect/pull/16918)
* Update @prefecthq/prefect-ui-library to version 3.11.39 by [@marvin-robot](https://github.com/marvin-robot) in [#16919](https://github.com/PrefectHQ/prefect/pull/16919)
* Fix `prefect-dask` test suite by [@desertaxle](https://github.com/desertaxle) in [#16920](https://github.com/PrefectHQ/prefect/pull/16920)
* refactor work pool client methods by [@aaazzam](https://github.com/aaazzam) in [#16661](https://github.com/PrefectHQ/prefect/pull/16661)
* Update @prefecthq/prefect-ui-library to version 3.11.40 by [@marvin-robot](https://github.com/marvin-robot) in [#16929](https://github.com/PrefectHQ/prefect/pull/16929)
* Update @prefecthq/prefect-ui-library to version 3.11.41 by [@marvin-robot](https://github.com/marvin-robot) in [#16930](https://github.com/PrefectHQ/prefect/pull/16930)
* more pendulum consolidation by [@zzstoatzz](https://github.com/zzstoatzz) in [#16922](https://github.com/PrefectHQ/prefect/pull/16922)
* Unifies background service running between the web server and CLI by [@chrisguidry](https://github.com/chrisguidry) in [#16927](https://github.com/PrefectHQ/prefect/pull/16927)
* rm `pendulum` use in `schedules.py` by [@zzstoatzz](https://github.com/zzstoatzz) in [#16943](https://github.com/PrefectHQ/prefect/pull/16943)
* Add file exclusion to codeowners by [@cicdw](https://github.com/cicdw) in [#16957](https://github.com/PrefectHQ/prefect/pull/16957)
* Update a few more small things for labeler and review tags by [@cicdw](https://github.com/cicdw) in [#16958](https://github.com/PrefectHQ/prefect/pull/16958)
* Remove switching logic within settings config by [@cicdw](https://github.com/cicdw) in [#16961](https://github.com/PrefectHQ/prefect/pull/16961)
* Remove failure flag by [@cicdw](https://github.com/cicdw) in [#16974](https://github.com/PrefectHQ/prefect/pull/16974)
* Use nvm in pre-commit hooks by [@cicdw](https://github.com/cicdw) in [#16975](https://github.com/PrefectHQ/prefect/pull/16975)
* Fix labeler to remove unnecessary labels by [@cicdw](https://github.com/cicdw) in [#17009](https://github.com/PrefectHQ/prefect/pull/17009)
* Remove full team from schema json updates by [@cicdw](https://github.com/cicdw) in [#17008](https://github.com/PrefectHQ/prefect/pull/17008)
* Fix migration downgrades on deployment schedule table by [@cicdw](https://github.com/cicdw) in [#17044](https://github.com/PrefectHQ/prefect/pull/17044)
* Refactor results and result records to improve circular import situation by [@cicdw](https://github.com/cicdw) in [#17031](https://github.com/PrefectHQ/prefect/pull/17031)
* Update @prefecthq/prefect-ui-library to version 3.11.42 by [@marvin-robot](https://github.com/marvin-robot) in [#17046](https://github.com/PrefectHQ/prefect/pull/17046)

**Documentation 📓**

* Consolidates discovery of Prefect server `Service`s to the base class by [@chrisguidry](https://github.com/chrisguidry) in [#16913](https://github.com/PrefectHQ/prefect/pull/16913)
* Enhancement: Add New SLA Types by [@dylanbhughes](https://github.com/dylanbhughes) in [#16902](https://github.com/PrefectHQ/prefect/pull/16902)
* add notes on `TASK_SOURCE` behavior by [@zzstoatzz](https://github.com/zzstoatzz) in [#16928](https://github.com/PrefectHQ/prefect/pull/16928)
* fix(docs): small quickstart fixes by [@mitchnielsen](https://github.com/mitchnielsen) in [#16931](https://github.com/PrefectHQ/prefect/pull/16931)
* Chore: Add `/reference` redirects by [@znicholasbrown](https://github.com/znicholasbrown) in [#16980](https://github.com/PrefectHQ/prefect/pull/16980)
* chore: Add additional `reference` redirects by [@jimid27](https://github.com/jimid27) in [#16993](https://github.com/PrefectHQ/prefect/pull/16993)
* Update a few more links to the SDK reference by [@daniel-prefect](https://github.com/daniel-prefect) in [#16997](https://github.com/PrefectHQ/prefect/pull/16997)
* add docs on per-schedule parameters by [@zzstoatzz](https://github.com/zzstoatzz) in [#17000](https://github.com/PrefectHQ/prefect/pull/17000)
* add cli docs by [@aaazzam](https://github.com/aaazzam) in [#17037](https://github.com/PrefectHQ/prefect/pull/17037)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.1.15...3.2.0](https://github.com/PrefectHQ/prefect/compare/3.1.15...3.2.0)

***


# 3.3
Source: https://docs-3.prefect.io/v3/release-notes/oss/version-3-3



## 3.3.7 - Model Behavior

*Released on April 28, 2025*

**Enhancements ➕➕**

* Determine `field_keys` using `.model_fields` instead of `.model_json_schema` by [@ogenstad](https://github.com/ogenstad) in [#17908](https://github.com/PrefectHQ/prefect/pull/17908)

**Bug Fixes 🐞**

* Fix errors in `task-run ls` CLI by [@desertaxle](https://github.com/desertaxle) in [#17903](https://github.com/PrefectHQ/prefect/pull/17903)
* Fix `human_friendly_diff` when used with offset timezone by [@zzstoatzz](https://github.com/zzstoatzz) in [#17927](https://github.com/PrefectHQ/prefect/pull/17927)
* Fix scheduled run execution via `prefect-client` and add smoke test by [@desertaxle](https://github.com/desertaxle) in [#17920](https://github.com/PrefectHQ/prefect/pull/17920)

**Development & Tidiness 🧹**

* Add done callback before submitting by [@cicdw](https://github.com/cicdw) in [#17917](https://github.com/PrefectHQ/prefect/pull/17917)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.6...3.3.7](https://github.com/PrefectHQ/prefect/compare/3.3.6...3.3.7)

***

## 3.3.6 - One flow, many roads

*Released on April 24, 2025*

**Direct submission of workflows to dynamic infrastructure is in beta!**

We're pleased to announce the beta release of new infrastructure decorators enabling the submission of workflows directly to dynamic infrastructure.

This feature enables you to easily execute workflows on various infrastructure environments without the need for multiple deployments or managing persistent workers. This simplifies workflow definitions and enhances portability.

Here's a small example of the new `@kubernetes` decorator in action:

{/* pmd-metadata: notest */}

```python
from prefect import flow
from prefect_kubernetes import kubernetes

@kubernetes(work_pool="olympic")
@flow(result_storage="s3-bucket/remote-result-storage")
def my_k8s_flow():
    return "🏊‍♀️ Finished another lap!"

[@flow](https://github.com/flow)
def parent_flow():
    return my_k8s_flow() # will run in a Kubernetes cluster via the 'olympic' work pool

print(my_k8s_flow()) # prints "🏊‍♀️ Finished another lap!"
```

Check out the [docs](https://docs.prefect.io/v3/deploy/submit-flows-directly-to-dynamic-infrastructure) for more information on using this new feature.

Feedback is very important for us to help refine this feature while it's in beta. Give it a try, and share your feedback with us by [opening an issue](https://github.com/PrefectHQ/prefect/issues/new?template=1_bug_report.yaml)!

**Enhancements ➕➕**

* Add option to serve all tasks in a module by [@zzstoatzz](https://github.com/zzstoatzz) in [#17858](https://github.com/PrefectHQ/prefect/pull/17858)
* feat: Add support for a new `resolve_futures_to_results` function by [@Andrew-S-Rosen](https://github.com/Andrew-S-Rosen) in [#17869](https://github.com/PrefectHQ/prefect/pull/17869)
* Add global concurrency id to the create and update route for deployments by [@cbelsole](https://github.com/cbelsole) in [#17826](https://github.com/PrefectHQ/prefect/pull/17826)
* Add `submit` method to infrastructure-bound flows by [@desertaxle](https://github.com/desertaxle) in [#17896](https://github.com/PrefectHQ/prefect/pull/17896)
* Add deployment version info to `prefect deploy` by [@kevingrismore](https://github.com/kevingrismore) in [#17466](https://github.com/PrefectHQ/prefect/pull/17466)
* Add infrastructure decorators by [@desertaxle](https://github.com/desertaxle) in [#17863](https://github.com/PrefectHQ/prefect/pull/17863)
* Link submitted flows to their parent flow by [@desertaxle](https://github.com/desertaxle) in [#17894](https://github.com/PrefectHQ/prefect/pull/17894)
* Add `@docker` decorator by [@desertaxle](https://github.com/desertaxle) in [#17878](https://github.com/PrefectHQ/prefect/pull/17878)
* Add `with_options` implementation to `InfrastructureBoundFlow` by [@desertaxle](https://github.com/desertaxle) in [#17900](https://github.com/PrefectHQ/prefect/pull/17900)

**Bug Fixes 🐞**

* Update `pydantic-settings` version pin by [@desertaxle](https://github.com/desertaxle) in [#17853](https://github.com/PrefectHQ/prefect/pull/17853)
* Propagates the currently triggering event (if any) for composite triggers by [@chrisguidry](https://github.com/chrisguidry) in [#17854](https://github.com/PrefectHQ/prefect/pull/17854)
* Polishes the experience with inferring versioning by [@chrisguidry](https://github.com/chrisguidry) in [#17901](https://github.com/PrefectHQ/prefect/pull/17901)
* Fix warning on reconnect by [@mslavoshevskii](https://github.com/mslavoshevskii) in [#17876](https://github.com/PrefectHQ/prefect/pull/17876)

**Development & Tidiness 🧹**

* Move decorated function discovery out of the cli by [@zzstoatzz](https://github.com/zzstoatzz) in [#17840](https://github.com/PrefectHQ/prefect/pull/17840)

**Documentation 📓**

* Add initial documentation for submitting workflows directly to dynamic infrastructure by [@desertaxle](https://github.com/desertaxle) in [#17861](https://github.com/PrefectHQ/prefect/pull/17861)
* Fix dead integration link by [@zzstoatzz](https://github.com/zzstoatzz) in [#17831](https://github.com/PrefectHQ/prefect/pull/17831)
* Nginx sample config + note about client API key/auth string precedence by [@ColinMaudry](https://github.com/ColinMaudry) in [#17810](https://github.com/PrefectHQ/prefect/pull/17810)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.5...3.3.6](https://github.com/PrefectHQ/prefect/compare/3.3.5...3.3.6)

***

## 3.3.5 - Don't block, just commit

*Released on April 17, 2025*

**Enhancements ➕➕**

* Add async interface for transactions by [@desertaxle](https://github.com/desertaxle) in [#17794](https://github.com/PrefectHQ/prefect/pull/17794)

**Bug Fixes 🐞**

* Use platform-independent method in telemetry instrumentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#17824](https://github.com/PrefectHQ/prefect/pull/17824)
* Respect auth for websockets by [@zzstoatzz](https://github.com/zzstoatzz) in [#17741](https://github.com/PrefectHQ/prefect/pull/17741)
* Fixes `Runner` command handling for Windows by [@desertaxle](https://github.com/desertaxle) in [#17839](https://github.com/PrefectHQ/prefect/pull/17839)

**Integrations & Dependencies 🤝**

* Fix null `Scheduling` case in Vertex worker by [@kevingrismore](https://github.com/kevingrismore) in [#17835](https://github.com/PrefectHQ/prefect/pull/17835)
* Update @prefecthq/prefect-design to version 2.14.23 by [@marvin-robot](https://github.com/marvin-robot) in [#17845](https://github.com/PrefectHQ/prefect/pull/17845)
* Update @prefecthq/prefect-ui-library to version 3.12.1 by [@marvin-robot](https://github.com/marvin-robot) in [#17847](https://github.com/PrefectHQ/prefect/pull/17847)

**Development & Tidiness 🧹**

* Improve schema and documentation generation pre-commit steps by [@zzstoatzz](https://github.com/zzstoatzz) in [#17800](https://github.com/PrefectHQ/prefect/pull/17800)
* Fix typing errors by [@zzstoatzz](https://github.com/zzstoatzz) in [#17841](https://github.com/PrefectHQ/prefect/pull/17841)
* Add default version when the version cannot be found by [@teocns](https://github.com/teocns) in [#17802](https://github.com/PrefectHQ/prefect/pull/17802)

**Documentation 📓**

* Update background tasks docs and add guide by [@zzstoatzz](https://github.com/zzstoatzz) in [#17783](https://github.com/PrefectHQ/prefect/pull/17783)
* Update `prefect:managed` docs by [@jakekaplan](https://github.com/jakekaplan) in [#17808](https://github.com/PrefectHQ/prefect/pull/17808)
* Quickstart docs by [@aaazzam](https://github.com/aaazzam) in [#17726](https://github.com/PrefectHQ/prefect/pull/17726)
* Update deployment and remote code storage docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#17819](https://github.com/PrefectHQ/prefect/pull/17819)
* Add terraform example for deployment trigger by [@parkedwards](https://github.com/parkedwards) in [#17829](https://github.com/PrefectHQ/prefect/pull/17829)
* Update sync/async example in `prefect-slack` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17832](https://github.com/PrefectHQ/prefect/pull/17832)
* Clean up dbt integration docs by [@kevingrismore](https://github.com/kevingrismore) in [#17838](https://github.com/PrefectHQ/prefect/pull/17838)

**Experimental 🧪**

* Add experimental bundle steps for Azure Blob Storage by [@desertaxle](https://github.com/desertaxle) in [#17825](https://github.com/PrefectHQ/prefect/pull/17825)
* Add `.submit` method to `BaseWorker` by [@desertaxle](https://github.com/desertaxle) in [#17828](https://github.com/PrefectHQ/prefect/pull/17828)
* Add `InfrastructureBoundFlow` class and `bind_flow_to_infrastructure` function by [@desertaxle](https://github.com/desertaxle) in [#17833](https://github.com/PrefectHQ/prefect/pull/17833)
* Add CLI to configure GCS storage for a work pool by [@desertaxle](https://github.com/desertaxle) in [#17836](https://github.com/PrefectHQ/prefect/pull/17836)
* Add CLI to configure Azure Blob Storage for a work pool by [@desertaxle](https://github.com/desertaxle) in [#17837](https://github.com/PrefectHQ/prefect/pull/17837)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.4...3.3.5](https://github.com/PrefectHQ/prefect/compare/3.3.4...3.3.5)

***

## 3.3.4 - Support for 3.13 in All Integrations - A Triskaidekaphobe's Worst Nightmare

*Released on April 11, 2025*

**Enhancements ➕➕**

* Added support for embedding image in mail by [@lavishkhandelwal](https://github.com/lavishkhandelwal) in [#17790](https://github.com/PrefectHQ/prefect/pull/17790)
* allow configuring `RecentDeploymentScheduler` loop interval by [@zzstoatzz](https://github.com/zzstoatzz) in [#17795](https://github.com/PrefectHQ/prefect/pull/17795)

**Bug Fixes 🐞**

* Avoid deleting runs where execution has been attempted or are past their scheduled start date by [@desertaxle](https://github.com/desertaxle) in [#17769](https://github.com/PrefectHQ/prefect/pull/17769)
* Update event occurred + related resource indexes for Postgres by [@desertaxle](https://github.com/desertaxle) in [#17731](https://github.com/PrefectHQ/prefect/pull/17731)
* Fix readiness\_result type to match expected Process type by [@Igort4](https://github.com/Igort4) in [#17771](https://github.com/PrefectHQ/prefect/pull/17771)
* deprecate runner webserver machinery by [@zzstoatzz](https://github.com/zzstoatzz) in [#17775](https://github.com/PrefectHQ/prefect/pull/17775)
* Only prompt to save if file does not exist by [@cicdw](https://github.com/cicdw) in [#17519](https://github.com/PrefectHQ/prefect/pull/17519)

**Development & Tidiness 🧹**

* update classifiers and matrix generation for integrations 3.13 support by [@zzstoatzz](https://github.com/zzstoatzz) in [#17791](https://github.com/PrefectHQ/prefect/pull/17791)
* avoid unexpected pre-commit diffs from local to CI by [@zzstoatzz](https://github.com/zzstoatzz) in [#17779](https://github.com/PrefectHQ/prefect/pull/17779)
* Update @prefecthq/prefect-ui-library to version 3.11.55 by [@marvin-robot](https://github.com/marvin-robot) in [#17786](https://github.com/PrefectHQ/prefect/pull/17786)
* Update @prefecthq/prefect-ui-library to version 3.12.0 by [@marvin-robot](https://github.com/marvin-robot) in [#17801](https://github.com/PrefectHQ/prefect/pull/17801)

**Experimental**

* Add GCS bundle upload and execute steps by [@desertaxle](https://github.com/desertaxle) in [#17781](https://github.com/PrefectHQ/prefect/pull/17781)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.3...3.3.4](https://github.com/PrefectHQ/prefect/compare/3.3.3...3.3.4)

***

## 3.3.3 - Where were you at midnight UTC on January 1st,  1 AD?

*Released on April 05, 2025*

Includes a [fix](\[#17747]\(https://github.com/PrefectHQ/prefect/pull/17747\)) for a [bug](https://github.com/PrefectHQ/prefect/issues/17729) loading the flow run graph caused by an incorrect timezone-naive default.

**Enhancements ➕➕**

* Add server side error handling to block class registration by [@cicdw](https://github.com/cicdw) in [#17670](https://github.com/PrefectHQ/prefect/pull/17670)

**Bug Fixes 🐞**

* `prefect-dask`: fix string `cluster_class` instantiation by [@zzstoatzz](https://github.com/zzstoatzz) in [#17737](https://github.com/PrefectHQ/prefect/pull/17737)
* Include timezone in default `since` value for flow run graph v2 endpoint by [@desertaxle](https://github.com/desertaxle) in [#17747](https://github.com/PrefectHQ/prefect/pull/17747)

**Integrations & Dependencies 🤝**

* docs(prefect-ray): `.wait()` needed by [@joscha](https://github.com/joscha) in [#17732](https://github.com/PrefectHQ/prefect/pull/17732)

**Experimental**

* Add deployment branch schemas and client methods by [@zangell44](https://github.com/zangell44) in [#17715](https://github.com/PrefectHQ/prefect/pull/17715)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.2...3.3.3](https://github.com/PrefectHQ/prefect/compare/3.3.2...3.3.3)

***

## 3.3.2 - Just Pumping My GitHub Stats Again

*Released on April 03, 2025*

**Bug Fixes 🐞**

* Update `Cron` `day_or` default to match `croniter` default by [@desertaxle](https://github.com/desertaxle) in [#17675](https://github.com/PrefectHQ/prefect/pull/17675)
* Use platform independent datetime in `prefect version` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17692](https://github.com/PrefectHQ/prefect/pull/17692)
* Fix `redis` locking by [@zzstoatzz](https://github.com/zzstoatzz) in [#17679](https://github.com/PrefectHQ/prefect/pull/17679)
* fix improper reuse of client context in new thread by [@zzstoatzz](https://github.com/zzstoatzz) in [#17719](https://github.com/PrefectHQ/prefect/pull/17719)

**Integrations & Dependencies 🤝**

* Fix `pydantic` deprecation warnings by [@zzstoatzz](https://github.com/zzstoatzz) in [#17698](https://github.com/PrefectHQ/prefect/pull/17698)
* Bumps Jinja2 to address CVE-2025-27516 by [@chrisguidry](https://github.com/chrisguidry) in [#17697](https://github.com/PrefectHQ/prefect/pull/17697)

**Development & Tidiness 🧹**

* use official `uv` lock pre-commit by [@zzstoatzz](https://github.com/zzstoatzz) in [#17662](https://github.com/PrefectHQ/prefect/pull/17662)
* update `self.model_fields` -> `type(self).model_fields` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17681](https://github.com/PrefectHQ/prefect/pull/17681)
* chore(deps): bump helm/kind-action from 1.8.0 to 1.12.0 by [@dependabot](https://github.com/dependabot) in [#17395](https://github.com/PrefectHQ/prefect/pull/17395)
* update pin for `prefect-ray` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17680](https://github.com/PrefectHQ/prefect/pull/17680)
* switch to stdlib datetime by [@zzstoatzz](https://github.com/zzstoatzz) in [#17694](https://github.com/PrefectHQ/prefect/pull/17694)

**Documentation 📓**

* Omit UI routes from the REST API reference docs by [@desertaxle](https://github.com/desertaxle) in [#17716](https://github.com/PrefectHQ/prefect/pull/17716)
* Update README with new community and contribution details by [@radhigulati](https://github.com/radhigulati) in [#17706](https://github.com/PrefectHQ/prefect/pull/17706)

**Experimental**

* Includes `Deployment` versioning info in flow run execution event by [@chrisguidry](https://github.com/chrisguidry) in [#17701](https://github.com/PrefectHQ/prefect/pull/17701)
* Add version and branching info to `DeploymentCreate` and `DeploymentUpdate` by [@zangell44](https://github.com/zangell44) in [#17711](https://github.com/PrefectHQ/prefect/pull/17711)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.1...3.3.2](https://github.com/PrefectHQ/prefect/compare/3.3.1...3.3.2)

***

## 3.3.1

*Released on April 01, 2025*

[Alleviates](\[#17671]\(https://github.com/PrefectHQ/prefect/pull/17671\)) a potential error `ValueError: Must provide start_date as a datetime` caused by changes to deprecation utils in [#17577](https://github.com/PrefectHQ/prefect/pull/17577).

**Enhancements ➕➕**

* Added worker for Snowflake's Snowpark Container Services by [@bjorhn](https://github.com/bjorhn) in [#16393](https://github.com/PrefectHQ/prefect/pull/16393)

**Bug Fixes 🐞**

* Fixes class instance tasks and flows when called directly on a class by [@desertaxle](https://github.com/desertaxle) in [#17660](https://github.com/PrefectHQ/prefect/pull/17660)
* Update `DaskTaskRunner` to lazily load the Dask client by [@desertaxle](https://github.com/desertaxle) in [#17648](https://github.com/PrefectHQ/prefect/pull/17648)
* handle `targeted_retries=0` in `run_dbt_cloud_job` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17663](https://github.com/PrefectHQ/prefect/pull/17663)
* temporarily allow `str` or `datetime` for `generate_deprecation_message` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17671](https://github.com/PrefectHQ/prefect/pull/17671)

**Development & Tidiness 🧹**

* Add logic to handle cancel\_scope None by [@cicdw](https://github.com/cicdw) in [#17659](https://github.com/PrefectHQ/prefect/pull/17659)
* include 3.13 tags in matrix by [@zzstoatzz](https://github.com/zzstoatzz) in [#17666](https://github.com/PrefectHQ/prefect/pull/17666)
* chore(prefect-client): allow indefinite retries during maintenance by [@parkedwards](https://github.com/parkedwards) in [#17667](https://github.com/PrefectHQ/prefect/pull/17667)

**Documentation 📓**

* docs: correct worker type for Google Cloud Run V2 by [@rcash](https://github.com/rcash) in [#17669](https://github.com/PrefectHQ/prefect/pull/17669)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.0...3.3.1](https://github.com/PrefectHQ/prefect/compare/3.3.0...3.3.1)

***

## 3.3.0 - Whenever, wherever

*Released on March 31, 2025*

We're excited to announce Python 3.13 support!

To accommodate Python 3.13, we've switched from `pendulum` to [`whenever`](https://github.com/ariebovenberg/whenever) for handling date/time functionality. This change currently applies only when installing `prefect` with Python 3.13; environments using Python 3.12 and below will continue using `pendulum`. We plan to fully transition to whenever for all Python versions in a future release.

Additionally, this release cleans up deprecated features whose deprecation periods have ended. For detailed information on removed functionalities, see [#17632](https://github.com/PrefectHQ/prefect/pull/17632).

**Enhancements ➕➕**

* Add Python 3.13 support by [@desertaxle](https://github.com/desertaxle) in [#17577](https://github.com/PrefectHQ/prefect/pull/17577)

**Bug Fixes 🐞**

* Remove extra `getattr` calls in `visit_collection` for `pydantic` objects by [@zzstoatzz](https://github.com/zzstoatzz) in [#17636](https://github.com/PrefectHQ/prefect/pull/17636)
* Handle all `emit_event` errors and log them by [@cicdw](https://github.com/cicdw) in [#17658](https://github.com/PrefectHQ/prefect/pull/17658)
* Update UI file permissions by [@happysalada](https://github.com/happysalada) in [#17644](https://github.com/PrefectHQ/prefect/pull/17644)
* Explicitly disallow async rollback hooks until supported by [@zzstoatzz](https://github.com/zzstoatzz) in [#17638](https://github.com/PrefectHQ/prefect/pull/17638)

**Development & Tidiness 🧹**

* Remove code past its marked deprecation date by [@desertaxle](https://github.com/desertaxle) in [#17632](https://github.com/PrefectHQ/prefect/pull/17632)
* Update @prefecthq/prefect-ui-library to version 3.11.54 by [@marvin-robot](https://github.com/marvin-robot) in [#17640](https://github.com/PrefectHQ/prefect/pull/17640)
* Update rich requirement from `<14.0,>=11.0` to `>=11.0,<15.0` by [@dependabot](https://github.com/dependabot) in [#17651](https://github.com/PrefectHQ/prefect/pull/17651)

**Documentation 📓**

* Fix broken link in docs for settings reference documentation by [@rcash](https://github.com/rcash) in [#17639](https://github.com/PrefectHQ/prefect/pull/17639)
* Fix Google Cloud run worker guide link by [@rcash](https://github.com/rcash) in [#17642](https://github.com/PrefectHQ/prefect/pull/17642)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.2.15...3.3.0](https://github.com/PrefectHQ/prefect/compare/3.2.15...3.3.0)

***


# 3.4
Source: https://docs-3.prefect.io/v3/release-notes/oss/version-3-4



## 3.4.19 - Pay No Attention To That GCL Behind The Curtain

*Released on September 19, 2025*

**Enhancements ➕➕**

* split `deploy.py` into a module by [@zzstoatzz](https://github.com/zzstoatzz) in [#18925](https://github.com/PrefectHQ/prefect/pull/18925)
* Add minimal V1→V2 concurrency adapter by [@zzstoatzz](https://github.com/zzstoatzz) in [#18971](https://github.com/PrefectHQ/prefect/pull/18971)
* Update task concurrency slot orchestration rules to work with global concurrency limits by [@desertaxle](https://github.com/desertaxle) in [#18983](https://github.com/PrefectHQ/prefect/pull/18983)
* Update task engine to use GCLs to limit task concurrency by [@desertaxle](https://github.com/desertaxle) in [#18982](https://github.com/PrefectHQ/prefect/pull/18982)
* Migrate V1 concurrency limits to V2 format in database by [@zzstoatzz](https://github.com/zzstoatzz) in [#18968](https://github.com/PrefectHQ/prefect/pull/18968)
* Add pagination support to lease storage `read_active_lease_ids` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18973](https://github.com/PrefectHQ/prefect/pull/18973)
* Add `list_holders_for_limit` to `ConcurrencyLeaseStorage` protocol by [@zzstoatzz](https://github.com/zzstoatzz) in [#18970](https://github.com/PrefectHQ/prefect/pull/18970)

**Bug Fixes 🐞**

* Fix `set_working_directory` to return absolute path by [@desertaxle](https://github.com/desertaxle) in [#18932](https://github.com/PrefectHQ/prefect/pull/18932)
* Silence retryable SQLite lock errors by [@zzstoatzz](https://github.com/zzstoatzz) in [#18957](https://github.com/PrefectHQ/prefect/pull/18957)
* Fix `wait()` to monitor all futures concurrently with timeout by [@zzstoatzz](https://github.com/zzstoatzz) in [#18960](https://github.com/PrefectHQ/prefect/pull/18960)
* Fix blocks not registering schema for nested Blocks in piped union types by [@GalLadislav](https://github.com/GalLadislav) in [#18920](https://github.com/PrefectHQ/prefect/pull/18920)
* Fix atomicity issue in GCL-backed tag-based concurrency limits by [@desertaxle](https://github.com/desertaxle) in [#18991](https://github.com/PrefectHQ/prefect/pull/18991)

**Development & Tidiness 🧹**

* Add Python environment setup to Claude workflow by [@desertaxle](https://github.com/desertaxle) in [#18931](https://github.com/PrefectHQ/prefect/pull/18931)
* Add models for validating loaded `prefect.yaml` files by [@desertaxle](https://github.com/desertaxle) in [#18941](https://github.com/PrefectHQ/prefect/pull/18941)
* Replace pre-push docs generation with GitHub Action by [@desertaxle](https://github.com/desertaxle) in [#18930](https://github.com/PrefectHQ/prefect/pull/18930)
* Install `mdxify` explicitly in CI by [@desertaxle](https://github.com/desertaxle) in [#18954](https://github.com/PrefectHQ/prefect/pull/18954)
* Add starlette status code compatibility layer by [@zzstoatzz](https://github.com/zzstoatzz) in [#18963](https://github.com/PrefectHQ/prefect/pull/18963)

**Documentation 📓**

* fix: add redirect setting to docs.json to fix /latest path 404s by [@zzstoatzz](https://github.com/zzstoatzz) in [#18945](https://github.com/PrefectHQ/prefect/pull/18945)
* fix: add errors.404.redirect setting to fix /latest path 404s by [@zzstoatzz](https://github.com/zzstoatzz) in [#18946](https://github.com/PrefectHQ/prefect/pull/18946)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.18...3.4.19](https://github.com/PrefectHQ/prefect/compare/3.4.18...3.4.19)

***

## 3.4.18 - He who holds the leases controls the universe

*Released on September 12, 2025*

**Enhancements ➕➕**

* Add bulk pause/resume commands for deployment schedules by [@zzstoatzz](https://github.com/zzstoatzz) in [#18860](https://github.com/PrefectHQ/prefect/pull/18860)
* Add holder parameter to V2 concurrency endpoints by [@zzstoatzz](https://github.com/zzstoatzz) in [#18887](https://github.com/PrefectHQ/prefect/pull/18887)

**Bug Fixes 🐞**

* preserve user-configured root logger on import by [@zzstoatzz](https://github.com/zzstoatzz) in [#18873](https://github.com/PrefectHQ/prefect/pull/18873)
* Fix `FileExistsError` in runner temp directory creation by [@zzstoatzz](https://github.com/zzstoatzz) in [#18864](https://github.com/PrefectHQ/prefect/pull/18864)
* Fix race condition in ProactiveTriggers service by [@desertaxle](https://github.com/desertaxle) in [#18909](https://github.com/PrefectHQ/prefect/pull/18909)

**Development & Tidiness 🧹**

* Add pre-commit instruction to Claude GitHub workflow by [@zzstoatzz](https://github.com/zzstoatzz) in [#18910](https://github.com/PrefectHQ/prefect/pull/18910)
* fix: use ruff-check instead of legacy ruff alias in pre-commit by [@zzstoatzz](https://github.com/zzstoatzz) in [#18914](https://github.com/PrefectHQ/prefect/pull/18914)
* Update git version constraint in dockerfile by [@cicdw](https://github.com/cicdw) in [#18916](https://github.com/PrefectHQ/prefect/pull/18916)
* Add Claude Code GitHub Workflow by [@zzstoatzz](https://github.com/zzstoatzz) in [#18908](https://github.com/PrefectHQ/prefect/pull/18908)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.17...3.4.18](https://github.com/PrefectHQ/prefect/compare/3.4.17...3.4.18)

***

## 3.4.17 - Distribution Matters

*Released on September 05, 2025*

**Bug Fixes 🐞**

* Run `Distributor` and `LogDistributor` in Prefect API servers by [@desertaxle](https://github.com/desertaxle) in [#18868](https://github.com/PrefectHQ/prefect/pull/18868)

**Development & Tidiness 🧹**

* Add `--ref` flag to trigger OSS testbed image update by [@desertaxle](https://github.com/desertaxle) in [#18863](https://github.com/PrefectHQ/prefect/pull/18863)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.16...3.4.17](https://github.com/PrefectHQ/prefect/compare/3.4.16...3.4.17)

***

## 3.4.16 - Background Noise Reduction

*Released on September 05, 2025*

**Enhancements ➕➕**

* Wait until determining deployment create or update to add deployment schedules by [@kevingrismore](https://github.com/kevingrismore) in [#18823](https://github.com/PrefectHQ/prefect/pull/18823)
* Display postgresql version on prefect version by [@hanhwanglim](https://github.com/hanhwanglim) in [#18836](https://github.com/PrefectHQ/prefect/pull/18836)
* More robust `write_path` method in `RemoteFileSystem` to handle SMB UNC paths.  by [@tom21100227](https://github.com/tom21100227) in [#18824](https://github.com/PrefectHQ/prefect/pull/18824)

**Bug Fixes 🐞**

* Fix nested `.delay()` serialization issue by [@zzstoatzz](https://github.com/zzstoatzz) in [#18849](https://github.com/PrefectHQ/prefect/pull/18849)
* Fix `result_async` race condition using final state from waiter by [@zzstoatzz](https://github.com/zzstoatzz) in [#18850](https://github.com/PrefectHQ/prefect/pull/18850)
* Improve multi-server scaling for triggers by [@desertaxle](https://github.com/desertaxle) in [#18820](https://github.com/PrefectHQ/prefect/pull/18820)
* Fix AttributeError in create\_flow\_run\_from\_deployment (#18707) by [@eddiemaru-101](https://github.com/eddiemaru-101) in [#18807](https://github.com/PrefectHQ/prefect/pull/18807)
* Kubernetes label disable lowercase by [@raniasev](https://github.com/raniasev) in [#18841](https://github.com/PrefectHQ/prefect/pull/18841)
* Add an additional check to obscure basic auth credentials when `git clone` fails by [@desertaxle](https://github.com/desertaxle) in [#18845](https://github.com/PrefectHQ/prefect/pull/18845)
* Preserve dev version info when generating docker image tag by [@desertaxle](https://github.com/desertaxle) in [#18854](https://github.com/PrefectHQ/prefect/pull/18854)

**Development & Tidiness 🧹**

* Remove unnecessary 'No retries configured' message from task failure logs by [@zzstoatzz](https://github.com/zzstoatzz) in [#18844](https://github.com/PrefectHQ/prefect/pull/18844)
* Drop `--refresh-package` from `mdxify` use in api ref gen by [@zzstoatzz](https://github.com/zzstoatzz) in [#18851](https://github.com/PrefectHQ/prefect/pull/18851)
* Claude prompts by [@zzstoatzz](https://github.com/zzstoatzz) in [#18833](https://github.com/PrefectHQ/prefect/pull/18833)
* Add trigger to update the OSS testbed image on Docker image release by [@desertaxle](https://github.com/desertaxle) in [#18853](https://github.com/PrefectHQ/prefect/pull/18853)
* Remove stale mdx files from api ref by [@zzstoatzz](https://github.com/zzstoatzz) in [#18828](https://github.com/PrefectHQ/prefect/pull/18828)

**Documentation 📓**

* Update incorrect push action description by [@mjarosie](https://github.com/mjarosie) in [#18834](https://github.com/PrefectHQ/prefect/pull/18834)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.15...3.4.16](https://github.com/PrefectHQ/prefect/compare/3.4.15...3.4.16)

***

## 3.4.15 - Emit me maybe

*Released on August 29, 2025*

**New Features 🎉**

* **Event emission from the command line with `prefect event emit`**

  Emit events directly from external systems with the new `prefect event emit` CLI command. Perfect for triggering deployment runs from CI/CD!

  ```bash
  prefect event emit user.logged_in --resource-id user-123
  prefect event emit order.shipped --resource-id order-456 --payload '{"tracking": "ABC123"}'
  ```

  by [@zzstoatzz](https://github.com/zzstoatzz) in [#18813](https://github.com/PrefectHQ/prefect/pull/18813)

**Enhancements ➕➕**

* Add `schedule_after` field to `RunDeployment` action for delayed execution by [@chrisguidry](https://github.com/chrisguidry) in [#18801](https://github.com/PrefectHQ/prefect/pull/18801)
* Update deployment concurrency limit lease maintenance to raise on failure by [@desertaxle](https://github.com/desertaxle) in [#18811](https://github.com/PrefectHQ/prefect/pull/18811)
* Enable metrics server on workers by [@bdalpe](https://github.com/bdalpe) in [#18630](https://github.com/PrefectHQ/prefect/pull/18630)
* Add artifact created and updated events by [@zangell44](https://github.com/zangell44) in [#18818](https://github.com/PrefectHQ/prefect/pull/18818)

**Bug Fixes 🐞**

* Fix metric trigger validation in automations schema by [@zzstoatzz](https://github.com/zzstoatzz) in [#18773](https://github.com/PrefectHQ/prefect/pull/18773)
* Fix event filter empty label value arrays to return no results by [@chrisguidry](https://github.com/chrisguidry) in [#18810](https://github.com/PrefectHQ/prefect/pull/18810)
* Special case for proactive automation by [@jakekaplan](https://github.com/jakekaplan) in [#18819](https://github.com/PrefectHQ/prefect/pull/18819)
* Add dictionary handling into `_to_environment_variable_value` by [@vyagubov](https://github.com/vyagubov) in [#18817](https://github.com/PrefectHQ/prefect/pull/18817)

**Development & Tidiness 🧹**

* Fix workflow to publish `prefect-aws` images when triggered via `workflow_call` by [@desertaxle](https://github.com/desertaxle) in [#18763](https://github.com/PrefectHQ/prefect/pull/18763)
* Bump `ruff` from 0.12.8 to 0.12.10 by [@dependabot](https://github.com/dependabot)\[bot] in [#18768](https://github.com/PrefectHQ/prefect/pull/18768)
* Fix CloudFormation template generation during `prefect-aws` release by [@desertaxle](https://github.com/desertaxle) in [#18792](https://github.com/PrefectHQ/prefect/pull/18792)
* Skip validating generated CloudFormation templates by [@desertaxle](https://github.com/desertaxle) in [#18794](https://github.com/PrefectHQ/prefect/pull/18794)
* Add `uv` set up to integration package release by [@desertaxle](https://github.com/desertaxle) in [#18793](https://github.com/PrefectHQ/prefect/pull/18793)

**Documentation 📓**

* Overhaul ECS Worker Guide by [@bdalpe](https://github.com/bdalpe) in [#18756](https://github.com/PrefectHQ/prefect/pull/18756)
* Add `PREFECT_SERVER_EVENTS_CAUSAL_ORDERING` to self-hosted docs by [@zzstoatzz](https://github.com/zzstoatzz) in [#18774](https://github.com/PrefectHQ/prefect/pull/18774)
* Fix `profiles_path` rendering in settings ref by [@rcash](https://github.com/rcash) in [#18772](https://github.com/PrefectHQ/prefect/pull/18772)
* Document PostgreSQL 14.9+ requirement by [@desertaxle](https://github.com/desertaxle) in [#18784](https://github.com/PrefectHQ/prefect/pull/18784)
* Add SQS queue and EventBridge setup to ECS worker manual deployment guide by [@desertaxle](https://github.com/desertaxle) in [#18789](https://github.com/PrefectHQ/prefect/pull/18789)
* Fix Docker healthcheck documentation to use Python instead of `curl` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18809](https://github.com/PrefectHQ/prefect/pull/18809)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.14...3.4.15](https://github.com/PrefectHQ/prefect/compare/3.4.14...3.4.15)

***

## 3.4.14 - Ctrl+C, Ctrl+V

*Released on August 21, 2025*

**New Features 🎉**

* **Environment Migration with `prefect transfer`**

  Transfer your Prefect setup between backends with a single command! Idempotently migrate work pools, deployments, blocks, variables, and concurrency limits between self-hosted servers and Prefect Cloud.

  [Check the Prefect dev log for more info!](https://dev-log.prefect.io/we-love-a-good-graph/)

* **Parallel task execution with `ProcessPoolTaskRunner`**

  This new task runner executes tasks in separate subprocesses and while maintaining run context so you get full observability while running in parallel. A great choice if you need parallelism, but aren't ready to start using `dask` or `ray`.

  [Check the PR for more info!](https://github.com/PrefectHQ/prefect/pull/18724)

**Enhancements ➕➕**

* Add `count_flow_runs` to prefect client by [@hanhwanglim](https://github.com/hanhwanglim) in [#18713](https://github.com/PrefectHQ/prefect/pull/18713)
* Update bundle creation to exclude dependencies installed from a local file path by [@desertaxle](https://github.com/desertaxle) in [#18743](https://github.com/PrefectHQ/prefect/pull/18743)

**Bug Fixes 🐞**

* Fix apprise notifications failing silently with `prefect_default` notification type by [@zzstoatzz](https://github.com/zzstoatzz) in [#18720](https://github.com/PrefectHQ/prefect/pull/18720)
* Fix error log when using a concurrency limit with a lease in strict mode by [@desertaxle](https://github.com/desertaxle) in [#18725](https://github.com/PrefectHQ/prefect/pull/18725)
* Fix total run time calculation for tasks by [@desertaxle](https://github.com/desertaxle) in [#18759](https://github.com/PrefectHQ/prefect/pull/18759)

**Development & Tidiness 🧹**

* Relax upper bound on `click` by [@desertaxle](https://github.com/desertaxle) in [#18731](https://github.com/PrefectHQ/prefect/pull/18731)
* Avoid key collision in tests by [@zzstoatzz](https://github.com/zzstoatzz) in [#18733](https://github.com/PrefectHQ/prefect/pull/18733)
* Run SDK API reference generation as `pre-push` hook by [@zzstoatzz](https://github.com/zzstoatzz) in [#18736](https://github.com/PrefectHQ/prefect/pull/18736)
* Deflake concurrency limit integration tests by [@desertaxle](https://github.com/desertaxle) in [#18745](https://github.com/PrefectHQ/prefect/pull/18745)
* Remove cloud telemetry sending infrastructure while preserving instrumentation by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#18739](https://github.com/PrefectHQ/prefect/pull/18739)

**Documentation 📓**

* Add `ProcessPoolTaskRunner` docs and `ThreadPoolTaskRunner` examples by [@zzstoatzz](https://github.com/zzstoatzz) in [#18734](https://github.com/PrefectHQ/prefect/pull/18734)
* Fix incorrect keys in automation by [@zzstoatzz](https://github.com/zzstoatzz) in [#18760](https://github.com/PrefectHQ/prefect/pull/18760)
* Use a consistent repo URL when generating SDK reference docs by [@desertaxle](https://github.com/desertaxle) in [#18761](https://github.com/PrefectHQ/prefect/pull/18761)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.13...3.4.14](https://github.com/PrefectHQ/prefect/compare/3.4.13...3.4.14)

***

## 3.4.13 - No, Your Database Cannot Have a Little Lock, Even As a Treat

*Released on August 14, 2025*

**Bug Fixes 🐞**

* Use server base path configuration when creating internal client by [@anton-daneyko-ultramarin](https://github.com/anton-daneyko-ultramarin) in [#18668](https://github.com/PrefectHQ/prefect/pull/18668)
* Fix TypeError with apprise 1.9.4 when adding notify type by [@zzstoatzz](https://github.com/zzstoatzz) in [#18697](https://github.com/PrefectHQ/prefect/pull/18697)
* Fix DB locks during DB clear with postgres by [@desertaxle](https://github.com/desertaxle) in [#18684](https://github.com/PrefectHQ/prefect/pull/18684)

**Documentation 📓**

* Add integration release notes section to documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#18711](https://github.com/PrefectHQ/prefect/pull/18711)
* Update "Use integrations" to reflect reference `pyproject.toml` by [@alastairtree](https://github.com/alastairtree) in [#18689](https://github.com/PrefectHQ/prefect/pull/18689)
* Add note on necessary GitHub PAT permissions by [@rcash](https://github.com/rcash) in [#18696](https://github.com/PrefectHQ/prefect/pull/18696)
* Add devlog to community resources in README by [@zzstoatzz](https://github.com/zzstoatzz) in [#18698](https://github.com/PrefectHQ/prefect/pull/18698)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.12...3.4.13](https://github.com/PrefectHQ/prefect/compare/3.4.12...3.4.13)

***

## 3.4.12 - 20k magic in the air

*Released on August 08, 2025*

**Bug Fixes 🐞**

* Check future is if cancelled. by [@is](https://github.com/is) in [#18628](https://github.com/PrefectHQ/prefect/pull/18628)
* Add in-memory causal ordering for task run recorder by [@desertaxle](https://github.com/desertaxle) in [#18634](https://github.com/PrefectHQ/prefect/pull/18634)
* Add note on run\_shell\_script by [@rcash](https://github.com/rcash) in [#18658](https://github.com/PrefectHQ/prefect/pull/18658)
* Note about `to_deployment` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18647](https://github.com/PrefectHQ/prefect/pull/18647)
* Fix event emission when blocks are loaded server-side by [@desertaxle](https://github.com/desertaxle) in [#18679](https://github.com/PrefectHQ/prefect/pull/18679)

**Development & Tidiness 🧹**

* chore(deps): bump ruff from 0.9.6 to 0.12.7 by [@dependabot](https://github.com/dependabot)\[bot] in [#18622](https://github.com/PrefectHQ/prefect/pull/18622)
* chore(deps): bump actions/download-artifact from 4 to 5 by [@dependabot](https://github.com/dependabot)\[bot] in [#18650](https://github.com/PrefectHQ/prefect/pull/18650)
* chore(deps): bump ruff from 0.12.7 to 0.12.8 by [@dependabot](https://github.com/dependabot)\[bot] in [#18673](https://github.com/PrefectHQ/prefect/pull/18673)
* chore(deps): bump uv from 0.5.7 to 0.8.6 in /scripts/proxy-test by [@dependabot](https://github.com/dependabot)\[bot] in [#18672](https://github.com/PrefectHQ/prefect/pull/18672)

**Documentation 📓**

* Port examples hosting from PrefectHQ/examples by [@desertaxle](https://github.com/desertaxle) in [#18661](https://github.com/PrefectHQ/prefect/pull/18661)
* Add Python SDK to variables-docs by [@oakhill87](https://github.com/oakhill87) in [#18626](https://github.com/PrefectHQ/prefect/pull/18626)
* Make mention of Azure Event Grid support by [@bdalpe](https://github.com/bdalpe) in [#18631](https://github.com/PrefectHQ/prefect/pull/18631)
* Fix link for ThreadPoolTaskRunner in Task Runners doc by [@bdalpe](https://github.com/bdalpe) in [#18663](https://github.com/PrefectHQ/prefect/pull/18663)
* Bold the stray h2 by [@zzstoatzz](https://github.com/zzstoatzz) in [#18669](https://github.com/PrefectHQ/prefect/pull/18669)
* Add CTA for contributing examples by [@desertaxle](https://github.com/desertaxle) in [#18671](https://github.com/PrefectHQ/prefect/pull/18671)
* Add setting to customize which causal ordering implementation to use by [@desertaxle](https://github.com/desertaxle) in [#18675](https://github.com/PrefectHQ/prefect/pull/18675)
* Don't use deprecated settings access in example by [@zzstoatzz](https://github.com/zzstoatzz) in [#18676](https://github.com/PrefectHQ/prefect/pull/18676)
* Update rate limit and metadata retention docs by [@desertaxle](https://github.com/desertaxle) in [#18674](https://github.com/PrefectHQ/prefect/pull/18674)
* docs: add health check configuration for .serve() deployments by [@zzstoatzz](https://github.com/zzstoatzz) in [#18677](https://github.com/PrefectHQ/prefect/pull/18677)
* Add blurb for Redis auth by [@bdalpe](https://github.com/bdalpe) in [#18682](https://github.com/PrefectHQ/prefect/pull/18682)
* Fix the upgrade guide URL by [@Janiczek](https://github.com/Janiczek) in [#18641](https://github.com/PrefectHQ/prefect/pull/18641)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.11...3.4.12](https://github.com/PrefectHQ/prefect/compare/3.4.11...3.4.12)

***

## 3.4.11 - Heads up, the repo man is coming for your deployment concurrency slot

*Released on July 31, 2025*

**Enhancements ➕➕**

* Update deployment concurrency limits to use leasing by [@desertaxle](https://github.com/desertaxle) in [#18567](https://github.com/PrefectHQ/prefect/pull/18567)
* Update ad hoc installations to use `uv` if available by [@desertaxle](https://github.com/desertaxle) in [#18618](https://github.com/PrefectHQ/prefect/pull/18618)

**Bug Fixes 🐞**

* Allow automations to notify when the triggers service is disabled by [@fatih-acar](https://github.com/fatih-acar) in [#18577](https://github.com/PrefectHQ/prefect/pull/18577)
* Truncate oversized log messages to prevent ValueError and improve flow debuggability by [@nrnavaneet](https://github.com/nrnavaneet) in [#18550](https://github.com/PrefectHQ/prefect/pull/18550)
* Fix async locking error by generating a unique holder for each transaction by [@desertaxle](https://github.com/desertaxle) in [#18607](https://github.com/PrefectHQ/prefect/pull/18607)

**Integrations & Dependencies 🤝**

**`prefect-azure`**

* Add `PREFECT_API_AUTH_STRING` to secure environment variables for ACI worker by [@desertaxle](https://github.com/desertaxle) in [#18624](https://github.com/PrefectHQ/prefect/pull/18624)

**`prefect-aws`**

* Add support for providing `PREFECT_API_AUTH_STRING` as a secret to ECS tasks by [@desertaxle](https://github.com/desertaxle) in [#18620](https://github.com/PrefectHQ/prefect/pull/18620)

**`prefect-dbt`**

* Handle dbt source types and source manifest references by [@kevingrismore](https://github.com/kevingrismore) in [#18570](https://github.com/PrefectHQ/prefect/pull/18570)
* Omit compiled dbt code when it exceeds max asset description length by [@kevingrismore](https://github.com/kevingrismore) in [#18572](https://github.com/PrefectHQ/prefect/pull/18572)
* Bump minimum `prefect` version for `prefect-dbt` by [@desertaxle](https://github.com/desertaxle) in [#18623](https://github.com/PrefectHQ/prefect/pull/18623)

**`prefect-gcp`**

* Add GCP secret support to `CloudRunV2Worker` for Prefect API key/auth string by [@desertaxle](https://github.com/desertaxle) in [#18594](https://github.com/PrefectHQ/prefect/pull/18594)
* Add GCP secret support to `CloudRunWorker` for Prefect API credentials by [@desertaxle](https://github.com/desertaxle) in [#18608](https://github.com/PrefectHQ/prefect/pull/18608)
* Improve performance of uploads to GCP bucket by [@zzstoatzz](https://github.com/zzstoatzz) in [#18571](https://github.com/PrefectHQ/prefect/pull/18571)

**`prefect-kubernetes`**

* Allow specifying the key for an existing Kubernetes worker API auth string secret by [@mitchnielsen](https://github.com/mitchnielsen) in [#18578](https://github.com/PrefectHQ/prefect/pull/18578)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-ui-library to version 3.13.2 by [@marvin-robot](https://github.com/marvin-robot) in [#18597](https://github.com/PrefectHQ/prefect/pull/18597)

**Documentation 📓**

* Update API Reference for new `mdxify` version by [@zzstoatzz](https://github.com/zzstoatzz) in [#18568](https://github.com/PrefectHQ/prefect/pull/18568)
* Add `--include-inheritance` to SDK reference docs builds by [@kevingrismore](https://github.com/kevingrismore) in [#18529](https://github.com/PrefectHQ/prefect/pull/18529)
* Add more states to docs by [@rcash](https://github.com/rcash) in [#18573](https://github.com/PrefectHQ/prefect/pull/18573)
* Fix docstrings and regenerate SDK docs by [@kevingrismore](https://github.com/kevingrismore) in [#18579](https://github.com/PrefectHQ/prefect/pull/18579)
* Fix example rendering in CLI ref by [@zzstoatzz](https://github.com/zzstoatzz) in [#18580](https://github.com/PrefectHQ/prefect/pull/18580)
* Update concurrency limit examples by [@kevingrismore](https://github.com/kevingrismore) in [#18604](https://github.com/PrefectHQ/prefect/pull/18604)
* Add detail and options to the GitHub Quickstart by [@kevingrismore](https://github.com/kevingrismore) in [#18621](https://github.com/PrefectHQ/prefect/pull/18621)
* Fix broken links in docs by [@bdalpe](https://github.com/bdalpe) in [#18609](https://github.com/PrefectHQ/prefect/pull/18609)
* Fix styling of certain code blocks and links in docs by [@markupboy](https://github.com/markupboy) in [#18625](https://github.com/PrefectHQ/prefect/pull/18625)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.10...3.4.11](https://github.com/PrefectHQ/prefect/compare/3.4.10...3.4.11)

***

## 3.4.10 - Lease and thank you

*Released on July 22, 2025*

**Enhancements ➕➕**

* Update async `concurrency` context manager to use leases by [@desertaxle](https://github.com/desertaxle) in [#18522](https://github.com/PrefectHQ/prefect/pull/18522)
* Update sync `concurrency` context manager to use leases by [@desertaxle](https://github.com/desertaxle) in [#18535](https://github.com/PrefectHQ/prefect/pull/18535)
* Track concurrency limit lease creation time and use it to calculate occupancy seconds by [@desertaxle](https://github.com/desertaxle) in [#18551](https://github.com/PrefectHQ/prefect/pull/18551)

**Integrations & Dependencies 🤝**

* Update @prefecthq/prefect-ui-library to version 3.13.1 by [@marvin-robot](https://github.com/marvin-robot) in [#18563](https://github.com/PrefectHQ/prefect/pull/18563)
* Bump form-data from 4.0.0 to 4.0.4 in /ui by [@dependabot](https://github.com/dependabot)\[bot] in [#18561](https://github.com/PrefectHQ/prefect/pull/18561)

**Documentation 📓**

* Add note about `PREFECT_API_KEY` in ecs guide by [@zzstoatzz](https://github.com/zzstoatzz) in [#18547](https://github.com/PrefectHQ/prefect/pull/18547)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.9...3.4.10](https://github.com/PrefectHQ/prefect/compare/3.4.9...3.4.10)

***

## 3.4.9 - It's the Lease We Can Do

*Released on July 17, 2025*

**Enhancements ➕➕**

* Add in-memory concurrency lease storage by [@desertaxle](https://github.com/desertaxle) in [#18481](https://github.com/PrefectHQ/prefect/pull/18481)
* Add repossessor service by [@desertaxle](https://github.com/desertaxle) in [#18492](https://github.com/PrefectHQ/prefect/pull/18492)
* Document an official Docker Compose setup by [@Toshaksha](https://github.com/Toshaksha) in [#18509](https://github.com/PrefectHQ/prefect/pull/18509)
* Delete logs when deleting a flow or task run by [@johnnyg](https://github.com/johnnyg) in [#18517](https://github.com/PrefectHQ/prefect/pull/18517)
* Allow infrastructure bound flows to be dispatched to existing workers by [@desertaxle](https://github.com/desertaxle) in [#18472](https://github.com/PrefectHQ/prefect/pull/18472)
* Add endpoint for acquiring concurrency slots with a lease by [@desertaxle](https://github.com/desertaxle) in [#18512](https://github.com/PrefectHQ/prefect/pull/18512)
* Add concurrency lease renewal endpoint by [@desertaxle](https://github.com/desertaxle) in [#18513](https://github.com/PrefectHQ/prefect/pull/18513)
* Add endpoint to decrement concurrency limits with a lease by [@desertaxle](https://github.com/desertaxle) in [#18515](https://github.com/PrefectHQ/prefect/pull/18515)
* Support templated --flow-run-name values in prefect deployment run by [@nrnavaneet](https://github.com/nrnavaneet) in [#18511](https://github.com/PrefectHQ/prefect/pull/18511)

**Bug Fixes 🐞**

* Fix Block secret serialization for fields with Union type by [@desertaxle](https://github.com/desertaxle) in [#18491](https://github.com/PrefectHQ/prefect/pull/18491)
* Remove restricted characters from dbt asset keys by [@kevingrismore](https://github.com/kevingrismore) in [#18484](https://github.com/PrefectHQ/prefect/pull/18484)
* Fix MinIOCredentials documentation to use correct boto3 parameter name by [@zzstoatzz](https://github.com/zzstoatzz) in [#18493](https://github.com/PrefectHQ/prefect/pull/18493)
* Add labels to scheduled runs by [@cicdw](https://github.com/cicdw) in [#18524](https://github.com/PrefectHQ/prefect/pull/18524)
* Raise `pydantic` lower pin to 2.10.1 by [@desertaxle](https://github.com/desertaxle) in [#18533](https://github.com/PrefectHQ/prefect/pull/18533)
* ✨ fix(server): update Prefect server docs URL in startup message by [@l-lumin](https://github.com/l-lumin) in [#18539](https://github.com/PrefectHQ/prefect/pull/18539)

**Development & Tidiness 🧹**

* Add `no-commit-to-branch` hook to prevent accidental commits to main by [@desertaxle](https://github.com/desertaxle) in [#18504](https://github.com/PrefectHQ/prefect/pull/18504)
* Update @prefecthq/prefect-ui-library to version 3.13.0 by [@marvin-robot](https://github.com/marvin-robot) in [#18527](https://github.com/PrefectHQ/prefect/pull/18527)
* Update dbt integration codeowners by [@kevingrismore](https://github.com/kevingrismore) in [#18483](https://github.com/PrefectHQ/prefect/pull/18483)
* skip no-commit-to-branch check on merge to main by [@zzstoatzz](https://github.com/zzstoatzz) in [#18505](https://github.com/PrefectHQ/prefect/pull/18505)
* Enforce max asset description length by [@jakekaplan](https://github.com/jakekaplan) in [#18541](https://github.com/PrefectHQ/prefect/pull/18541)

**Documentation 📓**

* Revert "Add --flow-run-name option to deployment run CLI with templating support" by [@zzstoatzz](https://github.com/zzstoatzz) in [#18503](https://github.com/PrefectHQ/prefect/pull/18503)
* Added support for setting flow run name in deployment CLI by [@nrnavaneet](https://github.com/nrnavaneet) in [#18506](https://github.com/PrefectHQ/prefect/pull/18506)
* Reintroduce the "Develop a custom worker" guide by [@desertaxle](https://github.com/desertaxle) in [#18516](https://github.com/PrefectHQ/prefect/pull/18516)
* expose new doc file in nav by [@zzstoatzz](https://github.com/zzstoatzz) in [#18520](https://github.com/PrefectHQ/prefect/pull/18520)
* a couple more edits to docker compose doc by [@zzstoatzz](https://github.com/zzstoatzz) in [#18521](https://github.com/PrefectHQ/prefect/pull/18521)
* Chore: update docs logo link from prefect.io => docs.prefect.io by [@znicholasbrown](https://github.com/znicholasbrown) in [#18525](https://github.com/PrefectHQ/prefect/pull/18525)
* add section on running work to completion by [@zzstoatzz](https://github.com/zzstoatzz) in [#18537](https://github.com/PrefectHQ/prefect/pull/18537)
* add db maintenance guide by [@zzstoatzz](https://github.com/zzstoatzz) in [#18526](https://github.com/PrefectHQ/prefect/pull/18526)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.8...3.4.9](https://github.com/PrefectHQ/prefect/compare/3.4.8...3.4.9)

***

## 3.4.8 - Objects in Mirror Are JSONer Than They Appear

*Released on July 10, 2025*

**Enhancements ➕➕**

* Add section on dynamic asset materialization by [@cicdw](https://github.com/cicdw) in [#18383](https://github.com/PrefectHQ/prefect/pull/18383)
* Add --output and -o flags to all inspect commands, supporting 'json' by [@cicdw](https://github.com/cicdw) in [#18390](https://github.com/PrefectHQ/prefect/pull/18390)
* add `prefect automation create` command by [@zzstoatzz](https://github.com/zzstoatzz) in [#18452](https://github.com/PrefectHQ/prefect/pull/18452)
* Add setting for configuring custom headers by [@cicdw](https://github.com/cicdw) in [#18444](https://github.com/PrefectHQ/prefect/pull/18444)

**Bug Fixes 🐞**

* Fix UI URL generation for FlowRunResponse in Slack automations by [@zzstoatzz](https://github.com/zzstoatzz) in [#18407](https://github.com/PrefectHQ/prefect/pull/18407)
* Fix broken Google-indexed documentation URLs with redirects by [@zzstoatzz](https://github.com/zzstoatzz) in [#18409](https://github.com/PrefectHQ/prefect/pull/18409)
* Fix worker crash when flow file is missing during hook execution by [@zzstoatzz](https://github.com/zzstoatzz) in [#18424](https://github.com/PrefectHQ/prefect/pull/18424)
* clear `pull_steps` when no storage on deployment by [@zzstoatzz](https://github.com/zzstoatzz) in [#18446](https://github.com/PrefectHQ/prefect/pull/18446)
* Account for null pull steps in CLI by [@cicdw](https://github.com/cicdw) in [#18454](https://github.com/PrefectHQ/prefect/pull/18454)
* Use UUID path converter in all places by [@cicdw](https://github.com/cicdw) in [#18455](https://github.com/PrefectHQ/prefect/pull/18455)
* Fix visit\_collection to properly handle shared references by [@zzstoatzz](https://github.com/zzstoatzz) in [#18434](https://github.com/PrefectHQ/prefect/pull/18434)

**Integrations & Dependencies 🤝**

* fail loudly if we can't connect to custom dask cluster by [@zzstoatzz](https://github.com/zzstoatzz) in [#18432](https://github.com/PrefectHQ/prefect/pull/18432)
* Snowflake: Handle pool and service timeouts in SPCS worker by [@bjorhn](https://github.com/bjorhn) in [#18403](https://github.com/PrefectHQ/prefect/pull/18403)
* Fix dbt logging behavior, improve context handling by [@kevingrismore](https://github.com/kevingrismore) in [#18377](https://github.com/PrefectHQ/prefect/pull/18377)
* Resolve dbt profiles and other improvements by [@kevingrismore](https://github.com/kevingrismore) in [#18410](https://github.com/PrefectHQ/prefect/pull/18410)
* Allow Prefect API key to be provided to an ECS tasks via an AWS secret by [@desertaxle](https://github.com/desertaxle) in [#18474](https://github.com/PrefectHQ/prefect/pull/18474)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-design to version 2.15.2 by [@marvin-robot](https://github.com/marvin-robot) in [#18387](https://github.com/PrefectHQ/prefect/pull/18387)
* Update @prefecthq/prefect-design to version 2.15.3 by [@marvin-robot](https://github.com/marvin-robot) in [#18418](https://github.com/PrefectHQ/prefect/pull/18418)
* Update @prefecthq/prefect-design to version 2.15.4 by [@marvin-robot](https://github.com/marvin-robot) in [#18419](https://github.com/PrefectHQ/prefect/pull/18419)
* Update @prefecthq/prefect-ui-library to version 3.12.17 by [@marvin-robot](https://github.com/marvin-robot) in [#18426](https://github.com/PrefectHQ/prefect/pull/18426)
* Migrate integration tests from custom test runner to pytest by [@desertaxle](https://github.com/desertaxle) in [#18450](https://github.com/PrefectHQ/prefect/pull/18450)
* Deflake schedule statefulness test by [@desertaxle](https://github.com/desertaxle) in [#18468](https://github.com/PrefectHQ/prefect/pull/18468)
* Improve reliability of integration tests by [@desertaxle](https://github.com/desertaxle) in [#18469](https://github.com/PrefectHQ/prefect/pull/18469)
* Update test to connect to websocket with custom headers by [@desertaxle](https://github.com/desertaxle) in [#18479](https://github.com/PrefectHQ/prefect/pull/18479)
* update pins on core by [@zzstoatzz](https://github.com/zzstoatzz) in [#18382](https://github.com/PrefectHQ/prefect/pull/18382)

**Documentation 📓**

* Docs for `dbt-core==0.7.1` by [@kevingrismore](https://github.com/kevingrismore) in [#18380](https://github.com/PrefectHQ/prefect/pull/18380)
* begin "dependent settings" refactor by [@zzstoatzz](https://github.com/zzstoatzz) in [#18029](https://github.com/PrefectHQ/prefect/pull/18029)
* Fix api ref and open source links in new tab by [@zzstoatzz](https://github.com/zzstoatzz) in [#18385](https://github.com/PrefectHQ/prefect/pull/18385)
* Adds Worker healthcheck advanced guide by [@cicdw](https://github.com/cicdw) in [#18384](https://github.com/PrefectHQ/prefect/pull/18384)
* Add section of examples on schedule CLI by [@cicdw](https://github.com/cicdw) in [#18386](https://github.com/PrefectHQ/prefect/pull/18386)
* Add how to guide for running prefect server on windows by [@cicdw](https://github.com/cicdw) in [#18388](https://github.com/PrefectHQ/prefect/pull/18388)
* Update Event trigger docs for match\_related by [@bdalpe](https://github.com/bdalpe) in [#18405](https://github.com/PrefectHQ/prefect/pull/18405)
* Reformat all examples in docstrings by [@cicdw](https://github.com/cicdw) in [#18389](https://github.com/PrefectHQ/prefect/pull/18389)
* Run api-ref generation to incorporate new examples syntax by [@cicdw](https://github.com/cicdw) in [#18406](https://github.com/PrefectHQ/prefect/pull/18406)
* Update Slack footer link by [@bdalpe](https://github.com/bdalpe) in [#18421](https://github.com/PrefectHQ/prefect/pull/18421)
* add note about events in server metadata page by [@zzstoatzz](https://github.com/zzstoatzz) in [#18459](https://github.com/PrefectHQ/prefect/pull/18459)
* fix order of concept items by [@zzstoatzz](https://github.com/zzstoatzz) in [#18460](https://github.com/PrefectHQ/prefect/pull/18460)
* add How To Run Deployments doc by [@zzstoatzz](https://github.com/zzstoatzz) in [#18464](https://github.com/PrefectHQ/prefect/pull/18464)
* New quickstart by [@kevingrismore](https://github.com/kevingrismore) in [#18473](https://github.com/PrefectHQ/prefect/pull/18473)

**Uncategorized**

* chore(deps): bump vue from 3.5.16 to 3.5.17 in /ui by [@dependabot](https://github.com/dependabot)\[bot] in [#18345](https://github.com/PrefectHQ/prefect/pull/18345)
* Update CODEOWNERS by [@cicdw](https://github.com/cicdw) in [#18391](https://github.com/PrefectHQ/prefect/pull/18391)
* Update cloud block urls for CLI by [@kevingrismore](https://github.com/kevingrismore) in [#18423](https://github.com/PrefectHQ/prefect/pull/18423)
* Enhance BitBucket Credentials Block: Support Special Characters in Username and Escape Git URL Credentials by [@nrnavaneet](https://github.com/nrnavaneet) in [#18447](https://github.com/PrefectHQ/prefect/pull/18447)
* Fix errors in ECS worker related to ad hoc submission by [@desertaxle](https://github.com/desertaxle) in [#18438](https://github.com/PrefectHQ/prefect/pull/18438)
* remove ujson from deps by [@zzstoatzz](https://github.com/zzstoatzz) in [#18448](https://github.com/PrefectHQ/prefect/pull/18448)
* Migrate LocalFileSystem from sync\_compatible to async\_dispatch by [@zzstoatzz](https://github.com/zzstoatzz) in [#18413](https://github.com/PrefectHQ/prefect/pull/18413)
* use correct key name for basic auth local storage by [@zzstoatzz](https://github.com/zzstoatzz) in [#18457](https://github.com/PrefectHQ/prefect/pull/18457)
* Fix failing unit tests by [@desertaxle](https://github.com/desertaxle) in [#18463](https://github.com/PrefectHQ/prefect/pull/18463)
* Include run count in state change events by [@kevingrismore](https://github.com/kevingrismore) in [#18466](https://github.com/PrefectHQ/prefect/pull/18466)
* Update `RetryFailedFlows` orchestration policy to clear retry type on exhausted retries by [@desertaxle](https://github.com/desertaxle) in [#18462](https://github.com/PrefectHQ/prefect/pull/18462)
* Remove dependency on `dbt_project.yml` by [@kevingrismore](https://github.com/kevingrismore) in [#18465](https://github.com/PrefectHQ/prefect/pull/18465)
* Rename extra\_headers to additional\_headers by [@vyagubov](https://github.com/vyagubov) in [#18478](https://github.com/PrefectHQ/prefect/pull/18478)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.7...3.4.8](https://github.com/PrefectHQ/prefect/compare/3.4.7...3.4.8)

***

## 3.4.7 - Stream a Little Stream of Logs

*Released on June 26, 2025*

**Enhancements ➕➕**

* Add `not_any_` filter for `DeploymentFilterId` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18344](https://github.com/PrefectHQ/prefect/pull/18344)
* Snowflake: Fixed error message when retrieving SPCS container status by [@bjorhn](https://github.com/bjorhn) in [#18358](https://github.com/PrefectHQ/prefect/pull/18358)
* Add --web flag to inspect runs from the command line by [@zzstoatzz](https://github.com/zzstoatzz) in [#18370](https://github.com/PrefectHQ/prefect/pull/18370)
* Add tags support to Automation objects by [@chrisguidry](https://github.com/chrisguidry) in [#18286](https://github.com/PrefectHQ/prefect/pull/18286)
* Add tag filtering support for automations by [@chrisguidry](https://github.com/chrisguidry) in [#18288](https://github.com/PrefectHQ/prefect/pull/18288)
* serialization performance improvements by [@zzstoatzz](https://github.com/zzstoatzz) in [#18314](https://github.com/PrefectHQ/prefect/pull/18314)
* Add client-side logs subscriber module by [@chrisguidry](https://github.com/chrisguidry) in [#18318](https://github.com/PrefectHQ/prefect/pull/18318)
* Add `pause_deployment` and `resume_deployment` client methods by [@zzstoatzz](https://github.com/zzstoatzz) in [#18336](https://github.com/PrefectHQ/prefect/pull/18336)
* Track subflow results along with task results by [@jakekaplan](https://github.com/jakekaplan) in [#18338](https://github.com/PrefectHQ/prefect/pull/18338)
* Add an axios middleware for intercepting errors  by [@znicholasbrown](https://github.com/znicholasbrown) in [#18365](https://github.com/PrefectHQ/prefect/pull/18365)
* Materialize Prefect assets with dbt core by [@kevingrismore](https://github.com/kevingrismore) in [#18350](https://github.com/PrefectHQ/prefect/pull/18350)

**Bug Fixes 🐞**

* fix `TimeoutError` in `result_async` when accessing results from `delay` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18280](https://github.com/PrefectHQ/prefect/pull/18280)
* Fix for issue 18239 by [@TWeatherston](https://github.com/TWeatherston) in [#18284](https://github.com/PrefectHQ/prefect/pull/18284)
* \[prefect-aws] order env vars for task def equality by [@zzstoatzz](https://github.com/zzstoatzz) in [#18309](https://github.com/PrefectHQ/prefect/pull/18309)
* Fix serialization edge case in Prefect blocks by [@zzstoatzz](https://github.com/zzstoatzz) in [#18363](https://github.com/PrefectHQ/prefect/pull/18363)
* Fix asyncio loop issue when deploying with proxy by [@zzstoatzz](https://github.com/zzstoatzz) in [#18374](https://github.com/PrefectHQ/prefect/pull/18374)
* support `assets` for `with_options` by [@jesse-c](https://github.com/jesse-c) in [#18353](https://github.com/PrefectHQ/prefect/pull/18353)
* Fix subprocess cleanup in prefect\_test\_harness to prevent ResourceWarning by [@zzstoatzz](https://github.com/zzstoatzz) in [#18376](https://github.com/PrefectHQ/prefect/pull/18376)
* Fix throwing no key exception by [@emmanuel-ferdman](https://github.com/emmanuel-ferdman) in [#18281](https://github.com/PrefectHQ/prefect/pull/18281)
* Drop task\_run.state\_id foreign key to prevent deadlocks by [@zzstoatzz](https://github.com/zzstoatzz) in [#18302](https://github.com/PrefectHQ/prefect/pull/18302)

**Development & Tidiness 🧹**

* bump lockfile and run pre-push hooks by [@zzstoatzz](https://github.com/zzstoatzz) in [#18308](https://github.com/PrefectHQ/prefect/pull/18308)
* remove `fetch` kwarg from docstring and overloads by [@zzstoatzz](https://github.com/zzstoatzz) in [#18311](https://github.com/PrefectHQ/prefect/pull/18311)
* fix 3.9 test for prefect-shell by [@zzstoatzz](https://github.com/zzstoatzz) in [#18014](https://github.com/PrefectHQ/prefect/pull/18014)
* run pre-push hooks by [@zzstoatzz](https://github.com/zzstoatzz) in [#18330](https://github.com/PrefectHQ/prefect/pull/18330)
* Update @prefecthq/prefect-ui-library to version 3.12.15 by [@marvin-robot](https://github.com/marvin-robot) in [#18348](https://github.com/PrefectHQ/prefect/pull/18348)
* add api ref for python sdk by [@zzstoatzz](https://github.com/zzstoatzz) in [#18334](https://github.com/PrefectHQ/prefect/pull/18334)
* Update @prefecthq/prefect-ui-library to version 3.12.16 by [@marvin-robot](https://github.com/marvin-robot) in [#18366](https://github.com/PrefectHQ/prefect/pull/18366)
* Update @prefecthq/prefect-design to version 2.15.1 by [@marvin-robot](https://github.com/marvin-robot) in [#18378](https://github.com/PrefectHQ/prefect/pull/18378)
* make warning debug by [@zzstoatzz](https://github.com/zzstoatzz) in [#18327](https://github.com/PrefectHQ/prefect/pull/18327)
* omit nested venv from docker builds by [@zzstoatzz](https://github.com/zzstoatzz) in [#18328](https://github.com/PrefectHQ/prefect/pull/18328)
* Enforce asset key characters + length by [@jakekaplan](https://github.com/jakekaplan) in [#18379](https://github.com/PrefectHQ/prefect/pull/18379)

**Documentation 📓**

* add docs on HA self-hosted setups by [@zzstoatzz](https://github.com/zzstoatzz) in [#18279](https://github.com/PrefectHQ/prefect/pull/18279)
* improve self-host guide name by [@zzstoatzz](https://github.com/zzstoatzz) in [#18289](https://github.com/PrefectHQ/prefect/pull/18289)
* Move security settings into their own doc by [@cicdw](https://github.com/cicdw) in [#18316](https://github.com/PrefectHQ/prefect/pull/18316)
* Add /api/logs/out websocket endpoint for live log streaming by [@chrisguidry](https://github.com/chrisguidry) in [#18315](https://github.com/PrefectHQ/prefect/pull/18315)
* Update contribution guide to require pre-push hooks by [@zzstoatzz](https://github.com/zzstoatzz) in [#18332](https://github.com/PrefectHQ/prefect/pull/18332)
* dont need separate command for pre-push by [@zzstoatzz](https://github.com/zzstoatzz) in [#18351](https://github.com/PrefectHQ/prefect/pull/18351)
* Update API refs to remove old style bracket links by [@cicdw](https://github.com/cicdw) in [#18355](https://github.com/PrefectHQ/prefect/pull/18355)
* Remove brackets from example by [@cicdw](https://github.com/cicdw) in [#18360](https://github.com/PrefectHQ/prefect/pull/18360)
* Remove more example brackets by [@cicdw](https://github.com/cicdw) in [#18361](https://github.com/PrefectHQ/prefect/pull/18361)
* add some api-ref examples and avoid right hand nav pollution by [@zzstoatzz](https://github.com/zzstoatzz) in [#18367](https://github.com/PrefectHQ/prefect/pull/18367)
* Add AGENTS.md documentation files by [@zzstoatzz](https://github.com/zzstoatzz) in [#18248](https://github.com/PrefectHQ/prefect/pull/18248)
* improve agent guidance and remove redundant info by [@zzstoatzz](https://github.com/zzstoatzz) in [#18321](https://github.com/PrefectHQ/prefect/pull/18321)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.6...3.4.7](https://github.com/PrefectHQ/prefect/compare/3.4.6...3.4.7)

***

## 3.4.6 - Per My Last NOTIFY

*Released on June 11, 2025*

📰 Check out [Prefect Assets](https://docs.prefect.io/v3/concepts/assets)!

**Bug Fixes 🐞**

* use pg notify/listen for multi-server automation synchronization by [@zzstoatzz](https://github.com/zzstoatzz) in [#18266](https://github.com/PrefectHQ/prefect/pull/18266)
* Remove versions of pydantic that produce thread safety issues by [@cicdw](https://github.com/cicdw) in [#18250](https://github.com/PrefectHQ/prefect/pull/18250)
* fix `config` validation for nested and constrained settings by [@zzstoatzz](https://github.com/zzstoatzz) in [#18260](https://github.com/PrefectHQ/prefect/pull/18260)
* add note about long migrations with big tables by [@zzstoatzz](https://github.com/zzstoatzz) in [#18268](https://github.com/PrefectHQ/prefect/pull/18268)
* Add automations prefix to validate route by [@cicdw](https://github.com/cicdw) in [#18277](https://github.com/PrefectHQ/prefect/pull/18277)
* Fix nested materialization behavior by [@jakekaplan](https://github.com/jakekaplan) in [#18265](https://github.com/PrefectHQ/prefect/pull/18265)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-design to version 2.15.0 by [@marvin-robot](https://github.com/marvin-robot) in [#18274](https://github.com/PrefectHQ/prefect/pull/18274)
* Add tests for UI variable duplication enhancement by [@vilhenad](https://github.com/vilhenad) in [#18245](https://github.com/PrefectHQ/prefect/pull/18245)
* Replaced deprecated logic in SPCS worker by [@bjorhn](https://github.com/bjorhn) in [#18105](https://github.com/PrefectHQ/prefect/pull/18105)

**Documentation 📓**

* remove reference to "pull work pools" by [@zzstoatzz](https://github.com/zzstoatzz) in [#18256](https://github.com/PrefectHQ/prefect/pull/18256)
* add note on `--no-prompt` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18261](https://github.com/PrefectHQ/prefect/pull/18261)
* Fix incorrect links to SDK by [@bdalpe](https://github.com/bdalpe) in [#18262](https://github.com/PrefectHQ/prefect/pull/18262)
* Remove v2 file from docs by [@cicdw](https://github.com/cicdw) in [#18267](https://github.com/PrefectHQ/prefect/pull/18267)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.5...3.4.6](https://github.com/PrefectHQ/prefect/compare/3.4.5...3.4.6)

***

## 3.4.5 - Assets Have Been Materialized Internally

*Released on June 07, 2025*

To learn more, [register for next week's webinar here](https://lu.ma/c2bbz5bg)!

**New Features 💅**

* Add `Asset` + `[@materialize](https://github.com/materialize)`ing tasks by [@jakekaplan](https://github.com/jakekaplan) in [#18230](https://github.com/PrefectHQ/prefect/pull/18230)
* Emit `asset.referenced` events on materialization only by [@jakekaplan](https://github.com/jakekaplan) in [#18252](https://github.com/PrefectHQ/prefect/pull/18252)
* Support emitting asset events for `DaskTaskRunner` by [@jakekaplan](https://github.com/jakekaplan) in [#18241](https://github.com/PrefectHQ/prefect/pull/18241)
* Support emitting asset events for `RayTaskRunner` by [@jakekaplan](https://github.com/jakekaplan) in [#18242](https://github.com/PrefectHQ/prefect/pull/18242)

**Bug Fixes 🐞**

* use kopf event for `occurred` in forwarded prefect events by [@zzstoatzz](https://github.com/zzstoatzz) in [#18226](https://github.com/PrefectHQ/prefect/pull/18226)
* Subclassing to set the max\_range per sandox environment (#18083) by [@steveh-101](https://github.com/steveh-101) in [#18232](https://github.com/PrefectHQ/prefect/pull/18232)
* Early return bucket path to avoid duplicated prefix in GCS bucket by [@zzstoatzz](https://github.com/zzstoatzz) in [#18237](https://github.com/PrefectHQ/prefect/pull/18237)
* Attempt retries  when task returns a failed state by [@bunchesofdonald](https://github.com/bunchesofdonald) in [#18240](https://github.com/PrefectHQ/prefect/pull/18240)
* log warning if volumes set via create kwargs by [@zzstoatzz](https://github.com/zzstoatzz) in [#18233](https://github.com/PrefectHQ/prefect/pull/18233)
* `prefect-redis`: fix min group id and deprecation warning by [@zzstoatzz](https://github.com/zzstoatzz) in [#18215](https://github.com/PrefectHQ/prefect/pull/18215)
* fix SendGrid behavior when modifying instance by [@zzstoatzz](https://github.com/zzstoatzz) in [#18219](https://github.com/PrefectHQ/prefect/pull/18219)
* fix async retry fn typing by [@zzstoatzz](https://github.com/zzstoatzz) in [#18247](https://github.com/PrefectHQ/prefect/pull/18247)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-design to version 2.14.26 by [@marvin-robot](https://github.com/marvin-robot) in [#18204](https://github.com/PrefectHQ/prefect/pull/18204)
* lower bound pin uv by [@zzstoatzz](https://github.com/zzstoatzz) in [#18216](https://github.com/PrefectHQ/prefect/pull/18216)
* Update @prefecthq/prefect-ui-library to version 3.12.14 by [@marvin-robot](https://github.com/marvin-robot) in [#18234](https://github.com/PrefectHQ/prefect/pull/18234)
* run `uv sync -U` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18251](https://github.com/PrefectHQ/prefect/pull/18251)
* fix test assertion by [@zzstoatzz](https://github.com/zzstoatzz) in [#18236](https://github.com/PrefectHQ/prefect/pull/18236)
* Adds missing increments for events client metrics by [@chrisguidry](https://github.com/chrisguidry) in [#18246](https://github.com/PrefectHQ/prefect/pull/18246)

**Documentation 📓**

* Docs refactor by [@cicdw](https://github.com/cicdw) in [#18208](https://github.com/PrefectHQ/prefect/pull/18208)
* fix dead links by [@zzstoatzz](https://github.com/zzstoatzz) in [#18243](https://github.com/PrefectHQ/prefect/pull/18243)
* fix dead link to zombie flow runs by [@zzstoatzz](https://github.com/zzstoatzz) in [#18244](https://github.com/PrefectHQ/prefect/pull/18244)
* fix link to downstream-upstream trigger with serve by [@zzstoatzz](https://github.com/zzstoatzz) in [#18249](https://github.com/PrefectHQ/prefect/pull/18249)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.4...3.4.5](https://github.com/PrefectHQ/prefect/compare/3.4.4...3.4.5)

***

## 3.4.4 - No Cache in the Banana Stand

*Released on May 29, 2025*

**Enhancements ✨**

* Setting to disable cache globally by [@zzstoatzz](https://github.com/zzstoatzz) in [#18195](https://github.com/PrefectHQ/prefect/pull/18195)
* Add redis publisher/consumer settings by [@zzstoatzz](https://github.com/zzstoatzz) in [#18160](https://github.com/PrefectHQ/prefect/pull/18160)

**Bug Fixes 🐞**

* Enables CSRF protection support on internal server requests by [@chrisguidry](https://github.com/chrisguidry) in [#18157](https://github.com/PrefectHQ/prefect/pull/18157)
* Corrects an infinite loop in the `CancellationCleanup` service by [@chrisguidry](https://github.com/chrisguidry) in [#18158](https://github.com/PrefectHQ/prefect/pull/18158)
* Handle `None` metadata in `prefect version` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18190](https://github.com/PrefectHQ/prefect/pull/18190)
* Merge duplicate `extra_hosts` kwarg by [@zzstoatzz](https://github.com/zzstoatzz) in [#18192](https://github.com/PrefectHQ/prefect/pull/18192)
* fix fractional value handling in retry delay policy by [@zzstoatzz](https://github.com/zzstoatzz) in [#18200](https://github.com/PrefectHQ/prefect/pull/18200)
* multi-server setup fixes pt1 by [@zzstoatzz](https://github.com/zzstoatzz) in [#18149](https://github.com/PrefectHQ/prefect/pull/18149)

**Development & Tidiness 🧹**

* Update @prefecthq/prefect-ui-library to version 3.12.13 by [@marvin-robot](https://github.com/marvin-robot) in [#18202](https://github.com/PrefectHQ/prefect/pull/18202)
* Bump some upper bounds by [@zzstoatzz](https://github.com/zzstoatzz) in [#18175](https://github.com/PrefectHQ/prefect/pull/18175)
* Remove reimplementation of `from_template_and_values` from ECS worker by [@kevingrismore](https://github.com/kevingrismore) in [#18201](https://github.com/PrefectHQ/prefect/pull/18201)
* chore(deps): bump vue from 3.5.13 to 3.5.14 in /ui by [@dependabot](https://github.com/dependabot) in [#18101](https://github.com/PrefectHQ/prefect/pull/18101)

**Documentation 📓**

* Add thread local context note by [@zzstoatzz](https://github.com/zzstoatzz) in [#18147](https://github.com/PrefectHQ/prefect/pull/18147)
* Add prefect managed compute usage to the docs by [@jakekaplan](https://github.com/jakekaplan) in [#18194](https://github.com/PrefectHQ/prefect/pull/18194)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.3...3.4.4](https://github.com/PrefectHQ/prefect/compare/3.4.3...3.4.4)

***

## 3.4.3 - You Return NotImplemented, I Return False. We Are Not The Same

*Released on May 22, 2025*

**Enhancements ➕➕**

* add settings to configure asyncpg mtls by [@29x10](https://github.com/29x10) in [#18097](https://github.com/PrefectHQ/prefect/pull/18097)

**Bug Fixes 🐞**

* fix `AttributeError` during equality check after args/kwargs deletion by [@zzstoatzz](https://github.com/zzstoatzz) in [#18110](https://github.com/PrefectHQ/prefect/pull/18110)
* handle list value envvar overrides for logging by [@levzem](https://github.com/levzem) in [#18062](https://github.com/PrefectHQ/prefect/pull/18062)

**Development & Tidiness 🧹**

* minor log cleanup by [@zzstoatzz](https://github.com/zzstoatzz) in [#18127](https://github.com/PrefectHQ/prefect/pull/18127)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.2...3.4.3](https://github.com/PrefectHQ/prefect/compare/3.4.2...3.4.3)

***

## 3.4.2 - Stay classy

*Released on May 19, 2025*

**Enhancements ➕➕**

* Support serving `[@classmethod](https://github.com/classmethod)` and `[@staticmethod](https://github.com/staticmethod)` flows by [@vyagubov](https://github.com/vyagubov) in [#18065](https://github.com/PrefectHQ/prefect/pull/18065)

**Bug Fixes 🐞**

* Make `RedisLockManager` picklable for Ray/Dask compatibility by [@zzstoatzz](https://github.com/zzstoatzz) in [#18018](https://github.com/PrefectHQ/prefect/pull/18018)
* Fix parsing for `PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18043](https://github.com/PrefectHQ/prefect/pull/18043)
* Add boolean flag execute\_commit for SELECT statements by [@DSauterIntersport](https://github.com/DSauterIntersport) in [#18095](https://github.com/PrefectHQ/prefect/pull/18095)
* Fix bug where the runner would try to cancel a flow run that was not running by [@desertaxle](https://github.com/desertaxle) in [#18108](https://github.com/PrefectHQ/prefect/pull/18108)
* Update call method to handle string payloads by [@qabilityp](https://github.com/qabilityp) in [#18058](https://github.com/PrefectHQ/prefect/pull/18058)

**Integrations & Dependencies 🤝**

* Update `jsonschema` lower bound to 4.18+ by [@zzstoatzz](https://github.com/zzstoatzz) in [#18036](https://github.com/PrefectHQ/prefect/pull/18036)
* Vendor `uuid7` implementation by [@desertaxle](https://github.com/desertaxle) in [#18046](https://github.com/PrefectHQ/prefect/pull/18046)

**`prefect-kubernetes`**

* Disable `kopf` scanning for `prefect-kubernetes` observer by [@desertaxle](https://github.com/desertaxle) in [#18013](https://github.com/PrefectHQ/prefect/pull/18013)

**`prefect-docker`**

* Add option to persist auto-generated Dockerfile by [@AliLordLoss](https://github.com/AliLordLoss) in [#17866](https://github.com/PrefectHQ/prefect/pull/17866)

**`prefect-shell`**

* Improve typing in `prefect-shell` by [@zzstoatzz](https://github.com/zzstoatzz) in [#18002](https://github.com/PrefectHQ/prefect/pull/18002)

**Development & Tidiness 🧹**

* Move generation hooks to pre-push by [@desertaxle](https://github.com/desertaxle) in [#18010](https://github.com/PrefectHQ/prefect/pull/18010)
* Task worker hygiene by [@zzstoatzz](https://github.com/zzstoatzz) in [#18016](https://github.com/PrefectHQ/prefect/pull/18016)
* Fix readme link by [@zzstoatzz](https://github.com/zzstoatzz) in [#17999](https://github.com/PrefectHQ/prefect/pull/17999)
* Run `prefect-client` smoke tests against local server by [@desertaxle](https://github.com/desertaxle) in [#18067](https://github.com/PrefectHQ/prefect/pull/18067)
* Fix error in setup for client compatibility tests by [@desertaxle](https://github.com/desertaxle) in [#18100](https://github.com/PrefectHQ/prefect/pull/18100)

**Documentation 📓**

* Adds Google site verification tag to our docs by [@cicdw](https://github.com/cicdw) in [#18031](https://github.com/PrefectHQ/prefect/pull/18031)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.1...3.4.2](https://github.com/PrefectHQ/prefect/compare/3.4.1...3.4.2)

***

## 3.4.1 - Zen and the Art of Kubernetes Job Submission

*Released on May 08, 2025*

This release also ships with version 0.6.0 of prefect-kubernetes, featuring a revamped Kubernetes worker. The updated worker is more stateless, providing improved resiliency, enhanced event emission, and better crash detection capabilities. See [#18004](\[#18004]\(https://github.com/PrefectHQ/prefect/pull/18004\)) for more details.

**Enhancements ➕➕**

* Support staticmethod and classmethod flow entrypoints by [@vyagubov](https://github.com/vyagubov) in [#17976](https://github.com/PrefectHQ/prefect/pull/17976)
* Adds support for `AND`ed related resources in queries and triggers by [@chrisguidry](https://github.com/chrisguidry) in [#18003](https://github.com/PrefectHQ/prefect/pull/18003)
* Refactor `Runner` to receive cancellation signals via websocket by [@desertaxle](https://github.com/desertaxle) in [#17973](https://github.com/PrefectHQ/prefect/pull/17973)
* Parse docker image strings with digests by [@kevingrismore](https://github.com/kevingrismore) in [#17987](https://github.com/PrefectHQ/prefect/pull/17987)
* Add DB index for automation event followers by [@zzstoatzz](https://github.com/zzstoatzz) in [#17981](https://github.com/PrefectHQ/prefect/pull/17981)
* Update variable name validator to allow hyphens by [@znicholasbrown](https://github.com/znicholasbrown) in [#17995](https://github.com/PrefectHQ/prefect/pull/17995)
* Allow `flow.submit` to be non-blocking for some infrastructure types by [@desertaxle](https://github.com/desertaxle) in [#17992](https://github.com/PrefectHQ/prefect/pull/17992)
* Uses UUIDv7 for the IDs of time-oriented objects by [@chrisguidry](https://github.com/chrisguidry) in [#18008](https://github.com/PrefectHQ/prefect/pull/18008)

**Bug Fixes 🐞**

* Use correct secret in task worker websocket subscription by [@zzstoatzz](https://github.com/zzstoatzz) in [#17975](https://github.com/PrefectHQ/prefect/pull/17975)
* Update `Runner` to use a long-lived `EventsClient` by [@desertaxle](https://github.com/desertaxle) in [#17986](https://github.com/PrefectHQ/prefect/pull/17986)
* Catch `FileNotFoundError` in `find_uv_bin` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17993](https://github.com/PrefectHQ/prefect/pull/17993)
* Coalesce flow run start times with expected start times by [@znicholasbrown](https://github.com/znicholasbrown) in [#17997](https://github.com/PrefectHQ/prefect/pull/17997)
* Fix generated work pool storage config for GCS by [@desertaxle](https://github.com/desertaxle) in [#18000](https://github.com/PrefectHQ/prefect/pull/18000)
* Fix run scatterplot pagination by [@znicholasbrown](https://github.com/znicholasbrown) in [#18009](https://github.com/PrefectHQ/prefect/pull/18009)

**Integrations & Dependencies 🤝**

* Refactor Kubernetes worker to reduce statefulness by [@desertaxle](https://github.com/desertaxle) in [#18004](https://github.com/PrefectHQ/prefect/pull/18004)
* Fix regex for Snowflake private keys by [@zzstoatzz](https://github.com/zzstoatzz) in [#17985](https://github.com/PrefectHQ/prefect/pull/17985)
* Bump vue-tsc from 2.2.8 to 2.2.10 in /ui by [@dependabot](https://github.com/dependabot) in [#17923](https://github.com/PrefectHQ/prefect/pull/17923)

**Development & Tidiness 🧹**

* Add test covering `.with_options` when used with a `classmethod` flow by [@vilhenad](https://github.com/vilhenad) in [#17647](https://github.com/PrefectHQ/prefect/pull/17647)
* Consolidate validation on self-validating types by [@zzstoatzz](https://github.com/zzstoatzz) in [#17994](https://github.com/PrefectHQ/prefect/pull/17994)

**Documentation 📓**

* Add parameter form documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#17972](https://github.com/PrefectHQ/prefect/pull/17972)
* Add deployment versioning documentation by [@kevingrismore](https://github.com/kevingrismore) in [#17974](https://github.com/PrefectHQ/prefect/pull/17974)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.4.0...3.4.1](https://github.com/PrefectHQ/prefect/compare/3.4.0...3.4.1)

***

## 3.4.0 - Pour one out for the flow run notification service

*Released on May 02, 2025*

This release removes the deprecated flow run notifications feature. Existing notification policies will be automatically migrated to automations when the server starts after upgrading. Notifications will continue to work as expected—no user action is required.

**Enhancements ➕➕**

* Allow providing a commit sha to the `git_clone` pull step by [@kevingrismore](https://github.com/kevingrismore) in [#17933](https://github.com/PrefectHQ/prefect/pull/17933)
* Add default result storage for work pools by [@desertaxle](https://github.com/desertaxle) in [#17953](https://github.com/PrefectHQ/prefect/pull/17953)
* Remove flow run notifications by [@desertaxle](https://github.com/desertaxle) in [#17939](https://github.com/PrefectHQ/prefect/pull/17939)
* Add version info inference to `flow.deploy()` by [@kevingrismore](https://github.com/kevingrismore) in [#17966](https://github.com/PrefectHQ/prefect/pull/17966)

**Bug Fixes 🐞**

* handle heartbeat event in `wait_for_flow_run` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17930](https://github.com/PrefectHQ/prefect/pull/17930)
* add `parameters` validator to `DeploymentCreateFlowRun` by [@zzstoatzz](https://github.com/zzstoatzz) in [#17938](https://github.com/PrefectHQ/prefect/pull/17938)
* Fix links to Specify flow parameters section by [@bkkkk](https://github.com/bkkkk) in [#17942](https://github.com/PrefectHQ/prefect/pull/17942)
* fix dead-lock between `ConcurrentTaskRunner`, `wait_for`, and tag concurrency limits by [@zzstoatzz](https://github.com/zzstoatzz) in [#17943](https://github.com/PrefectHQ/prefect/pull/17943)
* Remove future garbage collection warning by [@cicdw](https://github.com/cicdw) in [#17954](https://github.com/PrefectHQ/prefect/pull/17954)
* fix: Specify project during Cloud Run provision by [@danfairs](https://github.com/danfairs) in [#17965](https://github.com/PrefectHQ/prefect/pull/17965)
* Remove `extra="forbid"` config on `WorkPoolStorageConfiguration` by [@desertaxle](https://github.com/desertaxle) in [#17960](https://github.com/PrefectHQ/prefect/pull/17960)

**Development & Tidiness 🧹**

* Update `uv.lock` and fix ECS provisioner test errors by [@desertaxle](https://github.com/desertaxle) in [#17928](https://github.com/PrefectHQ/prefect/pull/17928)
* Remove unnecessary walrus by [@zzstoatzz](https://github.com/zzstoatzz) in [#17957](https://github.com/PrefectHQ/prefect/pull/17957)
* Add `logfire` dependency group for performance exploration by [@zzstoatzz](https://github.com/zzstoatzz) in [#17860](https://github.com/PrefectHQ/prefect/pull/17860)
* Bump `astral-sh/setup-uv` from 5 to 6 by [@dependabot](https://github.com/dependabot) in [#17906](https://github.com/PrefectHQ/prefect/pull/17906)
* Update `whenever` requirement from `<0.8.0,>=0.7.3` to `>=0.7.3,<0.9.0` by [@dependabot](https://github.com/dependabot) in [#17962](https://github.com/PrefectHQ/prefect/pull/17962)
* Run integration tests against `prefect-client` by [@desertaxle](https://github.com/desertaxle) in [#17967](https://github.com/PrefectHQ/prefect/pull/17967)
* Update packaging requirement from `<24.3,>=21.3` to `>=21.3,<25.1` by [@dependabot](https://github.com/dependabot) in [#17871](https://github.com/PrefectHQ/prefect/pull/17871)
* Downgrade log to debug level by [@cicdw](https://github.com/cicdw) in [#17970](https://github.com/PrefectHQ/prefect/pull/17970)

**Documentation 📓**

* Add vcs version types for Gitlab, Bitbucket, and Azure Devops by [@kevingrismore](https://github.com/kevingrismore) in [#17915](https://github.com/PrefectHQ/prefect/pull/17915)
* Add documentation for Prefect Cloud GitHub app by [@jakekaplan](https://github.com/jakekaplan) in [#17911](https://github.com/PrefectHQ/prefect/pull/17911)

**Full Changelog**: [https://github.com/PrefectHQ/prefect/compare/3.3.7...3.4.0](https://github.com/PrefectHQ/prefect/compare/3.3.7...3.4.0)

***