In Prefect 3.x,

get_client()

gives you a Python client for talking directly to the Prefect API. Basic usage

python
from prefect import get_client

async def main():
    async with get_client() as client:
        flow_runs = await client.read_flow_runs(limit=10)
        print(flow_runs)

Or sync:

python
from prefect import get_client

def main():
    with get_client(sync_client=True) as client:
        flow_runs = client.read_flow_runs(limit=10)
        print(flow_runs)

What it returns -

get_client()

→ async

PrefectClient

-

get_client(sync_client=True)

→ sync

SyncPrefectClient

What it talks to It connects over HTTP to your configured Prefect API: - Prefect Cloud - a self-hosted Prefect server - or, in some cases, an ephemeral local API if configured That configuration typically comes from: -

PREFECT_API_URL

-

PREFECT_API_KEY

Common pattern Use it as a context manager: -

async with get_client() as client:

-

with get_client(sync_client=True) as client:

That ensures connections are opened/closed properly. What you can do with it It exposes methods for working with Prefect objects such as: - flow runs - task runs - deployments - work pools / work queues - blocks - variables - artifacts - logs For example:

python
from prefect import get_client

async def inspect():
    async with get_client() as client:
        deployments = await client.read_deployments()
        for d in deployments:
            print(d.name)

A few important notes - The default client is async - If you're not already in async code, use

sync_client=True

- It is a low-level API client, so it’s most useful for scripts, admin tooling, integrations, and custom automation If you want, I can also show: 1. the most useful methods on

client

2. how

get_client()

differs from using flows/tasks normally 3. a real example like “find a deployment and trigger a flow run” Relevant docs/source: - Prefect docs - Client orchestration reference

Not directly via

get_client(...)

itself.

get_client()

uses the active Prefect settings/profile context, so if you want it to use values from a specific

profiles.toml

, you generally need to point Prefect at that file before creating the client. Most commonly, that means setting:

bash
export PREFECT_PROFILES_PATH=/path/to/profiles.toml

Then

get_client()

will read the active profile from that file. You’d also typically set/select the profile:

bash
prefect profile use my-profile

Or make sure the desired profile is active in that file. So the pattern is:

bash
export PREFECT_PROFILES_PATH=/path/to/profiles.toml
prefect profile use my-profile
python my_script.py

Then in Python:

python
from prefect import get_client

async def main():
    async with get_client() as client:
        print(await client.hello())

If you want to avoid relying on profiles entirely, another option is to set the API settings explicitly via environment variables: -

PREFECT_API_URL

-

PREFECT_API_KEY

That’s often simpler for scripts and CI. If you want, I can show you: - how to do this inside Python only - how to temporarily switch profiles for one script - or how to pass settings without using profiles at all