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

# Events & diagnostics

> Trace definitions, payloads, and handling guidance for events & diagnostics.

[All traces](/docs/api-reference/trace-types)

{/* gen:start id=traces/spec sha=e06469d87148 */}

## `completion`

Marks a model completion event during the turn. Streaming clients receive the completion lifecycle described under completion event traces.

| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `ai` | boolean | no | `state` is `start` |
| `content` | string | no | `state` is `content` |
| `delay` | number | no | `state` is `start` |
| `messageID` | string | no | always |
| `ref` | DebugTraceRef | no | `state` is `start` or `end` |
| `sourceUrls` | object[] | no | `state` is `start` |
| `state` | `"start"` or `"content"` or `"end"` | yes | always |

## `reasoning`

Marks model reasoning activity during the turn. The payload's `state` field selects the shape: `content` carries a `content` string, `final` carries a `message`, and `start` and `end` carry the state alone.

| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `content` | string | no | `state` is `content` |
| `message` | string | no | `state` is `final` |
| `state` | `"start"` or `"content"` or `"end"` or `"final"` | yes | always |

## `tool-call`

Marks a tool call made by the agent during the turn. The payload always carries the `callID` and a `state` of `start` or `end`; a `start` may also carry a `sound`.

| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `callID` | string | yes | always |
| `sound` | object | no | `state` is `start` |
| `state` | `"start"` or `"end"` | yes | always |

## `knowledgeBase`

Reports a knowledge base retrieval: the chunks returned and the query that produced them.

| Field | Type | Required |
| --- | --- | --- |
| `chunks` | object[] | yes |
| `query` | object | no |

## `realtime-agent`

Marks realtime agent activity on the turn. The payload's `action` field selects the shape: `START` carries `input` and `output`, while `END` and `INTERRUPTED` carry the action alone.

| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `action` | `"START"` or `"END"` or `"INTERRUPTED"` | yes | always |
| `input` | object | no | `action` is `START` |
| `output` | object | no | `action` is `START` |

## `block`

Marks the conversation entering a block, identified by its block ID.

| Field | Type | Required |
| --- | --- | --- |
| `blockID` | string | yes |

## `flow`

Marks the conversation entering a flow, identified by its diagram ID.

| Field | Type | Required |
| --- | --- | --- |
| `diagramID` | string | yes |
| `name` | string | no |

## `path`

Reports which path the conversation took out of a step.

| Field | Type | Required |
| --- | --- | --- |
| `path` | string | yes |

## `debug`

Debug output for the turn, with a message and optional level, context, and metadata. Surfaced in agent logs rather than to end users.

| Field | Type | Required |
| --- | --- | --- |
| `context` | string | no |
| `level` | `"fatal"` or `"error"` or `"warn"` or `"info"` or `"debug"` | no |
| `message` | string | yes |
| `metadata` | object | no |
| `ref` | DebugTraceRef | no |
| `type` | string | no |

## `log`

Diagnostic log output attached to the turn. The `payload` is always present and is a free-form object: the spec declares no named fields on it and permits any.
{/* gen:end id=traces/spec */}