Implementation:PrefectHQ Prefect Client Read Flow Runs

Metadata
Sources	Prefect
Domains	Orchestration, API
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete async client method for querying flow run records with composable filters provided by the Prefect library.

Description

The client.read_flow_runs method queries the Prefect server for flow run records matching specified filters. Used with get_client() async context manager. Filters are composed from FlowRunFilter, FlowRunFilterStartTime, and FlowRunFilterStateName.

Code Reference

Repository: https://github.com/PrefectHQ/prefect
File: examples/ai_database_cleanup_with_approval.py (L204-212), src/prefect/client/orchestration/__init__.py (L189) for get_client
Signature:

async with get_client() as client:
    flow_runs = await client.read_flow_runs(
        flow_run_filter=FlowRunFilter(
            start_time=FlowRunFilterStartTime(before_=cutoff),
            state=FlowRunFilterStateName(any_=config.states_to_clean),
        ),
        limit=config.batch_size * 5,
    )

Import: from prefect import get_client; from prefect.client.schemas.filters import FlowRunFilter, FlowRunFilterStartTime, FlowRunFilterStateName

I/O Contract

Inputs

flow_run_filter (FlowRunFilter, optional) — composable filter object
limit (int, optional) — max results

Outputs

list[FlowRun] — list of flow run objects with id, name, state, start_time

Usage Example

from datetime import datetime, timedelta, timezone
from prefect import get_client
from prefect.client.schemas.filters import (
    FlowRunFilter, FlowRunFilterStartTime, FlowRunFilterStateName,
)

async def find_old_runs():
    cutoff = datetime.now(timezone.utc) - timedelta(days=30)
    async with get_client() as client:
        runs = await client.read_flow_runs(
            flow_run_filter=FlowRunFilter(
                start_time=FlowRunFilterStartTime(before_=cutoff),
                state=FlowRunFilterStateName(any_=["Completed", "Failed"]),
            ),
            limit=500,
        )
    return runs

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment