Skip to main content

Analytics

Analytics endpoints provide usage metrics, credit tracking, and trend analysis for agents across your organization.
All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.
Requires authentication and is scoped to the caller’s own organization — a non-superadmin’s organizationId query parameter is ignored (their own org is always queried), and a non-superadmin who names a different organization gets 403. A platform superadmin may pass organizationId to widen the scope. Every response reports credits, never provider USD — there is no cost/$/usd field anywhere in this plugin’s responses. (Before 2026-09-29 / PR #536 this lane had no authentication at all — BSIO-450.)

Overview Metrics

Get high-level usage metrics with trend comparisons against the previous period.

Query Parameters

string
required
Organization UUID.
string
required
Start of the reporting period (ISO 8601 date string).
string
required
End of the reporting period (ISO 8601 date string).
string
Filter to a specific agent UUID.
string
Filter to a specific model ID.

Response (200)

Returns current period metrics with trend indicators compared to the equivalent previous period:
object
object
Message count with trend.
object
Token usage with trend.
object
Credits burned with trend (trend.credits / trend.creditsChange). Summed from token_usage.credits_burned — never provider USD.
number
Total priced requests in the period.
number
totalCredits / totalRequests.
number
Requests whose cost could not be matched to a priced event (credits_burned = 0 with no resolvable charge) — not the same as a request that genuinely cost nothing. Surfaces UsageSummary.unpricedTurns.
object
Response time in ms with trend.

Daily Breakdown

Get day-by-day usage breakdown for charting.

Query Parameters

Same as Overview Metrics.

Response (200)

Returns an array of daily data points with conversation counts, message counts, token usage, and credits (credits burned that day) for each day.

Model Usage

Get usage breakdown by AI model, showing which models are used most.

Query Parameters

Same as Overview Metrics.

Response (200)

Returns per-model aggregates including message count, token usage, and credits (credits burned, not provider cost).

Agent Usage

Get usage breakdown by agent.

Query Parameters

Same as Overview Metrics.

Response (200)

Returns per-agent aggregates including conversation count, message count, and credits (credits burned, not provider cost).

Realtime Metrics

Get recent activity metrics for live dashboards.

Query Parameters

string
required
Organization UUID.
string
ISO 8601 timestamp. Only return activity after this time. Defaults to last 15 minutes.

Response (200)

Returns recent conversation and message counts, active users, current response times, and creditsToday (credits burned so far today).