Documentation Index Fetch the complete documentation index at: https://docs.prefect.io/llms.txt
Use this file to discover all available pages before exploring further.
Flow run events track the lifecycle of every flow run, from scheduling through
completion. They are emitted on every state transition and, optionally, as
periodic heartbeats during execution.
prefect.flow-run.{state}Emitted each time a flow run transitions to a new state. The {state} suffix is
the state name (for example, prefect.flow-run.Running or
prefect.flow-run.Completed).
State variants State name State type Description ScheduledSCHEDULED Run is scheduled for future execution LateSCHEDULED Scheduled run was not started on time AwaitingConcurrencySlotSCHEDULED Waiting for a concurrency slot AwaitingRetrySCHEDULED Waiting before a retry attempt PendingPENDING Run is ready to execute RunningRUNNING Run is actively executing RetryingRUNNING Run is retrying after a failure CompletedCOMPLETED Run finished successfully FailedFAILED Run finished with an error CrashedCRASHED Run terminated unexpectedly (infrastructure failure) CancelledCANCELLED Run was cancelled CancellingCANCELLING Cancellation was requested but not yet confirmed PausedPAUSED Run is paused, waiting for input or manual resumption SuspendedPAUSED Run is suspended and its infrastructure may be freed
Resource Label Description prefect.resource.idprefect.flow-run.{uuid}prefect.resource.nameFlow run name (for example, crimson-fox) prefect.run-countNumber of times this run has been attempted prefect.state-messageMessage associated with the state transition (truncated to 100,000 characters) prefect.state-nameState name (for example, Running) prefect.state-timestampISO 8601 timestamp of the state transition prefect.state-typeState type enum value (for example, RUNNING, COMPLETED)
Resource ID pattern Role When present prefect.flow.{uuid}flowAlways prefect.deployment.{uuid}deploymentWhen triggered by a deployment prefect.work-queue.{uuid}work-queueWhen a work queue is assigned prefect.work-pool.{uuid}work-poolWhen a work pool is assigned (includes prefect.work-pool.type label) prefect.task-run.{uuid}task-runWhen the flow run is a subflow called from a task prefect.tag.{tag}tagOne entry per tag on the flow run or its flow/deployment prefect.deployment.{uuid} or prefect.automation.{uuid}creatorProvenance: which deployment or automation created this run
Payload Field Type Description intended.fromstring or null State type of the initial state (null for the first transition) intended.tostring State type of the validated (new) state initial_stateobject or null Previous state: type, name, message, and pause_reschedule if paused validated_stateobject New state: type, name, message, and pause_reschedule if paused
Show Example: flow run transitions to Running
{ "occurred" : "2026-03-31T18:30:00.000000Z" , "event" : "prefect.flow-run.Running" , "resource" : { "prefect.resource.id" : "prefect.flow-run.e3755d32-cec5-42ca-9bcd-af236e308ba6" , "prefect.resource.name" : "crimson-fox" , "prefect.run-count" : "1" , "prefect.state-message" : "" , "prefect.state-name" : "Running" , "prefect.state-timestamp" : "2026-03-31T18:30:00.000000Z" , "prefect.state-type" : "RUNNING" }, "related" : [ { "prefect.resource.id" : "prefect.flow.a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "prefect.resource.name" : "my-etl-flow" , "prefect.resource.role" : "flow" }, { "prefect.resource.id" : "prefect.deployment.b2c3d4e5-f6a7-8901-bcde-f12345678901" , "prefect.resource.name" : "my-etl-flow/production" , "prefect.resource.role" : "deployment" }, { "prefect.resource.id" : "prefect.work-pool.c3d4e5f6-a7b8-9012-cdef-123456789012" , "prefect.resource.name" : "my-k8s-pool" , "prefect.work-pool.type" : "kubernetes" , "prefect.resource.role" : "work-pool" }, { "prefect.resource.id" : "prefect.tag.production" , "prefect.resource.role" : "tag" } ], "payload" : { "intended" : { "from" : "PENDING" , "to" : "RUNNING" }, "initial_state" : { "type" : "PENDING" , "name" : "Pending" }, "validated_state" : { "type" : "RUNNING" , "name" : "Running" } }, "id" : "f6a7b890-1234-5678-9012-abcdef345678" , "follows" : "d4e5f6a7-b890-1234-5678-9012abcdef34" }
prefect.flow-run.heartbeatEmitted periodically during flow run execution when heartbeat frequency is configured.
Used for liveness detection, particularly with
zombie flow detection .
Resource Label Description prefect.resource.idprefect.flow-run.{uuid}prefect.resource.nameFlow run name prefect.versionPrefect SDK version
Resource ID pattern Role When present prefect.flow.{uuid}flowAlways prefect.deployment.{uuid}deploymentWhen triggered by a deployment prefect.tag.{tag}tagOne entry per tag
Payload This event has no payload. 
