> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Diagnose conversations

Diagnose conversations [#diagnose-conversations]

Pick chats the agent already had, launch a diagnosis with checks, and read its failures and fixes.

Endpoints [#endpoints]

All paths start with `/api/v1/diagnostics` and need `X-Space-Slug`.

| Method   | URL                                        | Does                                                                                                           | Auth          |
| -------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------- |
| `GET`    | `/agents/{agent_id}/chats/`                | The agent's chats the key's owner can open                                                                     | Key or bearer |
| `POST`   | `/agents/{agent_id}/runs/`                 | Launch a diagnosis; `201`; billed                                                                              | Key or bearer |
| `GET`    | `/agents/{agent_id}/runs/`                 | The agent's diagnoses                                                                                          | Key or bearer |
| `GET`    | `/agents/{agent_id}/runs/{run_id}/`        | Status and conclusions                                                                                         | Key or bearer |
| `POST`   | `/agents/{agent_id}/runs/{run_id}/cancel/` | Stop it; `202`                                                                                                 | Key or bearer |
| `DELETE` | `/agents/{agent_id}/runs/{run_id}/`        | Delete it; `204`                                                                                               | Key or bearer |
| `GET`    | `/runs/`                                   | Every diagnosis in the workspace, newest first; `?kit_id=` narrows to one environment                          | Key or bearer |
| `POST`   | `/compare/`                                | Compare 2–20 diagnoses of the same agent and environment: `{"run_ids"}`; `422` for runs without an environment | Key or bearer |

Request fields [#request-fields]

| Field               | Rule                                                                                                                          |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `trace_ids`         | Required, at least one: IDs of the caller's own chats with this agent in this workspace, from `GET /agents/{agent_id}/chats/` |
| `kit_id`            | Use the checks of an environment of this agent; replaces `eval_assertions`                                                    |
| `eval_assertions`   | Checks of your own, shaped as in [Build an environment](./environments)                                                       |
| `diagnostic_effort` | `low`, `medium` (default) or `high`                                                                                           |

Diagnose an agent [#diagnose-an-agent]

1. List the agent's chats and pick the ones to read; a chat started through `run-stream` is the one whose `thread_id` is the `threadId` you sent:

   ```bash
   curl "$CENTRAL_HUB_URL/api/v1/diagnostics/agents/42/chats/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"
   ```

2. Launch the diagnosis:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/diagnostics/agents/42/runs/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"trace_ids": [678, 679], "kit_id": 7, "diagnostic_effort": "low"}'
   ```

3. Poll `GET /agents/42/runs/{id}/` until `status` is `completed`, `failed` or `cancelled`; on the way it passes through `pending`, `loading`, `scoring`, `analyzing` and `optimizing`, and `cancelling` after a cancel.

4. Read the conclusions in the same response; see [Result fields](#result-fields). Read a diagnosed chat with `GET /agents/42/chats/{chat_id}/`, using an ID from `trace_ids`.

Result fields [#result-fields]

| Field                        | Holds                                                                                                                                                           |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `score`, `diagnosis_summary` | The result in one number and one paragraph                                                                                                                      |
| `per_assertion_results[]`    | `{id, label, passed, total}`: how each check did across the diagnosed chats                                                                                     |
| `failure_categories[]`       | `{category, severity, fix_level, description, count, examples}`: patterns the analysis found, including inefficient successes, in how many chats, with examples |
| `recommendations[]`          | `{priority, title, fix_level, description, suggested}`: the fix to make                                                                                         |

Troubleshooting [#troubleshooting]

| Response                                           | Cause                                                                                                                         | Fix                                                                    |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `404` `Trace(s) not found: […]`                    | A `trace_ids` entry is not the caller's own chat with this agent in this workspace; chats shared with the caller do not count | Use chats the caller started                                           |
| `404` `Diagnostic kit not found`                   | `kit_id` is wrong or not visible                                                                                              | Check it with `GET /kits/`                                             |
| `422` `This environment belongs to another agent.` | `kit_id` names another agent's environment                                                                                    | Use an environment of this agent, or of the agent it was promoted from |
| `422` `Unsupported assertion type(s): …`           | A check in `eval_assertions` has an unknown `type`                                                                            | Use a type from `GET /check-catalog/`                                  |