> ## Documentation Index > Fetch the complete documentation index at: https://bifrost-dev.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /openapi/openapi.json get /api/logs/rankings/by-dimension openapi: 3.1.0 info: title: Bifrost API description: > Bifrost HTTP Transport API for AI model inference and gateway management. This API provides a unified interface for interacting with multiple AI providers including OpenAI, Anthropic, Bedrock, Gemini, and more through a single API, along with comprehensive management APIs for configuring and monitoring the gateway. ## API Structure ### Unified Inference API (`/v1/*`) The primary API using Bifrost's unified format. Model parameters use the format `provider/model` (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`). ### Async Inference API (`/v1/async/*`) Submit inference requests for asynchronous execution. Returns a job ID immediately and allows polling for results. Supports all inference types except batches, files, and containers. ### Provider Integration APIs Native provider-format APIs for drop-in compatibility: - `/openai/*` - OpenAI-compatible API - `/anthropic/*` - Anthropic-compatible API - `/genai/*` - Google GenAI (Gemini) compatible API - `/bedrock/*` - AWS Bedrock compatible API - `/cohere/*` - Cohere compatible API ### Framework Integration APIs Multi-provider proxy endpoints for AI frameworks: - `/litellm/*` - LiteLLM proxy with all provider formats - `/langchain/*` - LangChain compatible endpoints - `/pydanticai/*` - PydanticAI compatible endpoints ### Management APIs (`/api/*`) APIs for managing and monitoring the Bifrost gateway: - `/api/config` - Configuration management - `/api/providers` - Provider and API key management - `/api/plugins` - Plugin management - `/api/governance/*` - Virtual keys, teams, customers, budgets, rate limits, routing rules, and pricing overrides - `/api/logs` - Log search and analytics - `/api/mcp/*` - MCP (Model Context Protocol) client management - `/api/session/*` - Authentication and session management - `/api/cache/*` - Cache management - `/health` - Health check endpoint ## Fallbacks Requests can include fallback models that will be tried if the primary model fails. version: 1.0.0 contact: name: Contact Us url: https://getmaxim.ai/bifrost license: name: Apache 2.0 url: https://opensource.org/licenses/Apache-2.0 servers: - url: '{baseUrl}' description: Your Bifrost instance variables: baseUrl: default: http://localhost:8080 description: Base URL of your Bifrost instance (e.g. https://bifrost.mycompany.com) security: - BearerAuth: [] - BasicAuth: [] - ApiKeyAuth: [] tags: - name: Models description: Model listing and information - name: Chat Completions description: Chat-based text generation - name: Text Completions description: Text completion generation - name: Responses description: OpenAI Responses API compatible endpoints - name: OCR description: Optical character recognition for documents and images - name: Rerank description: Document reranking by relevance to a query - name: Embeddings description: Text embedding generation - name: Images description: Image generations, editing, and variations - name: Videos description: Video generation and management - name: Audio description: Speech synthesis and transcription - name: Count Tokens description: Token counting utilities - name: Batch description: Batch processing operations - name: Files description: File management operations - name: Containers description: Container management operations - name: Async Jobs description: Asynchronous job submission and retrieval endpoints - name: Realtime description: Realtime WebSocket and WebRTC endpoints - name: OpenAI Integration description: OpenAI-compatible API endpoints (/openai/*) - name: Azure Integration description: Azure OpenAI integration endpoints - name: Anthropic Integration description: Anthropic-compatible API endpoints (/anthropic/*) - name: GenAI Integration description: Google GenAI (Gemini) compatible API endpoints (/genai/*) - name: Bedrock Integration description: AWS Bedrock compatible API endpoints (/bedrock/*) - name: Cohere Integration description: Cohere compatible API endpoints (/cohere/*) - name: LiteLLM Integration description: LiteLLM proxy endpoints with multi-provider support (/litellm/*) - name: LangChain Integration description: LangChain compatible endpoints with multi-provider support (/langchain/*) - name: PydanticAI Integration description: >- PydanticAI compatible endpoints with multi-provider support (/pydanticai/*) - name: Health description: Health check endpoints - name: Configuration description: Configuration management endpoints - name: Session description: Session and authentication endpoints - name: Providers description: Provider management endpoints - name: Plugins description: Plugin management endpoints - name: MCP description: Model Context Protocol endpoints - name: Governance description: Virtual keys, teams, and customers management - name: Routing description: Routing rules and complexity analyzer configuration - name: Logging description: Log search and management endpoints - name: Cache description: Cache management endpoints - name: Vault description: Vault secret management endpoints - name: Skills description: Skills Repository management, marketplace, and download endpoints - name: Audit Logs description: >- CADF-compliant audit log search, export, and signature verification endpoints - name: Webhooks description: Webhook endpoint management and signed async-job delivery history - name: Notifications description: >- Role-targeted dashboard notifications, delivered over the dashboard WebSocket paths: /api/logs/rankings/by-dimension: get: tags: - Logging summary: Get rankings by governance dimension description: > 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`. operationId: getDimensionRankings parameters: - name: dimension in: query required: true description: The governance dimension to rank by. schema: type: string description: Entity used to group dimension rankings enum: - team - customer - business_unit - project - user - virtual_key - app - user_agent - name: providers in: query description: Comma-separated list of providers to filter by schema: type: string - name: models in: query description: Comma-separated list of models to filter by schema: type: string - name: aliases in: query description: Comma-separated list of model aliases to filter by schema: type: string - name: status in: query description: Comma-separated list of statuses to filter by schema: type: string - name: objects in: query description: Comma-separated list of object types to filter by schema: type: string - name: selected_key_ids in: query description: Comma-separated list of selected key IDs to filter by schema: type: string - name: virtual_key_ids in: query description: Comma-separated list of virtual key IDs to filter by schema: type: string - name: team_ids in: query description: Comma-separated list of team IDs to filter by schema: type: string - name: customer_ids in: query description: Comma-separated list of customer IDs to filter by schema: type: string - name: user_ids in: query description: Comma-separated list of user IDs to filter by schema: type: string - name: business_unit_ids in: query description: Comma-separated list of business unit IDs to filter by schema: type: string - name: project_ids in: query description: Comma-separated list of project IDs to filter by schema: type: string - name: routing_rule_ids in: query description: Comma-separated list of routing rule IDs to filter by schema: type: string - name: routing_engine_used in: query description: Comma-separated list of routing engines to filter by schema: type: string - name: start_time in: query description: Start time filter (RFC3339 format) schema: type: string format: date-time - name: end_time in: query description: End time filter (RFC3339 format) schema: type: string format: date-time - name: period in: query description: Relative time period filter schema: type: string - name: min_latency in: query description: Minimum latency filter schema: type: number - name: max_latency in: query description: Maximum latency filter schema: type: number - name: min_tokens in: query description: Minimum tokens filter schema: type: integer - name: max_tokens in: query description: Maximum tokens filter schema: type: integer - name: min_cost in: query description: Minimum cost filter schema: type: number - name: max_cost in: query description: Maximum cost filter schema: type: number - name: missing_cost_only in: query description: Only show logs with missing cost schema: type: boolean - name: stop_reasons in: query description: Comma-separated list of stop reasons to filter by schema: type: string - name: cache_hit_types in: query description: Comma-separated list of cache hit types to filter by schema: type: string - name: parent_request_id in: query description: Parent request ID to filter by schema: type: string - name: session_id in: query description: >- Exact Bifrost session ID used for key stickiness and request correlation schema: type: string - name: metadata_ in: query description: Metadata filter where is the metadata key to match schema: type: string - name: content_search in: query description: Search in request/response content schema: type: string - name: request_id in: query description: >- 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. schema: type: string - name: limit in: query description: > Maximum number of ranked rows to return. Defaults to 100. Ignored when `all=true`. schema: type: integer minimum: 1 default: 100 - name: all in: query description: | When true, returns every ranked entity with no row cap. Intended for exports (CSV / PDF), which must not be truncated. schema: type: boolean default: false responses: '200': description: Dimension rankings retrieved successfully content: application/json: schema: type: object description: Dimension values ranked by usage with trend comparison properties: rankings: type: array items: allOf: - type: object description: >- Aggregated usage for a single dimension value (team, user, virtual key, etc.) properties: id: type: string name: type: string total_requests: type: integer format: int64 total_tokens: type: integer format: int64 total_cost: type: number - type: object properties: trend: type: object description: >- Percentage change versus the previous comparable period properties: has_previous_period: type: boolean requests_trend: type: number tokens_trend: type: number cost_trend: type: number dimension: type: string description: Entity used to group dimension rankings enum: - team - customer - business_unit - project - user - virtual_key - app - user_agent total_actual_requests: type: integer format: int64 description: > Distinct request count over the attributed population. Only set for fan-out dimensions (team, customer, business_unit) on Postgres. total_attributed_requests: type: integer format: int64 description: > Requests credited to every dimension value they touch; the sum can exceed the real request count. Only set for fan-out dimensions. '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BifrostError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BifrostError' security: - ManagementBearerAuth: [] components: schemas: BifrostError: type: object description: Error response from Bifrost properties: event_id: type: string type: type: string is_bifrost_error: type: boolean status_code: type: integer error: $ref: '#/components/schemas/ErrorField' extra_fields: $ref: '#/components/schemas/BifrostErrorExtraFields' ErrorField: type: object properties: type: type: string code: type: string message: type: string param: type: string event_id: type: string BifrostErrorExtraFields: type: object properties: provider: $ref: '#/components/schemas/ModelProvider' model_requested: type: string request_type: type: string ModelProvider: type: string description: AI model provider identifier enum: - anthropic - azure - bedrock - bedrock_mantle - cerebras - cohere - deepseek - gemini - groq - mistral - ollama - opencode-go - opencode-zen - openai - parasail - perplexity - sgl - vertex - openrouter - elevenlabs - huggingface - nebius - xai - replicate - vllm - runway - runware - fireworks - sarvam - wafer - databricks securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Use your provider API key or Bifrost authentication token. Virtual keys (prefixed with `sk-bf-`) can also be passed here. BasicAuth: type: http scheme: basic description: | Basic authentication using username and password. ApiKeyAuth: type: apiKey in: header name: x-api-key description: | API key authentication via the `x-api-key` header. Virtual keys (prefixed with `sk-bf-`) can also be passed here. ManagementBearerAuth: type: http scheme: bearer description: > Management API authentication for `/api/*` endpoints. Use the `Authorization` header with `Bearer `. Virtual keys, dashboard/user/session tokens, and `x-api-key` headers are not supported on management APIs. ````