> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Events reference

> Event format, naming conventions, and the full payload for every event type.

## Event format

Events follow an `object.action` naming convention. Every event is delivered with the same envelope. The `data` field contains a summary of the resource at the time of the event.

```json theme={null}
{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "credential.verified",
  "data": {
    "id": "cred_a1b2c3d4",
    "object": "credential",
    "status": "verified",
    "external_id": "user-12345",
    "source_id": "src_a1b2c3d4",
    "auth_method": "username_password",
    "created_at": "2025-01-15T09:28:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z"
}
```

| Field | Description |
| - | - |
| `id` | Unique event identifier with the `evt_` prefix. |
| `object` | Always `event`. |
| `type` | The event type in `object.action` format. |
| `data` | Summary of the resource at the time of the event. The shape depends on the resource, see the sections below. |
| `created_at` | When the event occurred (ISO 8601). |
| `request_id` | The API request that triggered the event, with the `req_` prefix. Only present when the event was caused by an API call. |

Fields that have no value yet are delivered as empty strings. For example, a task run that is not part of a workflow has `"workflow_id": ""`.

One event type falls outside the catalog below: `test.ping`, with a `data` payload of `{"ok": true}`. It's only delivered when you [send a test event](https://docs.deck.co/events/destinations-and-deliveries.md#sending-a-test-event) to a destination and isn't a subscribable type.

## Agent events

| Type | Fired when |
| - | - |
| `agent.created` | An agent is created |
| `agent.updated` | An agent is updated |
| `agent.deleted` | An agent is deleted |

> [accordion] agent.created
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "agent.created",
>   "data": {
>     "id": "agt_a1b2c3d4",
>     "object": "agent",
>     "name": "Utility bills agent",
>     "description": "Fetches utility bills and account data",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] agent.updated
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "agent.updated",
>   "data": {
>     "id": "agt_a1b2c3d4",
>     "object": "agent",
>     "name": "Utility bills agent",
>     "description": "Fetches utility bills, statements, and account data",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-16T14:02:00Z"
>   },
>   "created_at": "2025-01-16T14:02:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] agent.deleted
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "agent.deleted",
>   "data": {
>     "id": "agt_a1b2c3d4",
>     "object": "agent",
>     "name": "Utility bills agent",
>     "description": "Fetches utility bills, statements, and account data",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-20T11:45:00Z"
>   },
>   "created_at": "2025-01-20T11:45:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

## Source events

| Type | Fired when |
| - | - |
| `source.created` | A source is created |
| `source.updated` | A source is updated |
| `source.deleted` | A source is deleted |

> [accordion] source.created
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "source.created",
>   "data": {
>     "id": "src_a1b2c3d4",
>     "object": "source",
>     "name": "ConEdison",
>     "type": "website",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] source.updated
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "source.updated",
>   "data": {
>     "id": "src_a1b2c3d4",
>     "object": "source",
>     "name": "ConEdison",
>     "type": "website",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-16T14:02:00Z"
>   },
>   "created_at": "2025-01-16T14:02:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] source.deleted
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "source.deleted",
>   "data": {
>     "id": "src_a1b2c3d4",
>     "object": "source",
>     "name": "ConEdison",
>     "type": "website",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-20T11:45:00Z"
>   },
>   "created_at": "2025-01-20T11:45:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

## Credential events

| Type | Fired when |
| - | - |
| `credential.created` | A new credential is created with `unverified` status |
| `credential.unverified` | A `verified` or `invalid` credential's auth details were updated, resetting it to `unverified` |
| `credential.verified` | A task run using the credential completed successfully, moving it to `verified` |
| `credential.invalid` | Credentials were rejected by the source |
| `credential.deleted` | Credential was permanently removed from the vault |

