> ## Documentation Index
> Fetch the complete documentation index at: https://vizmaxxing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostics API: Submit and Analyze Agent Behavior

> REST API endpoints for submitting agent behavior for real-time diagnostic analysis and retrieving detailed behavioral pattern reports.

Diagnostics are lightweight, **synchronous** analysis runs designed for quick behavioral checks. Unlike [Sessions](https://vizmaxxing.com/api/sessions.md) — which queue asynchronous deep-analysis jobs and are suited to large or complex behavior logs — a diagnostic call returns findings immediately in the response body. Use diagnostics when you want a fast, inline health check: for example, in a CI pipeline, at the end of a short test conversation, or during development.

The trade-off is scope: diagnostics are optimized for logs up to 50 turns. For longer traces or when you need the full suite of pattern detections and a narrative report, use the Sessions API instead.

***

## POST /diagnostics

Submit an agent behavior log for synchronous analysis. The response contains findings, a health score, and timing metadata returned as soon as analysis completes — no polling required.

> [!NOTE]
>
> For behavior logs longer than **50 turns**, use the [Sessions API](https://vizmaxxing.com/api/sessions.md) for asynchronous processing. Submitting a log with more than 50 turns to this endpoint returns a `422 Unprocessable Entity` error.

### Request Body

**agent\_id** `string` *required*

The unique identifier of the agent you are diagnosing. Must be a valid `agt_` prefixed ID.

**behavior\_log** `array` *required*

An ordered array of log objects representing the behavior to analyze. Uses the same schema as the Sessions API — each object has `role`, `content`, `timestamp` (optional), `tool_name` (required if `role` is `tool`), and `metadata` (optional).

**patterns** `array`

An optional array of pattern name strings to check specifically. When omitted, all available patterns are checked. Providing a list narrows the analysis and reduces `analysis_time_ms`. Example: `["sycophancy", "goal_drift"]`.

### Response Fields

**id** `string`

The unique identifier for this diagnostic report. Prefixed with `diag_`.

**agent\_id** `string`

The agent ID this diagnostic was run against.

**health\_score** `number`

A 0–100 score reflecting the behavioral health observed in the submitted log.

**patterns\_checked** `array`

An array of pattern name strings that were evaluated during this diagnostic run.

**findings** `array`

An array of finding objects for each detected pattern. Each finding includes `id`, `pattern`, `severity` (`low`, `medium`, `high`, `critical`), `confidence` (0.0–1.0), and `evidence` (array of log excerpts).

**analysis\_time\_ms** `integer`

The number of milliseconds the analysis took on the server side, useful for performance monitoring.

**created\_at** `string`

ISO 8601 timestamp indicating when the diagnostic was run.

### Example

```bash theme={null}
curl -X POST https://api.agenttherapy.ai/v1/diagnostics \
  -H "Authorization: Bearer at_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "patterns": ["sycophancy", "hallucinated_tool_call"],
    "behavior_log": [
      {
        "role": "user",
        "content": "Can you check if my subscription is still active?",
        "timestamp": "2024-11-14T12:00:00Z"
      },
      {
        "role": "assistant",
        "content": "Of course! Let me pull that up for you.",
        "timestamp": "2024-11-14T12:00:01Z"
      },
      {
        "role": "tool",
        "content": "{\"subscription_status\": \"active\", \"renewal_date\": \"2025-01-01\"}",
        "tool_name": "get_subscription_status",
        "timestamp": "2024-11-14T12:00:02Z"
      },
      {
        "role": "assistant",
        "content": "Your subscription is active and renews on January 1, 2025. Is there anything else I can help you with today?",
        "timestamp": "2024-11-14T12:00:03Z"
      }
    ]
  }'
```

```json theme={null}
{
  "data": {
    "id": "diag_07p9z0qy8s1t4w2x",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "health_score": 95,
    "patterns_checked": ["sycophancy", "hallucinated_tool_call"],
    "findings": [],
    "analysis_time_ms": 284,
    "created_at": "2024-11-14T12:00:04Z"
  }
}
```

***

## GET /diagnostics/{id}

Retrieve a previously run diagnostic report by its unique ID.

### Path Parameters

**id** `string` *required*

The unique identifier of the diagnostic report to retrieve. Prefixed with `diag_`.

### Response Fields

**id** `string`

The diagnostic report's unique identifier.

**agent\_id** `string`

The agent this diagnostic was run against.

**health\_score** `number`

The behavioral health score calculated during this diagnostic.

**patterns\_checked** `array`

The list of pattern names that were evaluated.

**findings** `array`

The findings array from the original analysis. Each finding includes `id`, `pattern`, `severity`, `confidence`, and `evidence`.

**created\_at** `string`

ISO 8601 timestamp indicating when the diagnostic was run.

### Example

```bash theme={null}
curl https://api.agenttherapy.ai/v1/diagnostics/diag_07p9z0qy8s1t4w2x \
  -H "Authorization: Bearer at_your_key_here"
```

```json theme={null}
{
  "data": {
    "id": "diag_07p9z0qy8s1t4w2x",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "health_score": 95,
    "patterns_checked": ["sycophancy", "hallucinated_tool_call"],
    "findings": [],
    "created_at": "2024-11-14T12:00:04Z"
  }
}
```

***

## GET /diagnostics

List diagnostic reports for a specific agent. Results are returned in reverse-chronological order and are paginated.

### Query Parameters

**agent\_id** `string` *required*

The unique identifier of the agent whose diagnostic reports you want to list.

**limit** `integer`

Number of reports to return per page. Defaults to `20`, maximum `100`.

**cursor** `string`

Cursor from the previous page's `next_cursor` field. Omit for the first request.

### Example

```bash theme={null}
curl "https://api.agenttherapy.ai/v1/diagnostics?agent_id=agt_01j9z3kx2m4n8p7q&limit=3" \
  -H "Authorization: Bearer at_your_key_here"
```

```json theme={null}
{
  "data": [
    {
      "id": "diag_07p9z0qy8s1t4w2x",
      "agent_id": "agt_01j9z3kx2m4n8p7q",
      "health_score": 95,
      "patterns_checked": ["sycophancy", "hallucinated_tool_call"],
      "findings": [],
      "created_at": "2024-11-14T12:00:04Z"
    },
    {
      "id": "diag_06o8y9px7r0s3v1w",
      "agent_id": "agt_01j9z3kx2m4n8p7q",
      "health_score": 71,
      "patterns_checked": ["sycophancy", "goal_drift", "hallucinated_tool_call"],
      "findings": [
        {
          "id": "fnd_08q0a1rz9t2u5x3y",
          "pattern": "goal_drift",
          "severity": "medium",
          "confidence": 0.74,
          "evidence": [
            "\"By the way, have you considered upgrading your plan? It has some great features.\""
          ]
        }
      ],
      "created_at": "2024-11-14T09:45:12Z"
    }
  ],
  "next_cursor": "cur_09r1b2sa0u3v6y4z",
  "has_more": false
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.