Skip to main content

​
Overview

The Sessions API provides visibility into active gateway sessions where agents are connected and processing work. Sessions track token usage, model selection, activity timestamps, and connection status. Mission Control aggregates session data from:
  • OpenClaw Gateway: Primary source for active agent sessions
  • Claude Code: Local Claude development sessions
  • Token Usage Database: Historical session data

​
Authentication

All session endpoints require authentication via:
  • Session Cookie: mc-session (set after login)
  • API Key: x-api-key header
Minimum role: Viewer

​
List Gateway Sessions

GET /api/sessions

Retrieve all active gateway sessions with token usage and status information.
Authorization: Viewer role required

​
Query Parameters

​
agent
string
Filter sessions by agent name
​
limit
integer
default:"50"
Maximum number of sessions to return

​
Response Fields

​
sessions
array
Array of session objects

​
Gateway Session Fields (when source = “gateway”)

When sessions are retrieved from the OpenClaw Gateway, they include:
  • Live token usage and context window information
  • Real-time activity status
  • Channel information (Discord, Slack, etc.)
  • Session type (chat, cron, etc.)

​
Local Session Fields (when source = “local”)

When sessions are retrieved from local Claude Code database:
​
userMessages
integer
Number of user messages in session
​
assistantMessages
integer
Number of assistant responses
​
toolUses
integer
Number of tool invocations
​
estimatedCost
number
Estimated cost in USD
​
lastUserPrompt
string
Most recent user prompt text

​
Example Request

curl -X GET "https://your-domain.com/api/sessions?agent=code-reviewer&limit=20" \
  -H "x-api-key: your-api-key"

​
Example Response (Gateway Sessions)

{
  "sessions": [
    {
      "id": "code-reviewer:session-abc123",
      "key": "session-abc123",
      "agent": "code-reviewer",
      "kind": "chat",
      "age": "2h",
      "model": "claude-sonnet-4",
      "tokens": "12k/35k (34%)",
      "channel": "discord",
      "flags": [],
      "active": true,
      "startTime": 1709848800,
      "lastActivity": 1709856000,
      "source": "gateway"
    },
    {
      "id": "task-manager:session-def456",
      "key": "session-def456",
      "agent": "task-manager",
      "kind": "cron",
      "age": "15m",
      "model": "claude-3-5-haiku",
      "tokens": "3k/35k (9%)",
      "channel": "internal",
      "flags": [],
      "active": true,
      "startTime": 1709855100,
      "lastActivity": 1709856000,
      "source": "gateway"
    }
  ]
}

​
Example Response (Local Claude Sessions)

{
  "sessions": [
    {
      "id": "claude-abc-def-123",
      "key": "mission-control",
      "agent": "mission-control",
      "kind": "claude-code",
      "age": "1h",
      "model": "claude-sonnet-4",
      "tokens": "45k/82k",
      "channel": "local",
      "flags": ["main"],
      "active": true,
      "startTime": 1709852400,
      "lastActivity": 1709856000,
      "source": "local",
      "userMessages": 12,
      "assistantMessages": 12,
      "toolUses": 35,
      "estimatedCost": 0.42,
      "lastUserPrompt": "Create API documentation pages"
    }
  ]
}
Session DeduplicationOpenClaw tracks cron runs under the same session ID as parent sessions. Mission Control automatically deduplicates by sessionId, keeping the most recently updated entry when duplicates exist.

​
Error Responses

​
401 Unauthorized
Authentication required or invalid credentials

​
Control Session

POST /api/sessions/{id}/control

Control a session with pause, resume, or kill actions.
Authorization: Operator role required

​
Path Parameters

​
id
string
required
Session ID (key)

​
Request Body

​
action
string
required
Control action to perform

​
Response

​
success
boolean
Whether the control action was successful

​
Example Request

curl -X POST "https://your-domain.com/api/sessions/session-abc123/control" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "action": "pause"
  }'

​
Example Response

{
  "success": true
}

​
Error Responses

​
400 Bad Request
Invalid action or missing required fields
​
401 Unauthorized
Authentication required
​
403 Forbidden
Insufficient permissions (requires operator role)
​
404 Not Found
Session does not exist or has expired

​
Session Data Sources

Understanding Session Data

Mission Control aggregates session data from multiple sources.

​
Priority Order

  1. OpenClaw Gateway Sessions (Primary)
    • Live sessions from connected agents
    • Real-time token usage and status
    • Most up-to-date information
  2. Claude Code Local Sessions (Fallback)
    • Local development sessions
    • Historical data from SQLite database
    • Used when no gateway sessions available
  3. Token Usage Database (Final Fallback)
    • Derived from recorded token usage
    • Used when no active sessions exist

​
Session Types

Gateway Sessions are live connections between agents and the OpenClaw gateway.Characteristics:
  • Real-time status updates
  • Active token counting
  • Channel information (Discord, Slack, etc.)
  • Support for control actions (pause/resume/kill)
Common Types:
  • chat - Interactive chat sessions
  • cron - Scheduled task executions
  • webhook - Webhook-triggered sessions

​
Token Usage Formatting

Understanding Token Display

How token counts are formatted in session responses.

​
Format: used/context (percentage%)

Example: 12k/35k (34%)
  • 12k: Tokens used in this session
  • 35k: Total context window size
  • 34%: Percentage of context consumed

​
Token Abbreviations

  • Numbers ≥ 1,000,000: 1.5m (millions)
  • Numbers ≥ 1,000: 15k (thousands)
  • Numbers < 1,000: 850 (exact count)

​
Age Formatting

Session Age Display

How session age is calculated and displayed.
Age is calculated from the last activity timestamp:
  • Minutes: 15m (less than 1 hour)
  • Hours: 2h (less than 24 hours)
  • Days: 3d (24 hours or more)

​
Monitoring Best Practices

Session Monitoring Tips

Recommendations for effective session monitoring.

​
Active Monitoring

  1. Check session age regularly - Sessions older than 24h may be stale
  2. Monitor token usage - High percentages indicate context window pressure
  3. Track inactive sessions - active: false sessions may need cleanup
  4. Review failed sessions - Check for error patterns

​
Control Actions

Use Kill with CautionThe kill action terminates a session immediately. This may interrupt agent work in progress. Use pause first for graceful suspension.

​
Performance Considerations

  • Gateway sessions update in real-time
  • Local sessions refresh on database sync (typically every 5 minutes)
  • Token usage data is deduplicated to prevent duplicates from cron runs