GraphQL API

Claw Insights exposes a GraphQL API for querying gateway data and subscribing to real-time changes.

Endpoint

• URL: POST /graphql
• Auth: Bearer token (Authorization: Bearer <token>) or session cookie

Root Queries

The schema provides three root queries:

Query	Description
system	System-level state: gateway status, resources, channels, health
sources(filter)	List registered data sources with status and attributes
source(selector)	Resolve a single data source namespace for detailed queries

system

Returns an OpenClawSystem namespace with gateway process status, resource usage, channel connectivity, and health checks.

query {
  system {
    ... on OpenClawSystem {
      gateway { running version appVersion uptime pid updateAvailable }
      resources { cpu memoryMB diskMB sampledAt }
      channels { provider name connected latencyMs }
      health { status checks { name status message } }
    }
  }
}

sources(filter)

List all registered data sources, optionally filtered by category, provider, status, or tags.

query {
  sources(filter: { category: AGENT }) {
    id name status
    attributes { category provider tags }
  }
}

SourceFilter input fields: category (AGENT | DASHBOARD), provider (OPENCLAW | CLAUDE_CODE | CODEX), status (INITIALIZING | CONNECTED | DISCONNECTED | ERROR), tags ([String!]).

source(selector)

Resolve a single source namespace by selector. Returns a SourceNamespace union (AgentNamespace | DashboardNamespace).

query {
  source(selector: { category: AGENT, provider: OPENCLAW }) {
    ... on AgentNamespace {
      sessions { key model totalTokens turnCount status }
    }
  }
}

SourceSelector input fields: id, category, provider, tags.

All three root queries accept an optional context: QueryContext input for request tracing, display preferences, and default filters.

AgentNamespace Fields

Field	Arguments	Description
sessions(filter)	activeOnly, grouped, sortBy	List sessions with token usage, model, status
session(key)	key: String!	Single session by key
metrics(date, range)	date: String, range: MetricsRange	Aggregated metrics over a time range
events(from, to, types, limit)	from/to: Int, types: [String!], limit: Int	Structured event log with filtering
eventDensity	—	Hourly event density buckets with error/warning/restart flags
eventCounts(from, to)	from/to: Int	Aggregate counts of errors, warnings, restarts
lifetimeStats	—	All-time totals: days, sessions, tokens, messages
sessionTranscript(sessionKey, limit, before, after)	sessionKey: String!, limit: Int, before/after: String	Paginated session transcript with cursor-based navigation
cronJobs	—	Scheduled job definitions
usageCost	—	Token cost breakdown
recentLogs(count)	count: Int	Latest structured log entries

lifetimeStats Subfields

Field	Type	Description
isReady	Boolean!	Whether initial transcript scan has completed
createdAt	String!	ISO timestamp of earliest known activity
daysSinceCreation	Int!	Days since creation
totalSessions	Int!	Count of transcript files on disk
totalInputTokens	Float!	Cumulative input tokens
totalOutputTokens	Float!	Cumulative output tokens
totalCacheReadTokens	Float!	Cumulative cache read tokens
totalCacheWriteTokens	Float!	Cumulative cache write tokens
totalTokens	Float!	Sum of all token categories
totalUserMessages	Int!	Total user messages across all sessions
totalAssistantMessages	Int!	Total assistant messages across all sessions

Token fields use Float to avoid GraphQL Int32 overflow for large cumulative values.

sessionTranscript Return Type

Field	Type	Description
sessionKey	String!	Session key
displayName	String!	Session display name
model	String!	Model at session start
channel	String	Channel provider
kind	String!	Session kind: direct / group / cron
thinkingLevel	String	Thinking level at session start
startedAt	String!	ISO timestamp
fileSize	Int!	Transcript file size in bytes
totalTokens	Int!	Total tokens consumed
contextTokens	Int!	Approximate context window usage
durationMs	Int!	Session duration in milliseconds
isSubAgent	Boolean!	Whether this is a sub-agent session
parentDisplayName	String	Parent session name (sub-agent only)
spawnPrompt	String	First user message (sub-agent spawn prompt)
messages	[TranscriptMessage!]!	Structured messages
totalMessages	Int!	Total message count in file
pageInfo	PageInfo!	Cursor pagination info

Use limit, before, and after arguments for cursor-based pagination through messages.

Key Types

DataSource

type DataSource {
  id: String!
  name: String!
  status: SourceStatus!          # INITIALIZING | CONNECTED | DISCONNECTED | ERROR
  attributes: SourceAttributes!  # category, provider, tags
}

HealthStatus / HealthCheck

type HealthStatus {
  status: HealthLevel!    # HEALTHY | DEGRADED | UNHEALTHY
  checks: [HealthCheck!]!
}

type HealthCheck {
  name: String!
  status: CheckStatus!    # PASS | WARN | FAIL
  message: String
}

EventDensityBucket

type EventDensityBucket {
  hour: Int!
  count: Int!
  hasError: Boolean!
  hasWarning: Boolean!
  hasRestart: Boolean!
  errorCount: Int!
  warningCount: Int!
  restartCount: Int!
  epochStart: Int!
}

EventCounts

type EventCounts {
  error: Int!
  warning: Int!
  restart: Int!
}

Subscriptions

Subscription	Transport	Description
dataChanged	SSE	Fires when any data source updates (lightweight signal — client should refetch)
logs(filter)	SSE	Streams structured log entries in real time (level, module filters)

Examples

System status:

curl -X POST http://127.0.0.1:41041/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ system { ... on OpenClawSystem { gateway { running version uptime } resources { cpu memoryMB } health { status checks { name status } } } } }"}'

List data sources:

curl -X POST http://127.0.0.1:41041/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ sources { id name status attributes { category provider } } }"}'

Agent sessions and metrics:

curl -X POST http://127.0.0.1:41041/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ source(selector: { category: AGENT, provider: OPENCLAW }) { ... on AgentNamespace { sessions { key model totalTokens turnCount status } metrics(range: TWENTY_FOUR_HOUR) { totalTokensK totalErrors uptimePercent } } } }"}'

Lifetime stats:

curl -X POST http://127.0.0.1:41041/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ source(selector: { category: AGENT, provider: OPENCLAW }) { ... on AgentNamespace { lifetimeStats { isReady daysSinceCreation totalSessions totalTokens totalUserMessages totalAssistantMessages } } } }"}'

Subscribe to changes (SSE):

curl -N http://127.0.0.1:41041/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "subscription { dataChanged { source ts } }"}'

Schema

Full GraphQL schema is available on GitHub.