Usage and feedback

Open Admin → AI → Usage. This page and its HTTP endpoints require the administrator role. They expose usage metadata, feedback comments, and stored errors, without granting access to another user's private chat content.

Filter and investigate

The shared filters are period, user, model profile, actual provider model, and application. Compact filter chips apply selections immediately. Search user and model selectors by name or identifier. The runs view has a search row; submit text searches with Enter. About these data explains measurement and attribution limits. Filters, view, sorting, and pagination are stored in the URL. Refresh advances the period end; pagination retains the end time so new runs do not shift existing pages.

• Overview shows inference totals, coverage, timelines, application usage, chat launches, and tool activity. Chat and background inference count once. Tool events have no additional inference charge.
• Users & models displays one comparison table at a time. Switch between users and models to compare volume, costs, failures, latency, throughput, switches away, and feedback. Sort by volume, tokens, credits, failures, negative count, or negative share. Models are grouped by both profile and actual provider model, so editing a profile does not merge different models.
• Feedback filters current ratings by positive/negative and reason. The totals retain the whole selected user/model cohort, so filtering to negative feedback does not turn its denominator into 100%. Details show the full stored comment, reasons, timestamps, and identifiers.
• Errors & runs filters chat, background, and tool events by kind, status, task, error code, or literal text in the task/error. Show error opens the complete stored error plus attribution, duration, usage, and references. Copy details copies the displayed information.

Click a user or model to narrow the report. Click a failure count to open its matching runs. Run-specific filters apply only to the run list; rating and reason apply only to the feedback list.

Read the numbers correctly

Periods cover the start time of each run. Feedback uses current ratings on assistant messages belonging to chat turns started in that period, everywhere in the report. A rating added today to an older response does not move the response into today's period. Ratings can be edited or cleared; this is not a history of rating changes.

Negative share is negative ratings divided by all ratings. Rating coverage is rated assistant messages divided by stored assistant messages in the selected chat turns. Read both alongside the counts: one negative rating out of one is not the same evidence as 100 out of 100. Background runs have no message ratings. The user is the chat owner; the current feedback endpoint only accepts feedback on the caller's own chats.

Unknown tokens and prices appear as —. Coverage reports the fraction of runs with measurements; partial totals sum only reported values. A reported zero is retained as zero. No price is inferred for a provider that omits it. Chat duration is generation time; background duration is elapsed inference time, and tool duration is execution time. Switching away is counted within the selected period before applying model filters.

Chat accounting survives retry/edit removal of messages. Feedback and its coverage describe remaining messages; deleting a chat removes its chat turns and feedback. The standalone background ledger retains metadata and clears user/chat/turn references when their owners are deleted.

Background attribution

runAiStructured() accepts optional attribution metadata with userId, conversationId, turnId, and workflowRunId. Supply existing identifiers only after authorizing the domain operation. This metadata is not authorization. When a conversation is supplied without a user, its owner supplies attribution. Cloud also records the trace ID of the structured attempt.

Built-in enrichment, personalization, image inspection, and compaction forward available chat/turn references. Workflow AI forwards its workflow run ID and an existing user from the run's actor snapshot when available. System-owned work may legitimately have no user. Prompt, input, and output content are not added to the ledger.

Historical background records have no reliable user attribution and are not backfilled by guessing. The page shows the unassigned count, and selecting a specific user excludes these records. Choose Unassigned to inspect them. Background errors are limited to 2,000 stored characters; a detail view cannot recover text already truncated at storage time.

Use the CLI

The same service backs cld admin ai usage. JSON includes the server-resolved query, period, total count, page, and page size. List commands also accept --jsonl to emit one complete row per line from the requested page.

cld admin ai usage facets --field userId --search Ada --json
cld admin ai usage users --range 30d --sort negativeRate --json
cld admin ai usage feedback --user USER_UUID --model MODEL_ID --rating down --json
cld admin ai usage runs --kind background --status failed --search '404' --jsonl
cld admin ai usage get background RUN_UUID --json
cld admin ai usage report --range 7d --json

Other list commands are models, tasks, apps, launches, and capabilities. Use --provider-model and --app for additional global filtering, --reason for feedback, and --task or --error-code for run lists. --user unassigned selects events without a user. --page and --per-page control pagination; page size is 1–100. Reuse the returned query.until via --until when exporting multiple pages. JSONL does not fetch subsequent pages automatically.

For example, aggregate the negative counts returned for each user with jq, or retain full JSON reports for comparison with a later snapshot. The report contains user IDs as well as labels, so names do not become grouping keys.

HTTP and server interfaces

The Core endpoints are:

• GET /api/admin/core/ai-usage/report
• GET /api/admin/core/ai-usage/facets?field=userId&search=...
• GET /api/admin/core/ai-usage/runs/{chat|background|tool}/{uuid}

The report query supports range (24h, 7d, 30d, 90d), until (ISO), userId, modelProfileId, providerModel, appId, view, kind, status, task, errorCode, search, rating, reason, sort, page, and perPage. Invalid values are rejected before querying; unknown API parameters are rejected. Facet search returns at most the requested page size; refine the search to find an identifier beyond the suggestion list.

The server-only @k2b/cloud/ai/admin export supplies aiUsage.report(range, options), aiUsage.detail(kind, id), and aiUsage.facets(field, search, options). Applications using this internal admin surface must establish the administrator boundary before calling it. Report collections are paginated { items, page, perPage, total } objects; aggregate rows share measurement coverage and feedback counts. The browser-safe @k2b/cloud/shared export provides AiUsageQuerySchema, aiUsageSearchParams, and aiUsageHref for the same URL contract.