docs/v3/api-ref/events/task-run-events.mdx
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).
| 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 |
| 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) |
| Resource ID pattern | Role | When present |
|---|---|---|
prefect.tag.{tag} | tag | One entry per tag on the task run |
| 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 |
{
"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"
}