> ## 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": ""`.
## Agent events
| Type | Fired when |
| --------------- | ------------------- |
| `agent.created` | An agent is created |
| `agent.updated` | An agent is updated |
| `agent.deleted` | An agent is deleted |
```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"
}
```
```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"
}
```
```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 |
```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"
}
```
```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"
}
```
```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 |
```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"
}
```
```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"
}
```
```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"
}
```
```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"
}
```
```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 |
```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"
}
```
```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"
}
```
```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"
}
```
```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"
}
```
```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"
}
```
```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 |
```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"
}
```
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"
}
```
```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"
}
```
```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.
```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"
}
```
```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"
}
```
```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"
}
```
```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"
}
```
```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"
}
```
```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"
}
```
Includes an `interaction` object describing the input to collect. See [Handling interactions](/guides/interactions) 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"
}
```
## Storage events
| Type | Fired when |
| ----------------- | ---------------------------------- |
| `storage.created` | A file is stored during a task run |
```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"
}
```
## Event destination events
| Type | Fired when |
| ------------------------------- | ---------------------------------------------------- |
| `event_destination.activated` | A destination passes verification and becomes active |
| `event_destination.deactivated` | A destination is disabled |
```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"
}
```
```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"
}
```