> ## Documentation Index > Fetch the complete documentation index at: https://docs.os.meetluno.ai/llms.txt > Use this file to discover all available pages before exploring further. # Debug with traces > See every model call and tool call of an agent answer, with inputs, outputs, tokens and timing. When an agent answers badly, the reply alone rarely tells you why. A **trace** shows what happened inside one answer, in order: | Span | What it records | | - | - | | **Turn** | The whole answer: the message, the reply, total tokens and cost, how long it took, and the error if it failed | | **Model** | One model call: the model id, the system prompt and messages it was sent, the text and tool calls it answered, tokens in and out, cost when the model has known pricing, latency, the provider's finish reason, and the error of a failed call (including attempts before a retry or a fallback model) | | **Tool** | One tool call: the tool name, its input, its output or error, and how long it ran. Spans a tool opens (a subagent, a workflow run) nest under it | Traces are stored in Luno OS's own database, the same way in every environment. Nothing to configure and no third-party service involved. ## Open a trace **Luno Builder and the Luno assistant.** Under each finished answer in the chat, select **View trace** (the tree icon). A panel opens with the answer's spans as a tree. Select a span to expand its input, output and error. **Your project's agents.** Open **Runs** (`/history`), filter **Type** to **Agent**, select a run and open the **Trace** tab to see the spans, their timing and tokens. Agent steps of a workflow show the same spans in the step's **Trace** tab. Inputs and outputs are left out of those views to keep them fast; read them from the terminal (below), or ask for the whole session's spans with `payloads` (`include=trace,payloads`): ```bash theme={null} luno agents sessions get support --include trace,payloads ``` ## Read traces from the terminal `luno traces` reads the same traces with your CLI login or `LUNO_API_KEY`, so you, or a coding agent like Claude Code, can debug an agent without opening the web app. Each answer is one **turn** with a run id. ```bash theme={null} # Your latest Luno Builder turns (only the linked or --project Space's, when there is one) luno traces list # Failed Luno assistant answers of the last day luno traces list --kind assistant --since 24h --errors # One project agent session's turns luno --project support traces list --agent triage --session # One turn as a tree: kind, name, model, tokens, cost, duration, status, and cut inputs/outputs luno traces get --session luno --project support traces get --session --agent triage --max-chars 2000 # The raw spans as JSON (full payloads; --no-payloads leaves them out) luno traces get --session --json ``` `--kind` is `builder` (the default), `assistant`, or `agent` (implied by `--agent`, and needs the project: `--project` or the linked one). Without `--session`, `traces list` reads the turns of your most recently updated sessions (`--limit`, default 10). The API behind it: `GET /api/platform-agent/sessions/:id/traces[/:runId]` and `GET /api/luno-assistant/sessions/:id/traces[/:runId]` for Builder and assistant chats, `GET /api/projects/:projectId/agents/:slug/sessions/:id/traces[/:runId]` for project agents. The list returns each turn's run id, message ids, timing, status, model, tokens and cost; one turn returns its spans with inputs and outputs. In the SDK: `platformAgent.listTraces` / `getTrace`, `lunoAssistant.listTraces` / `getTrace`, and `client.agents.listTraces(agent, sessionId)` / `getTrace(agent, sessionId, runId)`. ## Debug from a coding agent (MCP) The [Luno OS MCP server](https://docs.os.meetluno.ai/build-with-ai/mcp-for-agents.md) has three read-only tools for this, with the same access as the web app: | Tool | What it returns | | - | - | | `list_agent_sessions` | Sessions you can read: `kind` `builder` or `assistant` (your chats; `scope: "team"` for every member's, org owners and admins only) or `agent` (a project agent's sessions, with `project` and `agent`). Filters: `since`, `limit`. | | `list_traces` | A session's turns: run id, message ids, timing, status, model, tokens, cost. | | `get_trace` | One turn's spans. `maxChars` cuts each input and output (default 2000), `payloads: false` leaves them out. | To connect Claude Code, add the server and sign in once (the MCP server uses OAuth, not API keys): ```bash theme={null} claude mcp add --transport http luno https://api.meetluno.ai/v1/mcp ``` Then run `/mcp` in Claude Code and authenticate `luno`. Other clients: see [Connect a client](https://docs.os.meetluno.ai/build-with-ai/mcp-for-agents.md#connect-a-client). For headless use with an API key (CI, scripts), use the `luno traces` commands with `LUNO_API_KEY` instead. ## Who can see a trace Exactly who can see the chat: * A Builder or assistant trace is visible to the person who owns that chat. Organization owners and admins can also read the traces of members' chats (read-only), and each time they open another member's chat or its traces the audit log records it (`chat_session.builder_viewed` / `chat_session.assistant_viewed`). An API key pinned to a project never reads other members' chats. * A project agent's trace follows the session's visibility: the person who started the session and project admins, among those on the agent's access list (see [Agent runs](https://docs.os.meetluno.ai/learn/logs/agent-runs.md)). ## What is stored, and for how long * Inputs and outputs are scrubbed before they are stored: values under secret-looking keys (`token`, `password`, `apiKey`, …) and credential-shaped strings (bearer tokens, API keys, passwords in URLs) are replaced with `[Filtered]`. * Each input and output is capped at about 32 KB. A long conversation keeps its newest messages (the input says how many older ones were left out); attachments are recorded by type and name, never their bytes. * Inputs and outputs are deleted after **30 days** on every plan. The spans themselves (timing, tokens, status) follow your plan's log retention. * Owner-data runs (sealed sessions) never store readable inputs or outputs in a trace. ## Read a trace * **Slow answer?** Compare durations: model latency versus the tool that took most of the time. * **Wrong tool, or wrong arguments?** Expand the model call before the tool call: its output shows exactly which tool it asked for and with what input, and its input shows what it knew at that point. * **Ignored an instruction?** Check the model call's input: the system prompt and messages it actually received (after context compaction). * **Failed answer?** The failed span is marked red; its error says whether the model call or a tool failed. A failed model call followed by a successful one means a retry or a fallback model answered. * **Expensive answer?** Tokens and cost are shown per model call and totaled on the turn. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.