StatsRaven

SQL API

Any program that can send HTTP can run read-only SQL against StatsRaven. Use a token from Settings, Claude and MCP, Tokens, or from statsraven admin-token.

curl -X POST https://stats.example.com/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT count(*) FROM events"}' 

The answer is a JSON array with one object per row. A query that fails returns 400 with {"error": "query_failed", "detail": "..."}. Statements that change data are refused. The API can be turned off in Settings, Claude and MCP, which returns 403.

On the server itself: statsraven query "SELECT count(*) FROM events".

Tables

TableWhat it holds
eventsEvery record: ts, project, source, kind, level, event, template_id, message, method, path, route, status, bytes, visitor, referrer, user_agent, is_bot, attrs
templatesThe log line patterns StatsRaven found
patternsNames, descriptions and areas given to patterns
rollupsHourly totals for each finished day, kept after raw events are removed

Read any other field you sent with attr(attrs, 'name'):

SELECT attr(attrs, 'plan') AS plan, count(*) AS signups
FROM events
WHERE project = 'shop' AND event = 'signup' AND ts > now() - INTERVAL '30 days'
GROUP BY plan
ORDER BY signups DESC

The SQL dialect is Apache DataFusion's, which is close to PostgreSQL. Each query can use up to 256 MB of memory and two run at a time. Every call is written to the change log with the token's name.