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.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.
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 |
|---|---|---|
Scheduled | SCHEDULED | Task is scheduled for execution |
Late | SCHEDULED | Scheduled task was not started on time |
AwaitingConcurrencySlot | SCHEDULED | Waiting for a concurrency slot |
AwaitingRetry | SCHEDULED | Waiting before a retry attempt |
Pending | PENDING | Task is ready to execute |
Running | RUNNING | Task is actively executing |
Retrying | RUNNING | Task is retrying after a failure |
Completed | COMPLETED | Task finished successfully |
Failed | FAILED | Task finished with an error |
Crashed | CRASHED | Task terminated unexpectedly |
Cancelled | CANCELLED | Task was cancelled |
Cancelling | CANCELLING | Cancellation was requested but not yet confirmed |
Paused | PAUSED | Task is paused |
Suspended | PAUSED | Task is suspended |
Resource
| Label | Description |
|---|---|
prefect.resource.id | prefect.task-run.{uuid} |
prefect.resource.name | Task run name |
prefect.run-count | Number of times this task run has been attempted |
prefect.state-message | Message associated with the state transition (truncated to 100,000 characters) |
prefect.state-name | State name (for example, Running) |
prefect.state-timestamp | ISO 8601 timestamp of the state transition |
prefect.state-type | State type enum value (for example, RUNNING, COMPLETED) |
prefect.orchestration | Always client (task state transitions are managed locally) |
Related resources
| Resource ID pattern | Role | When present |
|---|---|---|
prefect.tag.{tag} | tag | One 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.from | string or null | State type of the initial state (null for the first transition) |
intended.to | string | State type of the validated (new) state |
initial_state | object or null | Previous state: type, name, message, state_details |
validated_state | object | New state: type, name, message, state_details, and data (result metadata when result persistence is enabled) |
task_run | object | Task run metadata including name, task_key, dynamic_key, flow_run_id, tags, and task_inputs |