GET /api/v1/agent/status

Get Agent Status

Retrieve the current agent status including global state (idle, active, degraded) and per-session breakdown with tool usage and token counts.

Overview

Returns a snapshot of the agent’s current state. The response includes a global summary (idle, active, or degraded) and a sessions array with per-session details like current state, active tool, duration, and token usage.

Info

If POCKETPAW_STATUS_API_KEY is set, requests must include the key via the X-Status-Key header or ?key= query parameter. When no key is configured, the endpoint is open.

Authentication

This endpoint uses its own auth mechanism, separate from the dashboard bearer token:

Method	Example
Header	`X-Status-Key: your-key`
Query param	`?key=your-key`
No key configured	Open access (default)

Response

global object

Global agent status summary.

state string

Overall state: idle (no active sessions), active (processing), or degraded (one or more sessions in error).

active_sessions integer

Number of currently active sessions.

max_concurrent integer

Maximum allowed concurrent conversations.

uptime_seconds integer

Seconds since the status tracker was initialized.

sessions array

List of active sessions. Empty when idle.

session_key string

Full session key (e.g. websocket:abc123).

session_id string

Session ID portion of the key.

channel string

Channel type: websocket, telegram, discord, slack, whatsapp, etc.

title string | null

Session title from memory, if available.

state string

Current state: thinking, tool_running, streaming, waiting_for_user, or error.

tool_name string | null

Name of the currently running tool (only set when state is tool_running).

duration_seconds number

Seconds since the last state change.

token_usage object | null

Accumulated token counts with input and output fields. Null if no tokens have been tracked yet.

error_message string | null

Error description when state is error.

# No auth key configured
curl http://localhost:8000/api/v1/agent/status

# With auth key
curl http://localhost:8000/api/v1/agent/status \
  -H "X-Status-Key: your-key"

const response = await fetch("http://localhost:8000/api/v1/agent/status", {
  headers: { "X-Status-Key": "your-key" }
});
const data = await response.json();
console.log(data.global.state); // "idle", "active", or "degraded"

import requests

response = requests.get(
    "http://localhost:8000/api/v1/agent/status",
    headers={"X-Status-Key": "your-key"}
)
data = response.json()
print(data["global"]["state"])

{
  "global": {
    "state": "idle",
    "active_sessions": 0,
    "max_concurrent": 5,
    "uptime_seconds": 3600
  },
  "sessions": []
}

{
  "global": {
    "state": "active",
    "active_sessions": 1,
    "max_concurrent": 5,
    "uptime_seconds": 3600
  },
  "sessions": [
    {
      "session_key": "websocket:abc123",
      "session_id": "abc123",
      "channel": "websocket",
      "title": "Help with Python script",
      "state": "tool_running",
      "tool_name": "bash",
      "duration_seconds": 2.3,
      "token_usage": { "input": 1500, "output": 320 },
      "error_message": null
    }
  ]
}

{
  "global": {
    "state": "degraded",
    "active_sessions": 2,
    "max_concurrent": 5,
    "uptime_seconds": 7200
  },
  "sessions": [
    {
      "session_key": "websocket:abc123",
      "session_id": "abc123",
      "channel": "websocket",
      "title": null,
      "state": "thinking",
      "tool_name": null,
      "duration_seconds": 1.0,
      "token_usage": null,
      "error_message": null
    },
    {
      "session_key": "discord:xyz789",
      "session_id": "xyz789",
      "channel": "discord",
      "title": null,
      "state": "error",
      "tool_name": null,
      "duration_seconds": 15.2,
      "token_usage": { "input": 800, "output": 50 },
      "error_message": "Rate limit exceeded"
    }
  ]
}

Was this page helpful?

Request

curl -X GET "http://localhost:8000/api/v1/agent/status" \
  -H "Content-Type: application/json"

const response = await fetch("http://localhost:8000/api/v1/agent/status", {
  method: "GET",
  headers: {
    "Content-Type": "application/json"
},
});

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "http://localhost:8000/api/v1/agent/status",
    headers={'Content-Type':'application/json'},
)

print(response.json())

package main

import (
    "fmt"
    "net/http"
    "io"
)

func main() {
    req, _ := http.NewRequest("GET", "http://localhost:8000/api/v1/agent/status", nil)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Response
Send a request to see the response