> [accordion] credential.created
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "credential.created",
>   "data": {
>     "id": "cred_a1b2c3d4",
>     "object": "credential",
>     "status": "unverified",
>     "external_id": "user-12345",
>     "source_id": "src_a1b2c3d4",
>     "auth_method": "username_password",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] credential.unverified
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "credential.unverified",
>   "data": {
>     "id": "cred_a1b2c3d4",
>     "object": "credential",
>     "status": "unverified",
>     "external_id": "user-12345",
>     "source_id": "src_a1b2c3d4",
>     "auth_method": "username_password",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-16T14:02:00Z"
>   },
>   "created_at": "2025-01-16T14:02:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] credential.verified
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "credential.verified",
>   "data": {
>     "id": "cred_a1b2c3d4",
>     "object": "credential",
>     "status": "verified",
>     "external_id": "user-12345",
>     "source_id": "src_a1b2c3d4",
>     "auth_method": "username_password",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:32:00Z"
>   },
>   "created_at": "2025-01-15T09:32:00Z"
> }
> ```

> [accordion] credential.invalid
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "credential.invalid",
>   "data": {
>     "id": "cred_a1b2c3d4",
>     "object": "credential",
>     "status": "invalid",
>     "external_id": "user-12345",
>     "source_id": "src_a1b2c3d4",
>     "auth_method": "username_password",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:32:00Z"
>   },
>   "created_at": "2025-01-15T09:32:00Z"
> }
> ```

> [accordion] credential.deleted
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "credential.deleted",
>   "data": {
>     "id": "cred_a1b2c3d4",
>     "object": "credential",
>     "status": "deleted",
>     "external_id": "user-12345",
>     "source_id": "src_a1b2c3d4",
>     "auth_method": "username_password",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-20T11:45:00Z"
>   },
>   "created_at": "2025-01-20T11:45:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

## Session events

| Type | Fired when |
| - | - |
| `session.queued` | Session is waiting to be provisioned |
| `session.running` | Session is active and executing |
| `session.idle` | No active tasks, session is waiting for new work |
| `session.completing` | Work is done, session is shutting down |
| `session.completed` | Session finished and was closed |
| `session.failed` | Session encountered an error |

> [accordion] session.queued
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "session.queued",
>   "data": {
>     "id": "sess_a1b2c3d4",
>     "object": "session",
>     "status": "queued",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] session.running
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "session.running",
>   "data": {
>     "id": "sess_a1b2c3d4",
>     "object": "session",
>     "status": "running",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:05Z"
>   },
>   "created_at": "2025-01-15T09:30:05Z"
> }
> ```

> [accordion] session.idle
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "session.idle",
>   "data": {
>     "id": "sess_a1b2c3d4",
>     "object": "session",
>     "status": "idle",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:31:20Z"
>   },
>   "created_at": "2025-01-15T09:31:20Z"
> }
> ```

> [accordion] session.completing
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "session.completing",
>   "data": {
>     "id": "sess_a1b2c3d4",
>     "object": "session",
>     "status": "completing",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:32:00Z"
>   },
>   "created_at": "2025-01-15T09:32:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] session.completed
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "session.completed",
>   "data": {
>     "id": "sess_a1b2c3d4",
>     "object": "session",
>     "status": "completed",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:32:10Z"
>   },
>   "created_at": "2025-01-15T09:32:10Z"
> }
> ```

> [accordion] session.failed
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "session.failed",
>   "data": {
>     "id": "sess_a1b2c3d4",
>     "object": "session",
>     "status": "failed",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:31:40Z"
>   },
>   "created_at": "2025-01-15T09:31:40Z"
> }
> ```

## Task events

| Type | Fired when |
| - | - |
| `task.created` | A task is created |
| `task.updated` | A task definition is updated |
| `task.reset` | A task is reset to `learning`, invalidating its cached plan |
| `task.deleted` | A task is deleted |

