> ## 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 and diagnostics

> Read these traces inside Socket.IO action.trace events. Set config.completionEvents: true in client.start to receive generated-text chunks.

Read these traces inside Socket.IO `action.trace` events. Set `config.completionEvents: true` in `client.start` to receive generated-text chunks.

Public socket clients do not receive `debug` traces. An authenticated connection is required for those diagnostics.

<a id="events-diagnostics" />

## `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` or `end` |
| `state` | `"start"` or `"content"` or `"end"` | yes | always |

“Required” above means required in every payload shape. A field can be required for a particular state or event even when it is not required in every shape; the schema below defines those conditions.

### completion payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "start"
          ],
          "x-enumNames": [
            "START"
          ]
        },
        "ai": {
          "type": "boolean"
        },
        "sourceUrls": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "url"
            ]
          }
        },
        "delay": {
          "type": "number"
        },
        "messageID": {
          "type": "string"
        },
        "ref": {
          "allOf": [
            {
              "$ref": "#/components/schemas/DebugTraceRef"
            }
          ]
        }
      },
      "required": [
        "state",
        "messageID"
      ]
    },
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "content"
          ],
          "x-enumNames": [
            "CONTENT"
          ]
        },
        "content": {
          "type": "string"
        },
        "messageID": {
          "type": "string"
        }
      },
      "required": [
        "state",
        "content"
      ]
    },
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "end"
          ],
          "x-enumNames": [
            "END"
          ]
        },
        "ref": {
          "allOf": [
            {
              "$ref": "#/components/schemas/DebugTraceRef"
            }
          ]
        },
        "sourceUrls": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "url"
            ]
          }
        },
        "messageID": {
          "type": "string"
        }
      },
      "required": [
        "state"
      ]
    }
  ],
  "components": {
    "schemas": {
      "DebugTraceRef": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/DebugTraceNodeRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAgentRef"
          },
          {
            "$ref": "#/components/schemas/DebugTracePromptRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAPIToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceFunctionRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceIntegrationToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceMcpIntegrationToolRef"
          }
        ]
      },
      "DebugTraceNodeRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "node"
            ],
            "x-enumNames": [
              "NODE"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "nodeType": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "nodeType",
          "diagramID"
        ]
      },
      "DebugTraceAgentRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agent"
            ],
            "x-enumNames": [
              "AGENT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "agentID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "agentName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "agentID",
          "diagramID"
        ]
      },
      "DebugTracePromptRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "prompt"
            ],
            "x-enumNames": [
              "PROMPT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "promptID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "promptID",
          "diagramID"
        ]
      },
      "DebugTraceAPIToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "api-tool"
            ],
            "x-enumNames": [
              "API_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "apiToolID": {
            "type": "string"
          },
          "apiToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "apiToolID"
        ]
      },
      "DebugTraceFunctionRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "function"
            ],
            "x-enumNames": [
              "FUNCTION"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "functionID": {
            "type": "string"
          },
          "functionName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "functionID"
        ]
      },
      "DebugTraceIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "integration-tool"
            ],
            "x-enumNames": [
              "INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          },
          "integrationToolName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "integrationToolName"
        ]
      },
      "DebugTraceMcpIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp-integration-tool"
            ],
            "x-enumNames": [
              "MCP_INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "mcpToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "mcpToolName"
        ]
      }
    }
  }
}
```

## `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 |

“Required” above means required in every payload shape. A field can be required for a particular state or event even when it is not required in every shape; the schema below defines those conditions.

### reasoning payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "start"
          ],
          "x-enumNames": [
            "START"
          ]
        }
      },
      "required": [
        "state"
      ]
    },
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "content"
          ],
          "x-enumNames": [
            "CONTENT"
          ]
        },
        "content": {
          "type": "string"
        }
      },
      "required": [
        "state",
        "content"
      ]
    },
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "end"
          ],
          "x-enumNames": [
            "END"
          ]
        }
      },
      "required": [
        "state"
      ]
    },
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "final"
          ],
          "x-enumNames": [
            "FINAL"
          ]
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "state",
        "message"
      ]
    }
  ]
}
```

## `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 |

“Required” above means required in every payload shape. A field can be required for a particular state or event even when it is not required in every shape; the schema below defines those conditions.

### tool-call payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "callID": {
          "type": "string"
        },
        "sound": {
          "type": "object",
          "properties": {
            "ref": {
              "type": "string"
            },
            "volume": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "required": [
            "ref"
          ]
        },
        "state": {
          "type": "string",
          "enum": [
            "start"
          ],
          "x-enumNames": [
            "START"
          ]
        }
      },
      "required": [
        "callID",
        "state"
      ]
    },
    {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "end"
          ],
          "x-enumNames": [
            "END"
          ]
        },
        "callID": {
          "type": "string"
        }
      },
      "required": [
        "state",
        "callID"
      ]
    }
  ]
}
```

## `knowledgeBase`

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

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

### knowledgeBase payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "chunks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "score": {
            "type": "number"
          },
          "documentID": {
            "type": "string"
          },
          "documentData": {}
        },
        "required": [
          "score",
          "documentID",
          "documentData"
        ]
      }
    },
    "query": {
      "type": "object",
      "properties": {
        "messages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string"
              },
              "content": {
                "type": "string"
              }
            },
            "required": [
              "role",
              "content"
            ]
          }
        },
        "output": {
          "nullable": true,
          "type": "string"
        }
      },
      "required": [
        "messages",
        "output"
      ]
    }
  },
  "required": [
    "chunks"
  ]
}
```

