Endpoints · 04

Session management.

Four read endpoints to list and inspect the sessions and messages that conversational agents produce. Use them to poll message status, retrieve agent responses, and audit conversation history.

Conversational only

These routes are conversational-only. Workflow agents have no sessions, so these endpoints return 400 runtime_not_applicable for them. For workflow runs, use Run management.

Endpoints

Method	Path	Purpose
GET	`/api/agents/{agent_id}/sessions`	List sessions for an agent
GET	`/api/agents/{agent_id}/sessions/{session_id}`	Fetch one session with token usage and metadata
GET	`/api/agents/{agent_id}/sessions/{session_id}/messages`	List messages in a session
GET	`/api/agents/{agent_id}/sessions/{session_id}/messages/{message_id}`	Fetch one message with status, content, and token usage

List sessions

GET /api/agents/{agent_id}/sessions

Returns sessions for the agent, ordered by most-recently-active first. Only production sessions are returned — draft sessions created in Brain Builder are excluded automatically.

Query parameters

Name	Type	Default	Description
`limit`	`integer`	`20`	Max sessions to return. Capped at `100`.
`status`	`string`	—	Filter by session status — e.g. `active`, `closed`.
`since`	`ISO 8601`	—	Return only sessions with activity after this timestamp.

Any other query parameters are ignored.

Response shapeJSON

{
  "sessions": [
    {
      "session_id": "sess_01JV...",
      "agent_id": "agt_01HAKZ...",
      "status": "active",
      "channel": "webhook",
      "user_id": "user-42",
      "created_at": "2026-05-27T08:14:22Z",
      "last_message_at": "2026-05-27T08:15:04Z",
      "message_count": 4,
      "total_tokens": 1820
    }
  ],
  "limit": 20
}

List sessions · cURLshell

curl "https://webhook.olbrain.com/api/agents/agt_01HAKZ.../sessions?limit=10&status=active" \
  -H "Authorization: Bearer ak_<your-access-key>"

Fetch one session

GET /api/agents/{agent_id}/sessions/{session_id}

Returns the full session record including token usage breakdown, cost, and any custom metadata your agent attached.

Response shapeJSON

{
  "session_id": "sess_01JV...",
  "agent_id": "agt_01HAKZ...",
  "organization_id": "org_01GZ...",
  "project_id": "proj_01HB...",
  "status": "active",
  "channel": "webhook",
  "user_id": "user-42",
  "created_at": "2026-05-27T08:14:22Z",
  "last_message_at": "2026-05-27T08:15:04Z",
  "message_count": 4,
  "token_usage": {
    "prompt_tokens": 1640,
    "completion_tokens": 180,
    "total_tokens": 1820
  },
  "cost": 0.0031,
  "metadata": {}
}

List messages

GET /api/agents/{agent_id}/sessions/{session_id}/messages

Returns messages in chronological order (oldest first). Includes both user messages (the incoming trigger payloads) and assistant messages (the agent's replies).

Query parameters

Name	Type	Default	Description
`limit`	`integer`	`50`	Max messages to return. Capped at `200`.
`offset`	`integer`	`0`	Number of messages to skip (for pagination).
`role`	`string`	—	Filter by `user` or `assistant`.

Response shapeJSON

{
  "messages": [
    {
      "message_id": "msg_01JV...",
      "role": "user",
      "status": "completed",
      "content": "Order #4421 placed for Acme Corp",
      "created_at": "2026-05-27T08:14:22Z",
      "model": null,
      "token_usage": null
    },
    {
      "message_id": "msg_01JW...",
      "role": "assistant",
      "status": "completed",
      "content": "Order received — I'll start processing right away.",
      "created_at": "2026-05-27T08:14:23Z",
      "model": "claude-sonnet-4-6",
      "token_usage": {
        "prompt_tokens": 412,
        "completion_tokens": 18,
        "total_tokens": 430
      }
    }
  ],
  "limit": 50,
  "offset": 0
}

Fetch one message

GET /api/agents/{agent_id}/sessions/{session_id}/messages/{message_id}

Returns the full message record. The status field tells you whether the agent has finished responding:

Status	Meaning
`completed`	Agent finished processing; `content` is the final reply.
`error`	Processing failed. `error.code` will be `message_processing_failed`.

Response shape · assistant messageJSON

{
  "message_id": "msg_01JW...",
  "session_id": "sess_01JV...",
  "agent_id": "agt_01HAKZ...",
  "organization_id": "org_01GZ...",
  "project_id": "proj_01HB...",
  "role": "assistant",
  "status": "completed",
  "content": "Order received — I'll start processing right away.",
  "created_at": "2026-05-27T08:14:23Z",
  "model": "claude-sonnet-4-6",
  "token_usage": {
    "prompt_tokens": 412,
    "completion_tokens": 18,
    "total_tokens": 430
  },
  "cost": 0.00043,
  "processing_time_ms": 1240,
  "error": null
}

Polling tip

After triggering a conversational webhook, the response body includes a message_id. Poll GET .../messages/{message_id} until status is completed (or error) to retrieve the full agent response.

Scope & ownership

A session can only be read via the agent that created it. Querying a session with a different agent_id — or a key from a different org — returns 404 session_not_found regardless of whether the session exists. This prevents cross-org enumeration.

Errors

Status	Code	When
400	`runtime_not_applicable`	The agent is a workflow agent. Session management is conversational-only.
401	`unauthorized`	Missing or invalid Access Key.
404	`session_not_found`	Session doesn't exist or belongs to a different agent or org.
404	`message_not_found`	Message doesn't exist within the given session.
502	`upstream_timeout`	Agent runtime timed out. Retry with backoff.
502	`upstream_error`	Agent runtime returned an error. Retry with backoff.

For the full error reference, see Errors.