Explain Endpoint — One-Call Routing Decision Trace
2026-03-26
What We Built
GET /v1/explain/{request_id} — a single endpoint that returns the complete routing decision trace for any completed request. Model selection rationale, alternatives considered with scores, complexity classification, guardrail results, cost breakdown, quality prediction, and latency metrics.
Previously this data was scattered across 70+ response headers and separate audit tables. Now it's one clean JSON response that agents can use for self-improvement, developers for debugging, and dashboards for transparency.
Why It Matters
When an AI request costs more than expected or picks an unexpected model, operators need to understand _why_. The explain endpoint makes every routing decision fully transparent and queryable after the fact — no log diving, no header parsing.
How It Works
The endpoint consolidates data already captured by the router's intelligence systems:
curl https://api.brainstormrouter.com/v1/explain/req_abc123 \
-H "Authorization: Bearer br-xxx"Returns model selection (Thompson sampling scores), alternatives rejected (with reasons), complexity classification, guardrail pass/fail, actual vs estimated cost, TTFT, and cache status.
Assembly is a single indexed DB lookup — no joins, no aggregation. The decision trace is stored as JSONB in the usage_events table alongside every request.
Lockstep Checklist
- [x] API Routes:
src/api/routes/explain-request.ts— new route, mounted in server.ts - [x] TS SDK:
packages/sdk-ts/src/resources/explain-request.ts—client.explain.get(requestId) - [x] Python SDK:
packages/sdk-py/src/brainstormrouter/resources/explain_request.py— sync + async - [x] MCP Schemas:
br_explain_requesttool in manifest, server, and agents.json - [ ] Master Record: Update when record exists