A valid request URL is required to generate request examples{
"rankings": [
{
"id": "<string>",
"name": "<string>",
"total_requests": 123,
"total_tokens": 123,
"total_cost": 123,
"trend": {
"has_previous_period": true,
"requests_trend": 123,
"tokens_trend": 123,
"cost_trend": 123
}
}
],
"dimension": "team",
"total_actual_requests": 123,
"total_attributed_requests": 123
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>"
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>"
}
}Get rankings by governance dimension
Returns the entities of one governance dimension ranked by spend, tokens
and request volume, with trend percentages versus the previous comparable
period. Requests carrying no value for the dimension are reported under an
Unassigned entry rather than dropped, so the rows reconcile with real
traffic.
Note that the accepted dimension values differ from the ones the
/by-dimension histogram endpoints take: rankings use project where the
histograms use project_id.
A valid request URL is required to generate request examples{
"rankings": [
{
"id": "<string>",
"name": "<string>",
"total_requests": 123,
"total_tokens": 123,
"total_cost": 123,
"trend": {
"has_previous_period": true,
"requests_trend": 123,
"tokens_trend": 123,
"cost_trend": 123
}
}
],
"dimension": "team",
"total_actual_requests": 123,
"total_attributed_requests": 123
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>"
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>"
}
}| Permission | Granted via |
|---|---|
Dashboard:View | RBAC role or API key scope |
Authorizations
Management API authentication for /api/* endpoints. Use the Authorization header
with Bearer <token>, where <token> is one of:
- a Bifrost management API key,
- a dashboard session token issued by
POST /api/session/login, - base64 of
<admin-username>:<admin-password>(legacy equivalent ofBasicAuth).
Virtual keys (sk-bf-*) and the x-api-key header are not accepted on management APIs -
the sole exception is GET /api/governance/virtual-keys/quota, which is virtual-key-only.
Authentication alone is not sufficient in Bifrost Enterprise: each operation page shows a
Required Permissions table (Resource:Operation, for example Dashboard:View) above
its Authorizations section, and the caller's RBAC role or management API key scopes must
include what it lists, otherwise the request is rejected with 403 Forbidden.
A local admin — authenticated with the admin password, or any caller on a deployment with dashboard auth disabled — bypasses these checks and can call every management endpoint.
OSS setup lock. On Bifrost OSS, while dashboard auth is not active (no admin account,
or auth disabled), every management endpoint except the public ones (/health,
/api/version, /api/session/is-auth-enabled, /api/session/login, ...) requires the
operator's setup token in the X-Bifrost-Setup-Token header, in place of Authorization.
The token is set with setup_token in config.json or the BIFROST_SETUP_TOKEN
environment variable. A missing header returns 401, a wrong token 403. The header
stops working once dashboard auth is enabled. The dashboard instead trades the token once
for an HttpOnly bifrost_setup_session cookie via POST /api/session/setup.
See Required permissions for how
permissions are derived and which endpoints are exempt.
Query Parameters
The governance dimension to rank by. Entity used to group dimension rankings
team, customer, business_unit, project, user, virtual_key, app, user_agent Comma-separated list of providers to filter by
Comma-separated list of models to filter by
Comma-separated list of model aliases to filter by
Comma-separated list of statuses to filter by
Comma-separated list of object types to filter by
Comma-separated list of selected key IDs to filter by
Comma-separated list of virtual key IDs to filter by
Comma-separated list of team IDs to filter by
Comma-separated list of customer IDs to filter by
Comma-separated list of user IDs to filter by
Comma-separated list of business unit IDs to filter by
Comma-separated list of project IDs to filter by
Comma-separated list of routing rule IDs to filter by
Comma-separated list of routing engines to filter by
Start time filter (RFC3339 format)
End time filter (RFC3339 format)
Relative time period filter
Minimum latency filter
Maximum latency filter
Minimum tokens filter
Maximum tokens filter
Minimum cost filter
Maximum cost filter
Only show logs with missing cost
Comma-separated list of stop reasons to filter by
Comma-separated list of function names. Matches requests whose response called any of them, using the persisted tool_call_names metadata on the log row. Names are recorded even when content logging is disabled and stay on the row in hybrid storage mode; the call arguments are not.
Comma-separated list of cache hit types to filter by
Parent request ID to filter by
Exact Bifrost session ID used for key stickiness and request correlation
Metadata filter where is the metadata key to match
Search in request/response content
Exact lookup on a log ID (which is the request ID). Takes precedence over the time range — start_time/end_time/period are ignored when it is set. roots_only is ignored too, so an ID naming a fallback child returns that child rather than collapsing it into its root.
Maximum number of ranked rows to return. Defaults to 100. Ignored when
all=true.
x >= 1When true, returns every ranked entity with no row cap. Intended for exports (CSV / PDF), which must not be truncated.
Response
Dimension rankings retrieved successfully
Dimension values ranked by usage with trend comparison
Show child attributes
Show child attributes
Entity used to group dimension rankings
team, customer, business_unit, project, user, virtual_key, app, user_agent Distinct request count over the attributed population. Only set for fan-out dimensions (team, customer, business_unit) on Postgres.
Requests credited to every dimension value they touch; the sum can exceed the real request count. Only set for fan-out dimensions.
Was this page helpful?