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

Query Structure

All queries go through a source resolver with a selector:

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

Available Fields

Namespace	Field	Description
AgentNamespace	sessions	List sessions with token usage, model, status
AgentNamespace	session(key)	Single session by key
AgentNamespace	metrics(range)	Aggregated metrics over a time range
AgentNamespace	events(limit, types)	Structured event log with filtering
AgentNamespace	lifetimeStats	All-time totals: days, sessions, tokens, messages
AgentNamespace	sessionTranscript(sessionKey)	Full conversation transcript
AgentNamespace	cronJobs	Scheduled job definitions
AgentNamespace	usageCost	Token cost breakdown
AgentNamespace	recentLogs(count)	Latest structured log entries

Subscriptions

Subscription	Transport	Description
dataChanged	SSE	Fires when any data source updates
logs	SSE	Streams structured log entries in real time

Examples

List sessions:

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 (last 24h):

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 { metrics(range: TWENTY_FOUR_HOUR) { totalTokensK totalErrors totalTurns 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 { companionDays totalSessions totalTokens totalMessages } } } }"}'

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.