> [accordion] task.created
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task.created",
>   "data": {
>     "id": "task_a1b2c3d4",
>     "object": "task",
>     "name": "Fetch latest bill",
>     "status": "learning",
>     "agent_id": "agt_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] task.updated
>
> Also fired when a task graduates to a new status after successful runs, for example `learning` to `test`.
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task.updated",
>   "data": {
>     "id": "task_a1b2c3d4",
>     "object": "task",
>     "name": "Fetch latest bill",
>     "status": "test",
>     "agent_id": "agt_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-16T14:02:00Z"
>   },
>   "created_at": "2025-01-16T14:02:00Z"
> }
> ```

> [accordion] task.reset
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task.reset",
>   "data": {
>     "id": "task_a1b2c3d4",
>     "object": "task",
>     "name": "Fetch latest bill",
>     "status": "learning",
>     "agent_id": "agt_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-18T10:15:00Z"
>   },
>   "created_at": "2025-01-18T10:15:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] task.deleted
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task.deleted",
>   "data": {
>     "id": "task_a1b2c3d4",
>     "object": "task",
>     "name": "Fetch latest bill",
>     "status": "live",
>     "agent_id": "agt_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-20T11:45:00Z"
>   },
>   "created_at": "2025-01-20T11:45:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

## Task run events

| Type | Fired when |
| - | - |
| `task_run.queued` | Run is waiting to start |
| `task_run.running` | Execution begins |
| `task_run.completed` | Run finishes successfully |
| `task_run.failed` | Run encounters an error |
| `task_run.canceling` | Cancellation requested, agent is stopping |
| `task_run.canceled` | Run is canceled |
| `task_run.interaction_required` | User input is needed during execution |

Task run payloads share the same fields. `result` is empty until the run reaches a final result, then becomes `success` or `failure`. `runtime_ms` appears once the run has finished. `workflow_id` is empty for runs that are not part of a workflow. A run created by a [workflow](https://docs.deck.co/concepts/workflows.md) step also carries `workflow_run_id` and `step`, the name of the step that created it, and a run created by a trigger carries `trigger_id`. All three are omitted otherwise.

> [accordion] task\_run.queued
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task_run.queued",
>   "data": {
>     "id": "trun_a1b2c3d4",
>     "object": "task_run",
>     "status": "queued",
>     "result": "",
>     "task_id": "task_a1b2c3d4",
>     "workflow_id": "",
>     "credential_id": "cred_a1b2c3d4",
>     "session_id": "sess_a1b2c3d4",
>     "agent_id": "agt_a1b2c3d4",
>     "source_id": "src_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] task\_run.running
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task_run.running",
>   "data": {
>     "id": "trun_a1b2c3d4",
>     "object": "task_run",
>     "status": "running",
>     "result": "",
>     "task_id": "task_a1b2c3d4",
>     "workflow_id": "",
>     "credential_id": "cred_a1b2c3d4",
>     "session_id": "sess_a1b2c3d4",
>     "agent_id": "agt_a1b2c3d4",
>     "source_id": "src_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:05Z"
>   },
>   "created_at": "2025-01-15T09:30:05Z"
> }
> ```

> [accordion] task\_run.completed
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task_run.completed",
>   "data": {
>     "id": "trun_a1b2c3d4",
>     "object": "task_run",
>     "status": "completed",
>     "result": "success",
>     "task_id": "task_a1b2c3d4",
>     "workflow_id": "",
>     "credential_id": "cred_a1b2c3d4",
>     "session_id": "sess_a1b2c3d4",
>     "agent_id": "agt_a1b2c3d4",
>     "source_id": "src_a1b2c3d4",
>     "runtime_ms": 12453,
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:31:15Z"
>   },
>   "created_at": "2025-01-15T09:31:15Z"
> }
> ```

> [accordion] task\_run.failed
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task_run.failed",
>   "data": {
>     "id": "trun_a1b2c3d4",
>     "object": "task_run",
>     "status": "failed",
>     "result": "failure",
>     "task_id": "task_a1b2c3d4",
>     "workflow_id": "",
>     "credential_id": "cred_a1b2c3d4",
>     "session_id": "sess_a1b2c3d4",
>     "agent_id": "agt_a1b2c3d4",
>     "source_id": "src_a1b2c3d4",
>     "runtime_ms": 8420,
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:55Z"
>   },
>   "created_at": "2025-01-15T09:30:55Z"
> }
> ```

