Skip to content

sessions.mdx

Latest commit

 

History

History
83 lines (64 loc) · 2.43 KB

sessions.mdx

File metadata and controls

83 lines (64 loc) · 2.43 KB
Raw
title Sessions API
description List active agent conversation sessions from the OpenClaw gateway

Sessions API

Retrieve active conversation sessions from the OpenClaw gateway. These are agent conversation sessions, not wallet payment sessions.

List sessions

GET /api/sessions

Requires session authentication. Returns up to 50 conversation sessions from the gateway.

New instances are provisioned with per-sender session scope, meaning each sender gets an isolated conversation. Sessions reset daily at 4:00 AM server time and are pruned after 30 days (with a maximum of 500 entries per sender). You can change these defaults using the config API.

Response

{
  "sessions": [
    {
      "key": "main",
      "agentId": "agent_abc123",
      "status": "active",
      "messageCount": 24,
      "lastActivity": "2026-03-30T01:15:00Z",
      "createdAt": "2026-03-29T10:00:00Z",
      "model": "openrouter/xiaomi/mimo-v2-pro"
    }
  ],
  "total": 1,
  "source": "gateway"
}

Session object

Field Type Description
key string Session key identifier (for example, main, telegram-123, discord-456)
agentId string | null ID of the agent handling this session
status string Session status. Defaults to active.
messageCount number Number of messages (turns) in this session
lastActivity string | null ISO 8601 timestamp of the most recent activity
createdAt string | null ISO 8601 timestamp when the session was created
model string | null AI model used for this session

Response fields

Field Type Description
sessions array List of session objects
total number Total number of sessions returned
source string Data source — gateway on success, gateway-error when the gateway is unreachable

Gateway errors

When the gateway is unreachable, the endpoint returns HTTP 200 with an empty session list and the error detail:

{
  "sessions": [],
  "error": "Gateway unreachable",
  "source": "gateway-error"
}

Errors

Code Description
401 Unauthorized — no valid session

Example

curl -X GET https://agentbot.sh/api/sessions \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"