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

# Traces

> Reference for every trace type returned by the Conversations API.

Traces are the output of a Voiceflow agent. Each time your application sends an action to the [Conversations API](/api-reference/conversations-api/overview), the runtime returns an array of trace objects describing how the agent responded. A single turn often produces multiple traces in sequence - for example, a message followed by a set of buttons.

Every trace has a `type` field that identifies what it contains, a `payload` with the relevant data, and a `time` value recording when that trace was generated as a Unix timestamp. The `time` field can be useful for debugging: steps like message generation may take noticeably longer than simple text steps, and the timestamps make that visible.

## Trace types

### text

Returned by the [Message step](/documentation/build/steps/message), [Playbooks](/documentation/build/steps/playbook), and no-match and no-reply reprompts.

```json theme={null}
{
  "type": "text",
  "time": 1720552033,
  "payload": {
    "slate": {
      "id": "unique-id",
      "content": [
        {
          "children": [{ "text": "Hello there!" }]
        },
        {
          "children": [{ "text": "Select an option or ask me a question" }]
        }
      ],
      "messageDelayMilliseconds": 1000
    },
    "message": "Hello there!\n\nSelect an option or ask me a question",
    "delay": 1000
  }
}
```

The `message` field contains the plain text content. The `slate` field contains the same content in a structured rich-text format. `delay` controls the pause in milliseconds before the next trace is rendered, defaulting to 1000ms.

### cardV2

Returned by the [Card step](/documentation/build/steps/card). When a card contains buttons, each button's `request.type` is a Voiceflow-generated path ID. Pass that value as the `action.type` in your next request to advance the conversation along the corresponding path.

```json theme={null}
{
  "type": "cardV2",
  "time": 1720552033,
  "payload": {
    "title": "This is a Card title",
    "description": {
      "text": "This is a Card description",
      "slate": [
        {
          "children": [{ "text": "This is a Card description" }]
        }
      ]
    },
    "imageUrl": "https://assets-global.website-files.com/example-file.png",
    "buttons": [
      {
        "name": "Click for next step",
        "request": {
          "type": "path-generated-by-voiceflow",
          "payload": {
            "actions": [],
            "label": "Click for next step"
          }
        }
      }
    ]
  }
}
```

### carousel

Returned by the [Carousel step](/documentation/build/steps/card). The same button handling applies as with `cardV2` -  pass the button's `request.type` as the `action.type` in your next request.

```json theme={null}
{
  "type": "carousel",
  "time": 1720552033,
  "payload": {
    "layout": "Carousel",
    "cards": [
      {
        "id": "unique-id",
        "title": "This is a Carousel card title",
        "description": {
          "text": "This is a Carousel card description",
          "slate": [
            {
              "children": [{ "text": "This is a Carousel card description" }]
            }
          ]
        },
        "imageUrl": "https://assets-global.website-files.com/example-file.png",
        "buttons": [
          {
            "name": "Click for next step",
            "request": {
              "type": "path-generated-by-voiceflow",
              "payload": {
                "label": "Click for next step",
                "actions": []
              }
            }
          }
        ]
      }
    ]
  }
}
```

### choice

Returned by the [Condition step](/documentation/build/steps/condition) and [Playbooks](/documentation/build/playbooks) or the Agent when the [buttons system tool](/documentation/build/tools/system-tools) is enabled. How you handle a choice trace depends on what's in each button's `request.type`.

#### Path buttons

When buttons are connected to specific paths in your workflow, `request.type` is a Voiceflow-generated path ID. Pass it directly as `action.type` in your next request. The `label` field is optional — if included, its value is set as the `last_utterance` variable.

```json theme={null}
{
  "type": "choice",
  "time": 1753108390491,
  "payload": {
    "buttons": [
      {
        "name": "Order coffee",
        "request": {
          "type": "path-cmd906pp400433b7ujbsbiotm",
          "payload": {
            "label": "Order coffee"
          }
        }
      }
    ]
  }
}
```

To handle this button click, send:

```json theme={null}
{
  "action": {
    "type": "path-cmd906pp400433b7ujbsbiotm",
    "payload": {
      "label": "Order coffee"
    }
  }
}
```

#### Agent-generated buttons

When the [buttons system tool](/documentation/build/tools/system-tools) is enabled on Playbook or on the Agent, the agent may dynamically generate buttons. These use `request.type: "text"` and simulate raw user input rather than triggering a specific path:

```json theme={null}
{
  "type": "choice",
  "time": 1753110520157,
  "payload": {
    "buttons": [
      {
        "name": "Check account balance",
        "request": {
          "type": "text",
          "payload": "Check account balance"
        }
      }
    ]
  }
}
```

### no-reply

Returned when a No Reply timeout is active. The `timeout` value is in seconds.

```json theme={null}
{
  "type": "no-reply",
  "time": 1720552033,
  "payload": {
    "timeout": 10
  }
}
```

If the user doesn't respond within the timeout window, send a `no-reply` action to retrieve the configured reprompt:

```json theme={null}
{
  "action": {
    "type": "no-reply"
  }
}
```

### 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 theme={null}
{
  "type": "calendar",
  "time": 1720552033,
  "payload": {
    "today": 1700096585398
  },
  "defaultPath": 0,
  "paths": [
    { "event": { "type": "done" } },
    { "event": { "type": "cancel" } }
  ]
}
```

### end

Returned when the conversation reaches an End step. On receiving this trace, your application should treat the session as closed.

```json theme={null}
{
  "type": "end",
  "time": 1720552033,
  "payload": null
}
```

## Completion event traces

When using the streaming endpoint, you may also encounter `completion-start`, `completion-continue`, and `completion-end` traces. These mark the lifecycle of an AI generation event within a stream.