Programmatic Access

This guide walks through a complete end-to-end example: an AI agent querying its own status via the Claw Insights API.

All examples use curl so agents can copy-paste directly.

1. Authentication

Get your Bearer token from the running instance:

# Token is printed in the startup URL:
claw-insights status
# → http://127.0.0.1:41041/?token=a1b2c3d4e5...

# Or read from file:
cat ~/.claw-insights/auth-token

Set it as an environment variable:

export CI_TOKEN="$(cat ~/.claw-insights/auth-token)"
export CI_URL="http://127.0.0.1:41041"

If running with --no-auth, skip the Authorization header entirely.

2. Query Sessions

List all active sessions with token usage:

curl -s "$CI_URL/graphql" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ source(selector: { category: AGENT }) { ... on AgentNamespace { sessions(filter: { activeOnly: true, sortBy: TOKENS_DESC }) { key displayName model status totalTokens contextTokens usagePercent turnCount subAgents { key displayName } } } } }"
  }' | jq '.data.source.sessions'

Get a specific session by key:

curl -s "$CI_URL/graphql" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ source(selector: { category: AGENT }) { ... on AgentNamespace { session(key: \"SESSION_KEY\") { displayName model totalTokens turnCount status } } } }"
  }' | jq '.data.source.session'

3. Query Metrics

Get token usage and error counts for the last 6 hours:

curl -s "$CI_URL/graphql" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ source(selector: { category: AGENT }) { ... on AgentNamespace { metrics(range: SIX_HOUR) { date range totalTokensK rangeTokensK totalErrors totalWarnings uptimePercent totalTurns buckets { label tokensK errors warnings turns } } } }"
  }' | jq '.data.source.metrics'

Available ranges: THIRTY_MIN, ONE_HOUR, SIX_HOUR, TWELVE_HOUR, TWENTY_FOUR_HOUR.

4. Query System Health

curl -s "$CI_URL/graphql" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ system { ... on OpenClawSystem { health { status checks { name status message } } gateway { running version uptime } resources { cpu memoryMB } } } }"
  }' | jq '.data.system'

Union Type

system returns a SystemNamespace union. Use ... on OpenClawSystem inline fragment to select fields.

5. Generate a Snapshot

Create a visual status card (PNG):

curl -X POST "$CI_URL/api/snapshot" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"detail":"standard","range":"6h","theme":"dark"}' \
  -o snapshot.png

Get raw data as JSON (for programmatic processing):

curl -s -X POST "$CI_URL/api/snapshot" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"format":"json","range":"6h"}' | jq .

Parameters: detail (compact/standard/full), format (png/svg/json), range (30m/1h/6h/12h/24h), theme (dark/light), lang (en/zh).

6. Real-time Monitoring (SSE)

Subscribe to data change signals for live updates:

curl -N "$CI_URL/graphql" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"query": "subscription { dataChanged { source ts } }"}'

Transport

This uses GraphQL over SSE. Simple curl works for testing, but production clients should use a proper GraphQL-SSE client library for reconnection and error handling.

The dataChanged subscription emits lightweight signals ({ source, ts }) whenever data updates. The client should refetch the relevant query after receiving a signal. No historical events are replayed on reconnect.

For full GraphQL schema details, see the GraphQL API.