Skip to main content
Use this endpoint to retrieve the complete ordered event log for an agent session. Events are returned in ascending event_time order, giving you a precise chronological trace of every API call the agent made during that session. This is the primary tool for session replay, root cause analysis, and understanding exactly what an agent did — including which external paths it hit, what responses it received, and whether any errors occurred.
Results are capped at 500 events per request. Use the limit parameter to reduce the page size. If a session has more than 500 events, only the earliest limit events are returned.

​
Request

​
X-OTAS-USER-TOKEN
string
required
JWT identifying the authenticated user.
​
X-OTAS-AGENT-ID
string
required
UUID of the agent that owns the session.
​
X-OTAS-PROJECT-ID
string
required
UUID of the project the agent belongs to.

​
Query parameters

​
session_id
string
required
UUID of the agent session. Corresponds to the agent_session_id claim in the session JWT and the AgentSession.id in UASAM.
​
limit
number
default:"200"
Maximum number of events to return. Clamped to the range [1, 500]. Defaults to 200.

​
Response

​
status
number
required
1 on success.
​
status_description
string
required
session_events_listed on success.
​
agent_id
string
required
The agent UUID from the request headers.
​
project_id
string
required
The project UUID from the request headers.
​
session_id
string
required
The session UUID from the query parameters, echoed back.
​
count
number
required
Number of events included in this response (at most limit).
​
events
object[]
required
Ordered list of serialized BackendEvent records.
curl --request GET \
  --url "http://localhost:8002/api/v1/agent/session/events/?session_id=b7e3a1c2-d4f5-6789-bcde-fa0987654321&limit=50" \
  --header "X-OTAS-USER-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --header "X-OTAS-AGENT-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "X-OTAS-PROJECT-ID: 3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234"

{
  "status": 1,
  "status_description": "session_events_listed",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "project_id": "3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234",
  "session_id": "b7e3a1c2-d4f5-6789-bcde-fa0987654321",
  "count": 2,
  "events": [
    {
      "event_id": "c1d2e3f4-a5b6-7890-cdef-ab1234567890",
      "event_time": "2026-03-26T10:00:01.123456+00:00",
      "event_date": "2026-03-26",
      "project_id": "3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent_session_id": "b7e3a1c2-d4f5-6789-bcde-fa0987654321",
      "path": "/api/v1/users/",
      "method": "GET",
      "status_code": 200,
      "latency_ms": 87.4,
      "request_size_bytes": 0,
      "response_size_bytes": 1024,
      "request_headers": "{\"Accept\": \"application/json\"}",
      "request_body": null,
      "query_params": "page=1",
      "post_data": null,
      "response_headers": "{\"Content-Type\": \"application/json\"}",
      "response_body": "{\"users\": [...]}",
      "request_content_type": null,
      "response_content_type": "application/json",
      "custom_properties": null,
      "error": null,
      "metadata": null,
      "created_at": "2026-03-26T10:00:01.200000+00:00"
    },
    {
      "event_id": "d2e3f4a5-b6c7-8901-defa-bc2345678901",
      "event_time": "2026-03-26T10:00:05.654321+00:00",
      "event_date": "2026-03-26",
      "project_id": "3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent_session_id": "b7e3a1c2-d4f5-6789-bcde-fa0987654321",
      "path": "/api/v1/external-service/",
      "method": "POST",
      "status_code": 500,
      "latency_ms": 2310.0,
      "request_size_bytes": 256,
      "response_size_bytes": 128,
      "request_headers": "{\"Content-Type\": \"application/json\"}",
      "request_body": "{\"payload\": \"data\"}",
      "query_params": null,
      "post_data": null,
      "response_headers": "{\"Content-Type\": \"application/json\"}",
      "response_body": "{\"error\": \"Internal Server Error\"}",
      "request_content_type": "application/json",
      "response_content_type": "application/json",
      "custom_properties": null,
      "error": "upstream returned 500",
      "metadata": null,
      "created_at": "2026-03-26T10:00:05.720000+00:00"
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us