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
| Table | What it holds |
|---|---|
events | Every record: ts, project, source, kind, level, event, template_id, message, method, path, route, status, bytes, visitor, referrer, user_agent, is_bot, attrs |
templates | The log line patterns StatsRaven found |
patterns | Names, descriptions and areas given to patterns |
rollups | Hourly 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.