Repository Public
1# Tracing23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45A **session** keeps your agent's conversation and work together. A session can contain several **turns**, each a cycle of work. A **trace** shows the steps within one turn: model responses, tool calls, and work delegated to other agents.67The [tracing dashboard](https://platform.openai.com/logs?api=agents) shows what your agent did, including each step's recorded inputs, outputs, duration, and status.89For session status, live events, saved output, and usage through the API, start with [Observability](https://developers.openai.com/api/docs/guides/agents-api/observability).1011Tracing is enabled by default for new sessions. You can inspect traces in the dashboard or export them through the API.1213## Open a trace14151. Open [Logs → Agents](https://platform.openai.com/logs?api=agents) and select the project where you ran your agent.162. Find your session with **Search logs**. Use **Add filter** to filter by model, status, or date.173. Select the session to open its timeline and list of turns.184. Expand a turn, then select a step in the timeline or event list to see its details.1920The session summary shows its status, model, start time, last activity, number of turns, and recorded token usage.2122## Read a trace2324Start with the session, then work your way into a turn:25261. **Session:** each entry in Logs → Agents is a session. Open it to see its timeline and list of turns. For example, a user can ask about an order, then ask a follow-up question in the same session.272. **Turn:** expand a turn to see the work done during that cycle. One turn can include several model responses and tool calls. A follow-up message sent after the turn finishes starts another turn in the same session.283. **Steps within the turn:** the trace groups model responses and tool calls under the root agent or the subagent that performed them. Each recorded step is called a **span**.2930Select a span to see its status, duration, start and end times, and recorded data:3132| Select | What you can inspect |33| ------------------------------------------------ | ------------------------------------------------------------------------------ |34| [**Agent**](#agent) | The agent's details, instructions, and recorded token usage |35| [**Generation**](#generation) (a model response) | The recorded input and output for a model response |36| [**Tool**](#tool) | Which tool was called, the arguments sent to it, and the result when available |3738### Agent3940An agent span groups the work done by the **root agent** or a **subagent**: another agent asked to handle part of the task. Model responses and tool calls appear under the agent that performed them.4142The details panel shows:4344- **Agent type:** root agent (`root`) or subagent (`subagent`).45- **Agent:** its ID, name, model, and instructions when recorded.46- **Usage:** that agent's recorded token counts. These counts cover the agent itself; they do not include its subagents.47- **Duration** and **Outcome status:** how long the recorded work took and whether it completed, failed, or is incomplete.4849### Generation5051A generation span groups recorded model inputs and outputs. Each turn can have several generations.5253During model inference, the model reads its input and produces a response. That response can request a tool. After the tool returns, the model can produce another response in a new generation.5455- **Input:** recorded inputs associated with that response, such as a user message or a tool result.56- **Output:** recorded items produced by the model, such as answer text or a tool call.57- **Model:** the model used for the response, when recorded.5859### Tool6061A tool span describes a tool call and its recorded result.6263Tool spans include calls to your functions and to tools on **MCP (Model Context Protocol)** servers. Web searches and command execution can also appear as tool spans.6465- **Call:** the tool request, including the tool name and arguments when present.66- **Result:** the recorded response from the tool, when available.67- **Outcome status** and **Error:** the recorded outcome and error details, when present.6869For an MCP tool call, **Call** contains the server label (`server_label`), tool name (`name`), and arguments (`arguments`). Its response and error are recorded there as `output` and `error`, when available. The separate **Result** panel can be empty because the MCP response is stored in **Call**.7071## Timing and status7273The timeline shows the order of the steps and which ones overlap. **Zoom in** shows shorter steps in more detail. **Fit timeline** shows the whole session.7475Each span shows its duration and outcome status. Failed spans can also include recorded error details.7677An agent span's duration includes its child steps. Steps can overlap: two subagents running together for 10 seconds cover about 10 seconds of elapsed time.7879## Token usage8081**Tokens** in the session summary shows session usage. **Usage** in an agent span shows that agent's recorded token counts.8283Usage can arrive after the turn ends. A blank value or `null` means the count is unknown. It does not mean the agent used zero tokens. Counts can change as more usage becomes available and are not a final bill.8485## When traces are ready8687Traces are built after a turn ends. The agent's answer can appear before its trace or token usage is ready.8889[Live session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events) show progress while the agent is still working.9091## Export session traces9293Download session traces to inspect them in another tracing tool. The endpoint `GET /v1/agents/sessions/{session_id}/traces` returns a page of traces containing OpenTelemetry Protocol (OTLP) JSON.9495Trace export must be enabled for your organization. Use an API key for the96 session's project with either traces read permission (`api.traces.read`) or97 the broader agents read permission (`api.agents.read`).9899Set `OPENAI_API_KEY` and replace `sess_123` with your session ID. This example uses cURL and `jq` to save one page as `traces.otlp.json`:100101Download a page of session traces102103```bash104curl --fail-with-body \105 "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \106 -H "Authorization: Bearer $OPENAI_API_KEY" \107 -H "OpenAI-Beta: agents=v1" \108 --output trace-page.json && \109jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.json110```111112113The command combines the traces from that page into one OTLP payload. Send it to your tracing provider's OTLP/HTTP endpoint using the provider's authentication.114115To export the whole session, check `trace-page.json`. When `has_more` is `true`, request the next page with `last_id` as `after`, keeping the same `order`. Save or upload each page before fetching the next, and repeat until `has_more` is `false`.116117Exports include only traces available when you make each request. For a historical export, wait for the session's turns to finish and allow time for traces to appear. Exporting does not set up automatic delivery of future traces.118119### Export traces for an agent120121To export traces across an agent's sessions, first [list sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#find-sessions) with the `agent_id` filter. Replace `agent_123` with your agent's ID:122123Find sessions for an agent124125```bash126curl --fail-with-body \127 "https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \128 -H "Authorization: Bearer $OPENAI_API_KEY" \129 -H "OpenAI-Beta: agents=v1"130```1311321331. For each session in `data`, use its `id` to export every page of session traces as described above.1342. When the session list has `has_more: true`, pass that list's `last_id` as `after` to fetch the next page. Keep the same `agent_id` and `order`.1353. Repeat until the session list has `has_more: false`.136137The filter matches the session's root agent. Keep the session-list cursor separate from each session's trace cursor.138139## Example: One turn with two subagents140141This example is based on a recorded session. The root agent calls an MCP tool while two subagents run a command and fetch documents. The subagent names are simplified below; the counts and durations come from the recorded trace.142143### Session and turn144145The session header shows **1 turn**, **10 tool calls**, and **252,468 tokens**. The session status is **Idle**, and **Turn 1** is **Completed** with a duration of **1m 37s**.146147Expanding the turn reveals the root agent and its child steps. The trace contains **3 agent spans** (the root and two subagents), **11 generation spans**, and **10 tool spans**.148149This tree groups repeated generations and tool calls together. It shows parent relationships; the timeline shows when each step ran.150151```text152Session: Idle153└── Turn 1: Completed 1m 37s154 └── Root agent 1m 37s155 ├── 6 generations156 ├── 2 tools: spawn_agent_call157 ├── Subagent A 24s158 │ ├── 2 generations159 │ └── Tool: command_execution 2s160 ├── Subagent B 21s161 │ ├── 3 generations162 │ ├── 2 tools: notion.fetch 2s each163 │ └── Tool: send_input_call 0ms164 ├── Tool: demo_capability_probe 87ms165 └── 3 tools: wait_for_agents_call166```167168### Model work and delegation169170The root agent's first **Generation** includes the user's message in **Input**. Its **Output** contains messages and two `spawn_agent_call` items. Those calls also appear as **Tool** spans, and the resulting subagents appear as **Agent** spans under the root.171172Subagent A has its own generations and a `command_execution` tool call. Subagent B has three generations, two `notion.fetch` MCP calls, and a `send_input_call`. Their model responses and tools belong to their respective subagent spans.173174The root agent also has three `wait_for_agents_call` tool spans. Its final generation contains a message and has a recorded duration of **6s**.175176### An MCP tool call177178The root agent's `demo_capability_probe` span is a completed **Tool** span with a duration of **87ms**. Its **Tool type** is `mcp_call`.179180The **Call** panel includes these fields:181182```json183{184 "type": "mcp_call",185 "server_label": "demo_local",186 "name": "demo_capability_probe",187 "status": "completed"188}189```190191This excerpt shows part of the recorded call. The same panel contains its `arguments` and the MCP response in `output`. The separate **Result** panel is `null`. The span's **Parent span** points to the root agent.192193Subagent B's two `notion.fetch` spans have the same structure: `mcp_call` as the tool type, the MCP response in **Call**, and the subagent as their parent.194195### Timing and usage in this session196197The two subagent spans overlap on the timeline. Subagent A takes **24s** and Subagent B takes **21s**, both within the root agent's **1m 37s** span. The dashboard rounds these displayed durations.198199The **Usage** panel on each agent span shows its own recorded token counts:200201| Agent | Input tokens | Output tokens | Total tokens |202| ---------- | ------------ | ------------- | ------------ |203| Root agent | 126,390 | 1,567 | 127,957 |204| Subagent A | 34,075 | 465 | 34,540 |205| Subagent B | 89,304 | 667 | 89,971 |206207In this recorded session, the three agent totals add up to the **252,468 tokens** shown in the session header.