Sessions API: Submit and Retrieve Diagnostic Sessions

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) 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

string

required

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

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.

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:

string

required

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

string

required

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

string

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

string

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

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

string

The unique identifier for the session. Prefixed with sess_.

string

The agent ID this session was submitted for.

string

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

string

ISO 8601 timestamp indicating when the session was submitted.

Example

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"
        }
      }
    ]
  }'

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

GET /sessions/

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 to be notified when the session.completed event fires.

Path Parameters

string

required

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

Response Fields

string

The session’s unique identifier.

string

The agent this session belongs to.

string

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

number

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

string

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

array

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

Show Finding object fields

string

Unique identifier for this finding. Prefixed with fnd_.

string

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

string

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

number

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

array

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

array

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

string

ISO 8601 timestamp when the session was submitted.

string

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

Example

curl https://api.agenttherapy.ai/v1/sessions/sess_04m6w7nv5p8q1t9u \
  -H "Authorization: Bearer at_your_key_here"

{
  "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

string

required

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

integer

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

string

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

string

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

Example

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

{
  "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
}

Overview

Endpoints

Webhooks

Sessions API: Submit and Retrieve Diagnostic Sessions

POST /sessions

Request Body

Log Object Fields

Response Fields

Example

GET /sessions/

Path Parameters

Response Fields

Example

GET /sessions

Query Parameters

Example

​POST /sessions

​Request Body

​Log Object Fields

​Response Fields

​Example

​GET /sessions/

​Path Parameters

​Response Fields

​Example

​GET /sessions

​Query Parameters

​Example

POST /sessions

Request Body

Log Object Fields

Response Fields

Example

GET /sessions/

Path Parameters

Response Fields

Example

GET /sessions

Query Parameters

Example