> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/teams/traces.md).

# Team Execution Records

View every team execution—which conversation it belongs to, which Agents it passes through, and each Agent's Token usage and duration—and filter by conversation to see all executions for the same conv

Teams automatically hand off and delegate work between Agents without users noticing. **Execution Traces** let you look back at which Agents each conversation actually passed through and how many resources each used, so you can verify that the team divides work as expected, troubleshoot issues, and optimize performance.

## <mark style="color:blue;">1. View execution traces</mark> <a href="#view-traces" id="view-traces"></a>

Switch to the **Execution Traces** view on the team page to list every execution for this team. A trace is created each time a user sends a message to the team. Each trace includes:

| Field            | Description                                                                                                                                                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trace ID**     | The unique identifier for this execution.                                                                                                                                                                                          |
| **Conversation** | The conversation this execution belongs to, shown by its title. Click the title to open All Conversations and view the full conversation.                                                                                          |
| **Status**       | Running, Completed, Failed, Timed Out, or Awaiting Reply. Awaiting Reply means the team paused at a connection with “Wait for the user's reply before continuing” enabled; see [Traces awaiting a reply](#waiting-for-user) below. |
| **Iterations**   | The total number of interactions between Agents during this execution.                                                                                                                                                             |
| **Tokens**       | Total Token usage for this execution (input in / output out).                                                                                                                                                                      |
| **Duration**     | Total time from receiving the message to completing the reply.                                                                                                                                                                     |
| **Created At**   | The time of this execution. Click the column header to switch between oldest-first and newest-first sorting; the default is newest first.                                                                                          |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-823fb555400af54c89c714cb0a7639da6e51acf8%2Fteams-traces-list.png?alt=media" alt="Team execution trace list with Trace ID, Conversation, Status, Iterations, Tokens, and Actions columns"><figcaption><p>Execution traces: each trace shows its conversation title, making it easy to identify traces from the same conversation</p></figcaption></figure>

{% hint style="info" %}
**Can't click a conversation title?** You need access to Conversation History for titles to appear as links. Without permission, titles appear as plain text (hover over a title to see why).
{% endhint %}

## <mark style="color:blue;">2. Filter execution traces by conversation</mark> <a href="#filter-by-conversation" id="filter-by-conversation"></a>

A conversation usually contains several messages, each generating its own execution trace. To focus on one conversation, list only the traces that belong to it.

### 1. Filter by this conversation <a href="#apply-conversation-filter" id="apply-conversation-filter"></a>

In the Actions column on the right of the trace you want to inspect, click the funnel icon <mark style="color:blue;">Filter by This Conversation</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-af8dbc17a102a15908d4afd228598b5f3c4180e8%2Fteams-traces-filter-by-conversation.png?alt=media" alt="Funnel icon in the Actions column with the tooltip Filter by This Conversation"><figcaption><p>Click the Filter by This Conversation funnel icon on the right of a trace</p></figcaption></figure>

### 2. View filtered results <a href="#filtered-result" id="filtered-result"></a>

A banner above the list reads **Showing only traces for conversation “…”**, and the list contains only traces for that conversation. The filter remains active when you paginate or sort. The funnel icons for these traces turn gray and show “Already viewing traces for this conversation” on hover.

To return to the full list, click <mark style="color:blue;">Clear</mark> or close (×) on the right of the banner.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-09594aef5f67452c4713db76671ae7d12e207195%2Fteams-traces-filtered.png?alt=media" alt="A banner indicates that only traces for one conversation are shown, with two traces from that conversation remaining in the list"><figcaption><p>After filtering: the banner identifies the current conversation, and only its traces remain in the list</p></figcaption></figure>

### Example: identify which Agent replied in a customer complaint conversation <a href="#example-complaint-review" id="example-complaint-review"></a>

A support manager receives feedback that “the return instructions are unclear” and wants to identify which Agent in the team handled each reply in that conversation:

1. Find any trace for the conversation in Execution Traces and click <mark style="color:blue;">Filter by This Conversation</mark> to show only its traces.
2. Expand each trace and check the Agent names on the step cards: the first message was handled by Demo – Support Routing Assistant and then handed off to Demo – Returns and Exchanges Assistant; subsequent follow-up questions were answered directly by Demo – Returns and Exchanges Assistant.
3. Click the title in the Conversation column to open the original conversation and compare the actual replies. Once you identify Demo – Returns and Exchanges Assistant as the source of the issue, return to AI Assistants to adjust its settings.

## <mark style="color:blue;">3. Expand step details</mark> <a href="#step-detail" id="step-detail"></a>

Click the **+** on the left of a trace (or click the row itself) to expand it and see **which Agent nodes this execution passed through, in order**. Each step has a card:

