Get model usage rankings

Returns models ranked by usage with trend percentages versus the previous comparable period. Accepts the same filter parameters as the histogram endpoints.

GET /api/logs/rankings

Error

A valid request URL is required to generate request examples

200

{
  "rankings": [
    {
      "model": "<string>",
      "provider": "<string>",
      "total_requests": 123,
      "success_count": 123,
      "success_rate": 123,
      "total_tokens": 123,
      "total_cost": 123,
      "avg_latency": 123,
      "trend": {
        "has_previous_period": true,
        "requests_trend": 123,
        "tokens_trend": 123,
        "cost_trend": 123,
        "latency_trend": 123
      }
    }
  ]
}

Authorizations

Authorization · string · header · required

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 of BasicAuth).

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

providers · string

Comma-separated list of providers to filter by

models · string

Comma-separated list of models to filter by

aliases · string

Comma-separated list of model aliases to filter by

status · string

Comma-separated list of statuses to filter by

objects · string

Comma-separated list of object types to filter by

selected_key_ids · string

Comma-separated list of selected key IDs to filter by

virtual_key_ids · string

Comma-separated list of virtual key IDs to filter by

team_ids · string

Comma-separated list of team IDs to filter by

customer_ids · string

Comma-separated list of customer IDs to filter by

user_ids · string

Comma-separated list of user IDs to filter by

business_unit_ids · string

Comma-separated list of business unit IDs to filter by

project_ids · string

Comma-separated list of project IDs to filter by

routing_rule_ids · string

Comma-separated list of routing rule IDs to filter by

routing_engine_used · string

Comma-separated list of routing engines to filter by

start_time · string<date-time>

Start time filter (RFC3339 format)

end_time · string<date-time>

End time filter (RFC3339 format)

period · string

Relative time period filter

min_latency · number

Minimum latency filter

max_latency · number

Maximum latency filter

min_tokens · integer

Minimum tokens filter

max_tokens · integer

Maximum tokens filter

min_cost · number

Minimum cost filter

max_cost · number

Maximum cost filter

missing_cost_only · boolean

Only show logs with missing cost

stop_reasons · string

Comma-separated list of stop reasons to filter by

tool_call_names · string

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.

cache_hit_types · string

Comma-separated list of cache hit types to filter by

parent_request_id · string

Parent request ID to filter by

session_id · string

Exact Bifrost session ID used for key stickiness and request correlation

metadata_<key> · string

Metadata filter where is the metadata key to match

content_search · string

Search in request/response content

request_id · string

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.

limit · integer · default: 100

Maximum number of ranked rows to return. Defaults to 100. Ignored when all=true.

Required range: x >= 1

all · boolean · default: false

When true, returns every ranked entity with no row cap. Intended for exports (CSV / PDF), which must not be truncated.

Response

200

application/json

Model rankings retrieved successfully

Models ranked by usage with trend comparison

rankings · object[]

Show child attributes