> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/cookbooks/platform-admin/agents-and-evidence/investigate-a-run.md).

# Investigate an agent run

Fetch a conversation or execution record — not the full reconstructed trace.

`GET /agents/{agentId}/conversations/{conversationId}` returns a conversation record. This is the closest API equivalent to [Investigate an agent run](https://docs.uptiq.ai/platform-guides/admin/agents-and-evidence/investigate-an-agent-run) — **closest**, not equivalent. Read the caveat below before building on this.

## At a glance

| Item              | Value                                                  |
| ----------------- | ------------------------------------------------------ |
| ⚙️ Microservice   | `Agent Builder`                                        |
| 🌍 Environment    | `QA`                                                   |
| 🔗 Base URL       | `https://api-builder-qa.uptiq.dev/agent-builder`       |
| ⌘ Endpoint        | `GET /agents/{agentId}/conversations/{conversationId}` |
| 🔐 Authentication | User session token                                     |

{% columns %}
{% column %}

#### What it does

Returns a conversation record and its top-level execution metadata.
{% endcolumn %}

{% column %}

#### What it doesn't do

It doesn't return the full span-by-span execution trace.
{% endcolumn %}
{% endcolumns %}

{% hint style="danger" %}
**This is not Runs & Traces.** The UI's Trace/Graph/Summary views reconstruct a span-by-span breakdown — every LLM call, tool call, guardrail check and retrieval step, each with its own duration, tokens and cost, plus parent/child relationships between them. This endpoint returns the conversation record: the thread, its messages, and top-level metadata. It does not return the span tree. If your integration needs per-step timing or per-call token/cost data, there's no documented API for that today — use the UI.
{% endhint %}

## Before you start

Your session token needs a role with the **View agents** capability — an account API key will not work here, see the note under Request. Have the agent ID and conversation ID — find them from your own trigger response, a webhook payload, or `GET /agents/{agentId}/conversations` to list a agent's conversations.

{% hint style="warning" %}
**Agent Builder does not accept an account API key.** These calls authenticate with a **user session token** — `authorization: Bearer <token>` — not with `x-platform-key`. Verified against QA: `GET /agent-builder/agents` returns the same `404 ACCOUNT_NOT_FOUND` with an account key as it does with **no credential at all**, so the key is not being read. The session token is the credential the console itself uses, and it **expires one hour after issue**, which makes this recipe unsuitable for an unattended integration today. See [Authentication](https://gitlab.com/uptiq-inc-enterprise/development/documentation/platform-docs-repo/-/tree/main/api-references/qa/getting-started/authentication.md).
{% endhint %}

## Request

`GET /agents/{agentId}/conversations/{conversationId}`

Optional query: `executionId` — a conversation spans the main execution plus one per sub-agent invocation; pass this to read a specific sub-agent's turn instead of the main one.

## Code snippets

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://api-builder-qa.uptiq.dev/agent-builder/agents/AGENT_ID/conversations/CONVERSATION_ID" \
  -H "authorization: Bearer YOUR_SESSION_TOKEN"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const res = await fetch(
  `https://api-builder-qa.uptiq.dev/agent-builder/agents/${agentId}/conversations/${conversationId}`,
  {
    headers: {
      authorization: `Bearer ${process.env.UPTIQ_SESSION_TOKEN}`,
    },
  }
);
const { data } = await res.json();
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

res = requests.get(
    f"https://api-builder-qa.uptiq.dev/agent-builder/agents/{agent_id}/conversations/{conversation_id}",
    headers={
        "authorization": f"Bearer {os.environ['UPTIQ_SESSION_TOKEN']}",
    },
)
conversation = res.json()["data"]
```

{% endtab %}
{% endtabs %}

## Response

| Result     | What it means                                                                                                                         | Next action                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| ✅ `200 OK` | `data` contains the conversation, its metadata, and the execution ID. It doesn't include a span list or per-step token and cost data. | Use Runs & Traces for detailed trace analysis. |

## What to reach for instead

| You need                                              | Use                                                                                                            |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| The full span tree, per-step timing, tool-call detail | [Runs & Traces](https://docs.uptiq.ai/control-center/observe/runs-and-traces) in Control Center — no API today |
| What model served a call and its cost                 | Also Runs & Traces — the trace view's LLM spans report this                                                    |
| Whether an execution is still running                 | `GET /agents/{agentId}/executions/{executionId}/queue-status`                                                  |
| To stop it                                            | [Stop an agent](/cookbooks/platform-admin/agents-and-evidence/stop-an-agent.md)                                |

## Related

* [Investigate an agent run](https://docs.uptiq.ai/platform-guides/admin/agents-and-evidence/investigate-an-agent-run) — as a screen, with the full trace view
* [Stop an agent](/cookbooks/platform-admin/agents-and-evidence/stop-an-agent.md)
* [Review credit usage](/cookbooks/platform-admin/cost/find-what-used-credits.md)


---

# 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.uptiq.ai/cookbooks/platform-admin/agents-and-evidence/investigate-a-run.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.