| Item                     | Description                                                                                                                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Step number and name** | Shown as “#Number · Name,” such as “#1 · Demo – Support Routing Assistant,” so you can immediately identify which Agent in the team handled the step.                                                                                                  |
| **Interaction type**     | After the name, shows how this Agent was actually invoked in this turn: **Handoff** or **Delegation**. Not shown for the first Agent handling the turn. For connections set to Automatic, this shows the handoff or delegation that actually occurred. |
| **Input**                | What this Agent received; see [Input and output content](#step-summaries) below.                                                                                                                                                                       |
| **Output**               | This Agent's final reply in this turn; see [Input and output content](#step-summaries) below.                                                                                                                                                          |
| **Token usage**          | The right side of the card shows input/output Tokens for this step (`in` / `out`). Some steps also show duration, helping you see which Agent accounts for the cost.                                                                                   |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e111f5b6779648bae94e72680649237008039af1%2Fteams-trace-step-summaries.png?alt=media" alt="An expanded trace with three step cards: #1 · docs-line Demo (Fictional) Step Details Team has input only; #2 · docs-line Demo (Fictional) Returns and Exchanges Assistant · Handoff shows the handoff reason as input and a reply as output; #3 · docs-line Demo (Fictional) Order Lookup Assistant · Delegation shows the delegated task as input and the returned result as output"><figcaption><p>Step details: Handoff or Delegation appears after the name, with the step's input and output below</p></figcaption></figure>

### Input and output content <a href="#step-summaries" id="step-summaries"></a>

Input and output depend on how the Agent entered this turn:

| Step                                                                                                                                           | Input                                                                                    | Output                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| The first Agent handling this turn (usually the entry Agent; if a handoff occurred in the previous turn, the Agent currently serving the user) | The message the user sent this time                                                      | Its final reply in this turn                                            |
| Interaction type is Handoff                                                                                                                    | The handoff reason: the previous Agent's explanation of why it handed over to this Agent | Its final reply in this turn                                            |
| Interaction type is Delegation                                                                                                                 | The delegated task                                                                       | The result it returns to the delegating Agent after completing the task |

* Input and output are each limited to 500 characters; additional content is truncated with “…”.
* Empty fields are hidden. For example, if the entry Agent only hands off the conversation without replying, its step card shows Input only.
* This content has been recorded only since the feature launched; older traces are not backfilled.

{% hint style="warning" %}
**When output controls are configured, step cards retain only the user message.** If the team's entry Agent (with the same name as the team) has a [Hook](/maiagent-user-guide/en/build/hook.md) at the After AI Response Generation interception point, or AWS Guardrails is enabled, these controls apply only to the team's final response to the user and do not pass through step cards. To avoid storing unprocessed model output in execution traces, step cards for these teams show only the interaction type and the user message received by the first Agent. Handoff reasons, delegated tasks, and all Output fields remain blank.
{% endhint %}

{% hint style="info" %}
**Who can see step content?** Input and output contain user messages and Agent replies, so a role must have [Team Permissions](/maiagent-user-guide/en/org/roles/role-permission.md) to read either the trace list or an individual trace. Organization owners are exempt from this requirement.
{% endhint %}

### Example: find where an exchange request gets stuck <a href="#example-step-summaries" id="example-step-summaries"></a>

An e-commerce support manager notices that customers asking about exchanges are often asked for a customer ID and wants to know which Agent requests it:

1. In Execution Traces, expand the trace for a customer's exchange inquiry. Three step cards appear: “#1 · docs-line Demo (Fictional) Step Details Team,” “#2 · docs-line Demo (Fictional) Returns and Exchanges Assistant · Handoff,” and “#3 · docs-line Demo (Fictional) Order Lookup Assistant · Delegation.”
2. The Input for #2 is the handoff reason written by the entry Agent, confirming that the conversation was handed to the correct Agent.
3. The Input for #3 is the task delegated by the returns and exchanges assistant, “Please check the shipping status of fictional order A1001.” Its Output is the order lookup assistant's returned response, “Please provide the customer ID (userId) so I can check the shipping status of order A1001.”
4. The manager now knows that the order lookup assistant could not look up the order because it lacked the customer ID, and can return to AI Assistants to adjust its settings without comparing the entire conversation message by message.

### Traces awaiting a reply <a href="#waiting-for-user" id="waiting-for-user"></a>

When the team reaches a connection with [Wait for the user's reply before continuing](/maiagent-user-guide/en/build/teams/setup.md#wait-for-reply-rules) enabled, the current turn stops after the source Agent replies, and the trace status becomes **Awaiting Reply**. This is a normal completion, not a failure. Expanding the trace reveals an additional information card below the step cards:

* **Waiting for the user's reply:** This turn has paused here, waiting for the user's next message.
* **Continue after reply with: ○○:** Which Agent will continue after the user replies. The name shown is the Agent's name at the time execution paused; it stays the same even if the Agent is later renamed.

After the user replies, the next turn generates a separate trace, with step cards starting from the target Agent.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9139f96ee3307d293980fe3d180361de3214cc32%2Fteams-traces-waiting-for-user.png?alt=media" alt="An expanded trace with Awaiting Reply status, step card #1 · docs-line Demo (Fictional) Support Routing Assistant, and an information card below showing Waiting for the user&#x27;s reply and Continue after reply with: docs-line Demo (Fictional) Returns and Exchanges Assistant"><figcaption><p>A trace awaiting a reply: expand it to see which Agent paused and who will continue after the user's reply</p></figcaption></figure>

{% hint style="info" %}
**Can I retrieve execution traces through the API?** Currently, traces are available only in the console's **Execution Traces** view and are not yet included in the public [API documentation](https://docs.maiagent.ai/api). Contact your MaiAgent representative if you need to export them for analysis.
{% endhint %}

{% hint style="info" %}
**No traces visible?** Execution traces are created only after a conversation actually triggers the team. If the list is empty, send a few messages to the team through its conversation platform, then return to check.
{% endhint %}

## <mark style="color:blue;">4. Use traces to optimize your team</mark> <a href="#optimize" id="optimize"></a>

* **Unexpected routing:** Use the Agent names on step cards and handoff reasons in Input to identify questions sent to the wrong Agent. Return to [Canvas Orchestration](/maiagent-user-guide/en/build/teams/setup.md#compose-canvas) and adjust the connection's Trigger Condition Description to clarify when that connection should be used.
* **High iteration counts or long durations:** Agents may be handing work back and forth too often. Check for unnecessary connections, or adjust the team's Maximum Iterations and individual node settings.
* **Costs concentrated on one Agent:** Compare Token usage across step cards to identify the Agent consuming the most Tokens. Consider switching it to a lighter model or narrowing its knowledge base and tool scope.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/teams/traces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.