> [accordion] task\_run.canceling
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task_run.canceling",
>   "data": {
>     "id": "trun_a1b2c3d4",
>     "object": "task_run",
>     "status": "canceling",
>     "result": "",
>     "task_id": "task_a1b2c3d4",
>     "workflow_id": "",
>     "credential_id": "cred_a1b2c3d4",
>     "session_id": "sess_a1b2c3d4",
>     "agent_id": "agt_a1b2c3d4",
>     "source_id": "src_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:40Z"
>   },
>   "created_at": "2025-01-15T09:30:40Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] task\_run.canceled
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task_run.canceled",
>   "data": {
>     "id": "trun_a1b2c3d4",
>     "object": "task_run",
>     "status": "canceled",
>     "result": "",
>     "task_id": "task_a1b2c3d4",
>     "workflow_id": "",
>     "credential_id": "cred_a1b2c3d4",
>     "session_id": "sess_a1b2c3d4",
>     "agent_id": "agt_a1b2c3d4",
>     "source_id": "src_a1b2c3d4",
>     "runtime_ms": 41200,
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:45Z"
>   },
>   "created_at": "2025-01-15T09:30:45Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] task\_run.interaction\_required
>
> Includes an `interaction` object describing the input to collect. See [Handling interactions](https://docs.deck.co/guides/interactions.md) for the full interaction object reference.
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "task_run.interaction_required",
>   "data": {
>     "id": "trun_a1b2c3d4",
>     "object": "task_run",
>     "status": "interaction_required",
>     "result": "",
>     "task_id": "task_a1b2c3d4",
>     "workflow_id": "",
>     "credential_id": "cred_a1b2c3d4",
>     "session_id": "sess_a1b2c3d4",
>     "agent_id": "agt_a1b2c3d4",
>     "source_id": "src_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:30Z",
>     "interaction": {
>       "type": "mfa",
>       "message": "Enter the 6-digit code sent to your phone",
>       "fields": [
>         {
>           "name": "code",
>           "type": "string",
>           "label": "Verification code"
>         }
>       ]
>     }
>   },
>   "created_at": "2025-01-15T09:30:30Z"
> }
> ```

## Workflow events

| Type | Fired when |
| - | - |
| `workflow.created` | A workflow is created |
| `workflow.updated` | A workflow is updated via PATCH |
| `workflow.deleted` | A workflow is deleted |

Workflow payloads carry the definition's identity, not its steps. Fetch `GET /v2/workflows/{workflow_id}` for the current definition.

> [accordion] workflow\.created
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow.created",
>   "data": {
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "name": "Price drop rebooking",
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] workflow\.updated
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow.updated",
>   "data": {
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "name": "Price drop auto-rebooking",
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-16T14:02:00Z"
>   },
>   "created_at": "2025-01-16T14:02:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] workflow\.deleted
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow.deleted",
>   "data": {
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "name": "Price drop auto-rebooking",
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-20T11:45:00Z"
>   },
>   "created_at": "2025-01-20T11:45:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

## Workflow run events

| Type | Fired when |
| - | - |
| `workflow_run.queued` | Run is waiting to start |
| `workflow_run.running` | A step begins executing |
| `workflow_run.paused` | The current step is waiting on external input, such as MFA |
| `workflow_run.completed` | All steps finished |
| `workflow_run.failed` | A step failed and the workflow stopped |
| `workflow_run.canceling` | Cancellation requested, the current step is stopping |
| `workflow_run.canceled` | Run is canceled |

Every status transition emits exactly once. Workflow run payloads share the same fields. `result` is `null` until the run reaches a terminal status, then becomes `success`, `failure`, or `unknown` (and stays `null` for a canceled run). `session_id` is the session every step of the run executes in, and `trigger_id` names the trigger that created the run, or `null` for runs created through the API. Per-step detail isn't in the payload; fetch `GET /v2/workflow-runs/{workflow_run_id}` for step statuses and outputs, or subscribe to the `task_run.*` events each step emits.

> [accordion] workflow\_run.queued
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow_run.queued",
>   "data": {
>     "workflow_run_id": "wrun_a1b2c3d4",
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "status": "queued",
>     "result": null,
>     "session_id": "sess_a1b2c3d4",
>     "trigger_id": null,
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:00Z"
>   },
>   "created_at": "2025-01-15T09:30:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] workflow\_run.running
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow_run.running",
>   "data": {
>     "workflow_run_id": "wrun_a1b2c3d4",
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "status": "running",
>     "result": null,
>     "session_id": "sess_a1b2c3d4",
>     "trigger_id": null,
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:04Z"
>   },
>   "created_at": "2025-01-15T09:30:04Z"
> }
> ```

