Tenant-scoped forward to the wiki KB usage aggregation report (PLT-393): top queries, top-cited pages, miss rate, never-read pages (prune/merge candidates), and token trend over a rolling window
GET/api/kb/usage
Tenant-scoped forward to the wiki KB usage aggregation report (PLT-393): top queries, top-cited pages, miss rate, never-read pages (prune/merge candidates), and token trend over a rolling window. The report itself is computed by the wiki over wiki.kb_reads; this route forwards the caller’s own auth so the wiki’s RLS + classification gating scope the result to what the caller may see. Backs the (follow-up) kb_usage MCP tool and pt kb-usage CLI.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 502
- 503
Successful response
Validation failure (malformed spaceId, out-of-range days/limit). ALSO the wiki’s own proactive window-ceiling rejection, forwarded verbatim (PLT-755): the requested window holds more wiki.kb_reads rows than the report will aggregate, and error.details carries rowsInWindow, ceiling and suggestedWindowDays so a caller can retry programmatically rather than parsing the message.
Caller is not authenticated.
The wiki backend rejected the forwarded caller credentials (HTTP 401/403) — WIKI_BACKEND_FORBIDDEN.
The requested spaceId does not exist, was deleted, or is not visible to the caller — a clean upstream 404 from the wiki, not a backend outage. A 404 WITHOUT a spaceId is a routing/deployment fault and surfaces as 502 instead.
The wiki backend was unreachable or errored (timeout / malformed body / an uncoded 5xx) — WIKI_BACKEND_UNAVAILABLE. Note a 5xx is NOT automatically forwarded: only the deliberate, caller-fixable codes listed under 503 are, so an outage can never masquerade as a caller-fixable rejection.
Either the wiki backend is not configured on this deployment (WIKI_ZONE_URL unset — WIKI_BACKEND_NOT_CONFIGURED), or the wiki raised one of three DELIBERATE, caller-fixable conditions that are forwarded verbatim with their own code and error.details (PLT-755): KB_USAGE_WINDOW_TOO_LARGE (the report exceeded its transaction budget and the window is known large — retry with the smaller suggestedWindowDays), KB_USAGE_BUDGET_EXCEEDED (the budget expired before the window size was established, so the window is NOT known to be the cause — retry the same request), and KB_USAGE_BACKEND_BUSY (the database connection was busy, so the report never ran — retry the same request shortly). Switch on error.code, never on the status: the four share it and mean different things.