Principle:PrefectHQ Prefect Flow Run Querying
| Metadata | |
|---|---|
| Sources | Prefect, Prefect Client |
| Domains | Orchestration, API |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
A pattern for programmatically querying and filtering Prefect flow run records using the async API client with composable filter objects.
Description
Flow Run Querying uses Prefect's async client to read flow run metadata from the Prefect server. It composes filter objects (FlowRunFilter, FlowRunFilterStartTime, FlowRunFilterStateName) to query specific runs by time range, state, and other criteria. This is essential for:
- Maintenance operations — finding old runs to clean up
- Monitoring — checking for failures
- Analytics — run statistics
- Automation — triggering based on run state
The client uses the async context manager pattern for connection management.
Usage
Use this pattern when you need to programmatically access flow run metadata for maintenance, monitoring, reporting, or automation workflows.
Theoretical Basis
Composable filter pattern. Instead of building raw SQL/API queries, the system provides typed filter objects that compose together. FlowRunFilter aggregates sub-filters (start_time, state, etc.) using AND logic. This provides type safety, IDE autocompletion, and prevents query injection.