> [accordion] workflow\_run.paused
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow_run.paused",
>   "data": {
>     "workflow_run_id": "wrun_a1b2c3d4",
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "status": "paused",
>     "result": null,
>     "session_id": "sess_a1b2c3d4",
>     "trigger_id": null,
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:31:12Z"
>   },
>   "created_at": "2025-01-15T09:31:12Z"
> }
> ```

> [accordion] workflow\_run.completed
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow_run.completed",
>   "data": {
>     "workflow_run_id": "wrun_a1b2c3d4",
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "status": "completed",
>     "result": "success",
>     "session_id": "sess_a1b2c3d4",
>     "trigger_id": null,
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:32:13Z"
>   },
>   "created_at": "2025-01-15T09:32:13Z"
> }
> ```

> [accordion] workflow\_run.failed
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow_run.failed",
>   "data": {
>     "workflow_run_id": "wrun_a1b2c3d4",
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "status": "failed",
>     "result": "failure",
>     "session_id": "sess_a1b2c3d4",
>     "trigger_id": null,
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:31:07Z"
>   },
>   "created_at": "2025-01-15T09:31:07Z"
> }
> ```

> [accordion] workflow\_run.canceling
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow_run.canceling",
>   "data": {
>     "workflow_run_id": "wrun_a1b2c3d4",
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "status": "canceling",
>     "result": null,
>     "session_id": "sess_a1b2c3d4",
>     "trigger_id": null,
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:31Z"
>   },
>   "created_at": "2025-01-15T09:30:31Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```

> [accordion] workflow\_run.canceled
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "workflow_run.canceled",
>   "data": {
>     "workflow_run_id": "wrun_a1b2c3d4",
>     "workflow_id": "wflo_a1b2c3d4",
>     "org_id": "org_a1b2c3d4",
>     "status": "canceled",
>     "result": null,
>     "session_id": "sess_a1b2c3d4",
>     "trigger_id": null,
>     "created_by": "usr_a1b2c3d4",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:38Z"
>   },
>   "created_at": "2025-01-15T09:30:38Z"
> }
> ```

## Storage events

| Type | Fired when |
| - | - |
| `storage.created` | A file is stored during a task run |
| `storage.deleted` | A file is deleted through the API |

> [accordion] storage.created
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "storage.created",
>   "data": {
>     "id": "stor_a1b2c3d4",
>     "object": "storage",
>     "file_name": "statement-2025-01.pdf",
>     "file_type": "application/pdf",
>     "file_size": 245678,
>     "fetch_date": "2025-01-15T09:31:10Z",
>     "task_run_id": "trun_a1b2c3d4",
>     "created_at": "2025-01-15T09:31:12Z"
>   },
>   "created_at": "2025-01-15T09:31:12Z"
> }
> ```

> [accordion] storage.deleted
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "storage.deleted",
>   "data": {
>     "id": "stor_a1b2c3d4",
>     "object": "storage",
>     "file_name": "statement-2025-01.pdf",
>     "file_type": "application/pdf",
>     "file_size": 245678,
>     "fetch_date": "2025-01-15T09:31:10Z",
>     "task_run_id": "trun_a1b2c3d4",
>     "created_at": "2025-01-15T09:31:12Z"
>   },
>   "created_at": "2025-02-01T14:05:00Z"
> }
> ```

## Event destination events

| Type | Fired when |
| - | - |
| `event_destination.activated` | A destination passes verification and becomes active |
| `event_destination.deactivated` | A destination becomes inactive, either set by you or automatically after repeated delivery failures |

> [accordion] event\_destination.activated
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "event_destination.activated",
>   "data": {
>     "id": "evtd_a1b2c3d4",
>     "object": "event_destination",
>     "name": "Production Webhook",
>     "status": "active",
>     "type": "webhook",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-15T09:30:10Z"
>   },
>   "created_at": "2025-01-15T09:30:10Z"
> }
> ```

> [accordion] event\_destination.deactivated
>
> ```json theme={null}
> {
>   "id": "evt_a1b2c3d4",
>   "object": "event",
>   "type": "event_destination.deactivated",
>   "data": {
>     "id": "evtd_a1b2c3d4",
>     "object": "event_destination",
>     "name": "Production Webhook",
>     "status": "inactive",
>     "type": "webhook",
>     "created_at": "2025-01-15T09:30:00Z",
>     "updated_at": "2025-01-20T11:45:00Z"
>   },
>   "created_at": "2025-01-20T11:45:00Z",
>   "request_id": "req_a1b2c3d4"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.