Sessions API

GET /api/sessions

List sessions with filtering and pagination.

Query Parameters

Parameter	Type	Description
agentId	string	Filter by agent ID
status	string	Filter by status: active, completed, error (comma-separated)
from	string	Start of time range (ISO 8601)
to	string	End of time range (ISO 8601)
tags	string	Filter by tags (comma-separated)
limit	number	Results per page (default: 50, max: 500)
offset	number	Pagination offset (default: 0)

Response (200)

{
  "sessions": [
    {
      "id": "sess_01HXYZ",
      "agentId": "my-agent",
      "agentName": "My Agent",
      "startedAt": "2026-02-08T10:00:00.000Z",
      "endedAt": "2026-02-08T10:05:00.000Z",
      "status": "completed",
      "eventCount": 47,
      "toolCallCount": 15,
      "errorCount": 0,
      "totalCostUsd": 0.42,
      "tags": ["production"]
    }
  ],
  "total": 256,
  "hasMore": true
}

curl Example

# List error sessions from the last week
curl "http://localhost:3400/api/sessions?status=error&from=2026-02-01T00:00:00Z" \
  -H "Authorization: Bearer als_your_key"

SDK Example

const { sessions, total } = await client.listSessions({
  status: 'error',
  from: '2026-02-01T00:00:00Z',
  limit: 20,
});

---

GET /api/sessions/:id

Get detailed information about a single session.

Response (200)

{
  "id": "sess_01HXYZ",
  "agentId": "my-agent",
  "agentName": "My Agent",
  "startedAt": "2026-02-08T10:00:00.000Z",
  "endedAt": "2026-02-08T10:05:00.000Z",
  "status": "completed",
  "eventCount": 47,
  "toolCallCount": 15,
  "errorCount": 0,
  "totalCostUsd": 0.42,
  "tags": ["production"]
}

Errors

Status	Cause
404	Session not found

---

GET /api/sessions/:id/timeline

Get all events for a session in ascending chronological order, with hash chain verification.

Response (200)

{
  "events": [
    {
      "id": "01H001...",
      "timestamp": "2026-02-08T10:00:00.000Z",
      "sessionId": "sess_01HXYZ",
      "agentId": "my-agent",
      "eventType": "session_started",
      "severity": "info",
      "payload": { "agentName": "My Agent", "tags": ["production"] },
      "metadata": {},
      "prevHash": null,
      "hash": "abc123..."
    },
    {
      "id": "01H002...",
      "timestamp": "2026-02-08T10:00:01.342Z",
      "sessionId": "sess_01HXYZ",
      "agentId": "my-agent",
      "eventType": "tool_call",
      "severity": "info",
      "payload": { "toolName": "search_database", "callId": "c1", "arguments": { "query": "users" } },
      "metadata": {},
      "prevHash": "abc123...",
      "hash": "def456..."
    }
  ],
  "chainValid": true
}

The chainValid field indicates whether the SHA-256 hash chain is intact (no events have been tampered with).

curl Example

curl "http://localhost:3400/api/sessions/sess_01HXYZ/timeline" \
  -H "Authorization: Bearer als_your_key"