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>"
}
}{
"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>"
}
}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>"
}
}{
"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>"
}
}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.
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?