GET /api/agent/v1/sessions/list/

This endpoint returns the complete session history for a given agent, ordered newest-first by creation time. Each session record includes the metadata attached at creation and the ID of the key that was used to start it. Use this endpoint to audit agent activity, replay debugging timelines, or surface session IDs for downstream log queries.

Endpoint

GET /api/agent/v1/sessions/list/

Base URL: http://localhost:8000

Request headers

string

required

JWT obtained from the OTAS login endpoint, identifying the calling user.

string

required

UUID of the project the agent belongs to. The agent must be active and owned by this project or the request returns a 403.

Query parameters

string

required

UUID of the agent whose sessions you want to retrieve.

Response

number

1 on success.

string

"agent_sessions_listed" on success.

object

Hide properties

string

UUID of the queried agent.

object[]

Array of session objects, ordered by created_at descending (newest first). Empty array if no sessions exist.

Hide session properties

string

UUID of the session.

string

UUID of the AgentKey used to create this session, or null if the key has since been deleted.

string

ISO 8601 timestamp of when the session was created.

object

JSON metadata attached when the session was created. Empty object {} if none was provided.

Errors

Status	`status_description`	Cause
400	`agent_id_required`	The `agent_id` query parameter was not provided.
403	`agent_not_found_or_no_access`	No active agent with that UUID exists in the project, or the agent belongs to a different project.

Example

cURL

curl --request GET \
  --url "http://localhost:8000/api/agent/v1/sessions/list/?agent_id=d1e2f3a4-b5c6-7890-abcd-ef1234567890" \
  --header "X-OTAS-USER-TOKEN: <your-user-jwt>" \
  --header "X-OTAS-PROJECT-ID: 4b7e2f1a-9c3d-4e8b-a012-3f5d6e7c8b9a"

Response (200)

{
  "status": 1,
  "status_description": "agent_sessions_listed",
  "response": {
    "agent_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
    "sessions": [
      {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "agent_key_id": "c9d8e7f6-a5b4-3210-fedc-ba9876543210",
        "created_at": "2026-04-16T14:30:00.000000+00:00",
        "meta": {
          "task": "summarize",
          "input_length": 512
        }
      },
      {
        "id": "a9b8c7d6-e5f4-3210-9876-543210abcdef",
        "agent_key_id": "c9d8e7f6-a5b4-3210-fedc-ba9876543210",
        "created_at": "2026-04-16T09:15:00.000000+00:00",
        "meta": {}
      }
    ]
  }
}

UASAM — Users & Auth

UASAM — Projects & Keys

UASAM — Agents

Brain — Event Capture

Brain — Analytics

GET /api/agent/v1/sessions/list/

Endpoint

Request headers

Query parameters

Response

Errors

Example

​Endpoint

​Request headers

​Query parameters

​Response

​Errors

​Example

Endpoint

Request headers

Query parameters

Response

Errors

Example