Task run events track the lifecycle of every task run within a flow. They are
emitted on every state transition, mirroring the structure of
flow run state events .
prefect.task-run.{state}Emitted each time a task run transitions to a new state. The {state} suffix is
the state name (for example, prefect.task-run.Running or
prefect.task-run.Completed).
Task state transitions are managed locally by the task engine, not proposed to the
server like flow run states. The task engine emits these events and delivers them
via the events system.
State variants State name State type Description ScheduledSCHEDULED Task is scheduled for execution LateSCHEDULED Scheduled task was not started on time AwaitingConcurrencySlotSCHEDULED Waiting for a concurrency slot AwaitingRetrySCHEDULED Waiting before a retry attempt PendingPENDING Task is ready to execute RunningRUNNING Task is actively executing RetryingRUNNING Task is retrying after a failure CompletedCOMPLETED Task finished successfully FailedFAILED Task finished with an error CrashedCRASHED Task terminated unexpectedly CancelledCANCELLED Task was cancelled CancellingCANCELLING Cancellation was requested but not yet confirmed PausedPAUSED Task is paused SuspendedPAUSED Task is suspended
Resource Label Description prefect.resource.idprefect.task-run.{uuid}prefect.resource.nameTask run name prefect.run-countNumber of times this task 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) prefect.orchestrationAlways client (task state transitions are managed locally)
Resource ID pattern Role When present prefect.tag.{tag}tagOne entry per tag on the task run
Unlike flow run events, task run state events do not include the parent flow run,
flow, or deployment as related resources. Task run context (including the parent
flow run ID) is available in the event payload under task_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, state_details validated_stateobject New state: type, name, message, state_details, and data (result metadata when result persistence is enabled) task_runobject Task run metadata including name, task_key, dynamic_key, flow_run_id, tags, and task_inputs
Show Example: task run transitions to Completed
{ "occurred" : "2026-03-31T18:31:05.000000Z" , "event" : "prefect.task-run.Completed" , "resource" : { "prefect.resource.id" : "prefect.task-run.a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "prefect.resource.name" : "extract-data-0" , "prefect.run-count" : "1" , "prefect.state-message" : "" , "prefect.state-name" : "Completed" , "prefect.state-timestamp" : "2026-03-31T18:31:05.000000Z" , "prefect.state-type" : "COMPLETED" , "prefect.orchestration" : "client" }, "related" : [ { "prefect.resource.id" : "prefect.tag.etl" , "prefect.resource.role" : "tag" } ], "payload" : { "intended" : { "from" : "RUNNING" , "to" : "COMPLETED" }, "initial_state" : { "type" : "RUNNING" , "name" : "Running" }, "validated_state" : { "type" : "COMPLETED" , "name" : "Completed" }, "task_run" : { "name" : "extract-data-0" , "task_key" : "extract_data" , "dynamic_key" : "0" , "flow_run_id" : "e3755d32-cec5-42ca-9bcd-af236e308ba6" , "tags" : [ "etl" ] } }, "id" : "b890c123-4567-89ab-cdef-0123456789ab" }