## `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` |

“Required” above means required in every payload shape. A field can be required for a particular state or event even when it is not required in every shape; the schema below defines those conditions.

### realtime-agent payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "START"
          ],
          "x-enumNames": [
            "START"
          ]
        },
        "input": {
          "type": "object",
          "properties": {
            "encoding": {
              "$ref": "#/components/schemas/AudioEncoding"
            },
            "sampleRate": {
              "type": "number"
            }
          },
          "required": [
            "encoding"
          ]
        },
        "output": {
          "type": "object",
          "properties": {
            "encoding": {
              "$ref": "#/components/schemas/AudioEncoding"
            },
            "sampleRate": {
              "type": "number"
            }
          },
          "required": [
            "encoding"
          ]
        }
      },
      "required": [
        "action",
        "input",
        "output"
      ]
    },
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "END"
          ],
          "x-enumNames": [
            "END"
          ]
        }
      },
      "required": [
        "action"
      ]
    },
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "INTERRUPTED"
          ],
          "x-enumNames": [
            "INTERRUPTED"
          ]
        }
      },
      "required": [
        "action"
      ]
    }
  ],
  "components": {
    "schemas": {
      "AudioEncoding": {
        "type": "string",
        "enum": [
          "audio/mp3",
          "audio/x-mulaw",
          "audio/pcm"
        ],
        "x-enumNames": [
          "MP_3",
          "MULAW",
          "PCM"
        ]
      }
    }
  }
}
```

## `block`

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

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

### block payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "blockID": {
      "type": "string"
    }
  },
  "required": [
    "blockID"
  ]
}
```

## `flow`

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

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

### flow payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "diagramID": {
      "type": "string"
    }
  },
  "required": [
    "diagramID"
  ]
}
```

## `path`

Reports which path the conversation took out of a step.

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

### path payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string"
    }
  },
  "required": [
    "path"
  ]
}
```

## `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 |

### debug payload schema

Look up nested fields, conditional requirements and constraints.

This is the OpenAPI payload schema, not an example response. Referenced definitions are included under `components.schemas`.

```json title="OpenAPI payload schema"
{
  "type": "object",
  "properties": {
    "ref": {
      "allOf": [
        {
          "$ref": "#/components/schemas/DebugTraceRef"
        }
      ]
    },
    "type": {
      "type": "string"
    },
    "level": {
      "allOf": [
        {
          "$ref": "#/components/schemas/DebugTraceLevel"
        }
      ]
    },
    "message": {
      "type": "string"
    },
    "context": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "message"
  ],
  "components": {
    "schemas": {
      "DebugTraceRef": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/DebugTraceNodeRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAgentRef"
          },
          {
            "$ref": "#/components/schemas/DebugTracePromptRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceAPIToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceFunctionRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceIntegrationToolRef"
          },
          {
            "$ref": "#/components/schemas/DebugTraceMcpIntegrationToolRef"
          }
        ]
      },
      "DebugTraceNodeRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "node"
            ],
            "x-enumNames": [
              "NODE"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "nodeType": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "nodeType",
          "diagramID"
        ]
      },
      "DebugTraceAgentRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agent"
            ],
            "x-enumNames": [
              "AGENT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "agentID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "agentName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "agentID",
          "diagramID"
        ]
      },
      "DebugTracePromptRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "prompt"
            ],
            "x-enumNames": [
              "PROMPT"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "promptID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "promptID",
          "diagramID"
        ]
      },
      "DebugTraceAPIToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "api-tool"
            ],
            "x-enumNames": [
              "API_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "apiToolID": {
            "type": "string"
          },
          "apiToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "apiToolID"
        ]
      },
      "DebugTraceFunctionRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "function"
            ],
            "x-enumNames": [
              "FUNCTION"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "functionID": {
            "type": "string"
          },
          "functionName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "functionID"
        ]
      },
      "DebugTraceIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "integration-tool"
            ],
            "x-enumNames": [
              "INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          },
          "integrationToolName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "integrationToolName"
        ]
      },
      "DebugTraceMcpIntegrationToolRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp-integration-tool"
            ],
            "x-enumNames": [
              "MCP_INTEGRATION_TOOL"
            ]
          },
          "nodeID": {
            "type": "string"
          },
          "diagramID": {
            "type": "string"
          },
          "mcpToolName": {
            "type": "string"
          },
          "diagramName": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "nodeID",
          "diagramID",
          "mcpToolName"
        ]
      },
      "DebugTraceLevel": {
        "type": "string",
        "enum": [
          "fatal",
          "error",
          "warn",
          "info",
          "debug"
        ],
        "x-enumNames": [
          "FATAL",
          "ERROR",
          "WARN",
          "INFO",
          "DEBUG"
        ]
      }
    }
  }
}
```

## `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.

## `Custom actions`

Custom action traces can be returned by functions and use the string you defined in Voiceflow as the `type` value. The `defaultPath` field indicates which path is set as the default: `0` for the first path, `1` for the second, and so on. Their payload is provided as JSON, as shown:

```json
{
  "type": "calendar",
  "time": 1720552033,
  "payload": {
    "today": 1700096585398
  },
  "defaultPath": 0,
  "paths": [
    { "event": { "type": "done" } },
    { "event": { "type": "cancel" } }
  ]
}
```
