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

# traces

```bash theme={null}
telnyx-acp traces alice
telnyx-acp traces alice run-1a2b3c
telnyx-acp traces alice --limit 5 --local
telnyx-acp invoke support-agent --conversation alice --trace "What's the weather in Paris?"
```

| Flag | Meaning |
| - | - |
| `--limit <n>` | How many of the newest runs to list, 20 by default, at most 50. |
| `--local` | Target the running `dev` instead of the deployed agent. |

`traces` shows what a conversation's runs did, step by step: each model call with its tokens and finish reason, each tool call with its outcome and the size of what it returned, the wait on an approval, and the reply's delivery, each with its start and duration. It runs in the project directory and reads the agent named in `agent.json`.

With a conversation alone, it lists that conversation's newest runs, one line each:

```text theme={null}
run run-7f3e…  invoke  completed  3.6 s  4,803 tok  1 tool call  2 m 05 s ago
run run-51aa…  sms  completed  1.2 s  1,904 tok  14 m 10 s ago
run run-0c9d…  invoke  failed  412 ms  HARNESS_PROVIDER_ERROR  31 m 40 s ago

the steps of one: telnyx-acp traces alice <run>
```

With a run id too, it shows that run as a waterfall, each step's time from the run's start on the left:

```text theme={null}
run run-7f3e…  invoke  completed  3.6 s  4,803 tok  1 tool call
├─     +6 ms  model  meta-llama/Llama-3.3-70B-Instruct  step 1  1.3 s  2,333 tok  tool-calls
├─    +1.3 s  tool  web_search                          ok  772 ms  408 B
├─    +2.1 s  model  meta-llama/Llama-3.3-70B-Instruct  step 2  1.5 s  2,470 tok  stop
└─    +3.6 s  deliver  invoke                           ok  0 ms
```

`invoke --trace` prints the same waterfall under the reply, and `/trace` inside [chat](https://developers.telnyx.com/docs/agents/cli/chat.md) prints it for the last turn. `invoke` and `chat` print the conversation and run they used. A run that failed is the one most worth reading: `invoke --trace` puts its trace on stderr ahead of the error. Against an agent deployed before traces existed, `invoke --trace` still prints the reply, with a warning in place of the trace.

## What a Trace Holds

| Step | Recorded |
| - | - |
| `run` | How the run came in (`invoke`, `chat`, `web`, `sms`, `email`, `eval`), its status, the failure code when it failed, its duration, the total tokens and the number of tool calls. |
| `model` | The model, the step number, input, output and total tokens, the finish reason, and for a streamed call the time to its first output. |
| `tool` | The tool, `ok`, `error` or `denied`, the size in bytes of what it returned, the provider's tool call id, and the harness's step name for it (`tool:web_search:0`). |
| `approval` | The tool waiting on the approval, `pending` while it waits, then the decision (`approved` or `denied`) and the time waited. An approval that expires or is canceled closes with the run. |
| `deliver` | The channel the reply went out on, whether it was delivered, and the attempt when it took more than one. |

A trace is metadata only. It never holds message text, a tool's arguments or its result, or an error's message: an error is recorded as its type, its code and its HTTP status, because a provider's error body or a tool's thrown message can carry a secret, such as a URL with a token. So a `browser_fill` value or an MCP server's secret header never reaches a trace.

Traces are kept in the conversation's own store, next to its messages: the newest 50 runs, at most 200 steps each, the oldest going first. Recording is best effort; a step that cannot be written is dropped with one log line, and the run goes on. Phone calls are not traced.

Under `--json`, a run's trace is `data.trace`, `{ run, spans }`, each span with `id`, `parent`, `kind`, `name`, `start` (epoch milliseconds), `durationMs`, `status` and `attrs`. The list is `data.runs`. [eval](https://developers.telnyx.com/docs/agents/cli/eval.md) reads the same trace for its `tool` and `noTool` checks.

> [!NOTE]
>
> Traces live in the agent and are read through the CLI only; they are not exported to an OpenTelemetry collector or a tracing service yet.