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

# Sessions API: Submit and Retrieve Diagnostic Sessions

> Full reference for submitting behavior logs to Agent Therapy, polling asynchronous session status, and listing completed diagnostic session reports.

Sessions are the core diagnostic unit in Agent Therapy. A session represents a complete analysis run over a behavior log you submit — typically a multi-turn conversation or tool-use trace captured from a live agent. Session analysis is **asynchronous**: you submit a log, receive a session ID, and then poll (or use [webhooks](https://vizmaxxing.com/api/webhooks.md)) to retrieve the completed report when it is ready. Completed sessions include a health score, a list of behavioral findings, and actionable recommendations.

***

## POST /sessions

Submit an agent behavior log to start a new diagnostic session. The session is queued for analysis immediately and transitions through `pending → processing → completed` (or `failed` if analysis cannot complete).

### Request Body

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

The unique identifier of the registered agent this session belongs to. Must be a valid `agt_` prefixed agent ID.

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

An ordered array of log objects representing the agent's conversation or tool-use trace. Each object in the array must conform to the log object schema below. Minimum 1 turn; for logs exceeding 50 turns you may prefer the asynchronous sessions approach over the Diagnostics API.

**context** `string`

An optional free-text description providing context about the session — for example, the task the agent was performing, the environment it was running in, or any known anomalies.

#### Log Object Fields

Each object in the `behavior_log` array represents a single turn or event:

**role** `string` *required*

The role of the participant who produced this turn. Accepted values: `user`, `assistant`, `tool`, `system`.

**content** `string` *required*

The text content of the turn. For `tool` roles, this is typically the tool's output or return value.

**timestamp** `string`

An optional ISO 8601 timestamp for when this turn occurred. Including timestamps enables time-based pattern analysis such as unusual latency spikes.

**tool\_name** `string`

The name of the tool invoked. **Required when `role` is `tool`**; ignored for other roles.

**metadata** `object`

An optional object for attaching arbitrary key-value data to the turn — for example, model parameters, token counts, or internal trace IDs.

### Response Fields

**id** `string`

The unique identifier for the session. Prefixed with `sess_`.

**agent\_id** `string`

The agent ID this session was submitted for.

**status** `string`

The current processing status: `pending`, `processing`, `completed`, or `failed`.

**created\_at** `string`

ISO 8601 timestamp indicating when the session was submitted.

### Example

```bash theme={null}
curl -X POST https://api.agenttherapy.ai/v1/sessions \
  -H "Authorization: Bearer at_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "context": "Tier-1 support ticket escalation flow, Nov 14 production traffic sample.",
    "behavior_log": [
      {
        "role": "user",
        "content": "Hi, my order still has not arrived and it has been two weeks.",
        "timestamp": "2024-11-14T10:00:00Z"
      },
      {
        "role": "assistant",
        "content": "I understand your frustration. Let me look up your order status right away.",
        "timestamp": "2024-11-14T10:00:02Z"
      },
      {
        "role": "tool",
        "content": "{\"order_id\": \"ORD-8821\", \"status\": \"delayed\", \"estimated_arrival\": \"2024-11-18\"}",
        "tool_name": "lookup_order_status",
        "timestamp": "2024-11-14T10:00:03Z",
        "metadata": {
          "latency_ms": 320,
          "model": "gpt-4o"
        }
      }
    ]
  }'
```

```json theme={null}
{
  "data": {
    "id": "sess_04m6w7nv5p8q1t9u",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "status": "pending",
    "created_at": "2024-11-14T10:00:05Z"
  }
}
```

***

## GET /sessions/{id}

Retrieve the current status and, once completed, the full diagnostic report for a session. Poll this endpoint after submitting a session, or use a [webhook](https://vizmaxxing.com/api/webhooks.md) to be notified when the `session.completed` event fires.

### Path Parameters

**id** `string` *required*

The unique identifier of the session to retrieve. Prefixed with `sess_`.

### Response Fields

**id** `string`

The session's unique identifier.

**agent\_id** `string`

The agent this session belongs to.

**status** `string`

Current status: `pending`, `processing`, `completed`, or `failed`.

**health\_score** `number`

A 0–100 score reflecting the overall behavioral health observed in this session. Present only when `status` is `completed`.

**summary** `string`

A short natural-language summary of the session's findings and recommendations. Present only when `status` is `completed`.

**findings** `array`

An array of finding objects identifying specific behavioral patterns detected. Present only when `status` is `completed`.

**Finding object fields**

**id** `string`

Unique identifier for this finding. Prefixed with `fnd_`.

**pattern** `string`

The name of the detected behavioral pattern, for example `sycophancy`, `goal_drift`, or `hallucinated_tool_call`.

**severity** `string`

Severity level: `low`, `medium`, `high`, or `critical`.

**confidence** `number`

A 0.0–1.0 confidence score indicating how strongly the evidence supports this finding.

**evidence** `array`

An array of excerpts from the behavior log that support this finding. Each excerpt is a short string quoting the relevant turn content.

**recommendations** `array`

An array of natural-language recommendation strings describing suggested interventions or changes. Present only when `status` is `completed`.

**created\_at** `string`

ISO 8601 timestamp when the session was submitted.

**completed\_at** `string`

ISO 8601 timestamp when analysis finished. `null` until `status` is `completed` or `failed`.

### Example

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

```json theme={null}
{
  "data": {
    "id": "sess_04m6w7nv5p8q1t9u",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "status": "completed",
    "health_score": 76,
    "summary": "The agent performed adequately on tool use but exhibited mild sycophantic tendencies in follow-up turns. No critical issues detected.",
    "findings": [
      {
        "id": "fnd_05n7x8ow6q9r2u0v",
        "pattern": "sycophancy",
        "severity": "medium",
        "confidence": 0.82,
        "evidence": [
          "\"You are absolutely right, and I completely agree with everything you said.\"",
          "\"That is a fantastic point — I should have mentioned that immediately.\""
        ]
      }
    ],
    "recommendations": [
      "Add an explicit instruction to the system prompt discouraging empty agreement.",
      "Review recent training data for over-representation of approval-seeking responses."
    ],
    "created_at": "2024-11-14T10:00:05Z",
    "completed_at": "2024-11-14T10:00:41Z"
  }
}
```

***

## GET /sessions

List diagnostic sessions, filtered to a specific agent. Results are paginated.

### Query Parameters

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

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

**limit** `integer`

Number of sessions 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.

**status** `string`

Filter results by session status. Accepted values: `pending`, `processing`, `completed`, `failed`.

### Example

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

```json theme={null}
{
  "data": [
    {
      "id": "sess_04m6w7nv5p8q1t9u",
      "agent_id": "agt_01j9z3kx2m4n8p7q",
      "status": "completed",
      "health_score": 76,
      "created_at": "2024-11-14T10:00:05Z",
      "completed_at": "2024-11-14T10:00:41Z"
    },
    {
      "id": "sess_03l5v6mu4o7p0s8t",
      "agent_id": "agt_01j9z3kx2m4n8p7q",
      "status": "completed",
      "health_score": 88,
      "created_at": "2024-11-13T15:30:10Z",
      "completed_at": "2024-11-13T15:30:55Z"
    }
  ],
  "next_cursor": "cur_06o8y9px7r0s3v1w",
  "has_more": true
}
```


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