> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List phrase suggestion runs

> Lists suggestion runs newest first, scheduled and manual, with what each read, created, refreshed and superseded, what its model calls cost, and why it failed if it did. The latest 200 runs are kept.


**Required Permissions**

| Permission | Granted via |
| - | - |
| `Routers:View` | RBAC role or API key scope |

[How permissions work](https://docs.getbifrost.ai/api/procuring-api-keys.md#required-permissions)


## OpenAPI

````yaml /openapi/openapi.json get /api/routing/model-routers/{router_id}/suggestions/runs
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,
          or https://mycompany.com/bifrost when served under server.base_path)
security:
  - BearerAuth: []
  - BasicAuth: []
  - ApiKeyAuth: []
tags:
  - name: Agent Gateway
    description: >-
      Agent registrations, A2A protocol calls, push callbacks, and operation
      history
  - 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: Decisions
    description: Structured decisions evaluated against annotated function-tool definitions
  - 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: Typesafe Integration
    description: Typesafe compatible API endpoints (/typesafe/*)
  - 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
  - name: News Feeds
    description: >-
      RSS and Atom news sources shown in the News tab of the dashboard
      notification tray
  - name: Background Jobs
    description: >-
      Status, progress and cancellation of durable background jobs (cost
      recalculation, Warp log indexing, and others)
  - name: Warp
    description: >-
      Configuration for Warp, the dashboard agent that answers questions about
      the deployment's own telemetry
  - name: Relays
    description: >-
      Relays to non-LLM HTTP APIs - endpoint management, usage preview, Relay
      Logs and the /relay data plane
paths:
  /api/routing/model-routers/{router_id}/suggestions/runs:
    get:
      tags:
        - Routing
      summary: List phrase suggestion runs
      description: >
        Lists suggestion runs newest first, scheduled and manual, with what each
        read, created, refreshed and superseded, what its model calls cost, and
        why it failed if it did. The latest 200 runs are kept.
      operationId: listComplexitySuggestionRuns
      parameters:
        - name: router_id
          in: path
          required: true
          description: The model router; an unknown router is 404.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
      responses:
        '200':
          description: Runs retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  runs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        router_id:
                          type: string
                        router_version:
                          type: string
                        window_start:
                          type: string
                          format: date-time
                          description: >-
                            Start of the window the run read; it ends at
                            started_at.
                        triggered_by:
                          type: string
                          enum:
                            - schedule
                            - manual
                        status:
                          type: string
                          enum:
                            - queued
                            - skipped
                            - running
                            - succeeded
                            - failed
                            - cancelled
                          description: >-
                            cancelled runs were stopped by a user; what they had
                            written is kept.
                        stage:
                          type: string
                          enum:
                            - backfilling
                            - reading
                            - clustering
                            - suggesting
                            - saving
                          description: How far a running run got; absent once it ends.
                        embedding_signature:
                          type: string
                        model:
                          type: string
                          description: provider/model the suggestions were written with.
                        prompt_hash:
                          type: string
                          description: >-
                            SHA-256 of the instructions and tier guidance in
                            force.
                        requests_read:
                          type: integer
                          description: Captured requests in the window.
                        requests_clustered:
                          type: integer
                          description: The sample the clusters were formed from.
                        requests_assigned:
                          type: integer
                          description: Requests counted into the clusters after the sample.
                        requests_skipped:
                          type: integer
                          description: >-
                            Requests past the counting bound, read into no
                            cluster.
                        requests_grouped:
                          type: integer
                          description: Requests in clusters big enough to keep.
                        clusters:
                          type: integer
                        clusters_decided:
                          type: integer
                          description: >-
                            Clusters matching an accepted or dismissed
                            suggestion, not asked about again.
                        clusters_over_limit:
                          type: integer
                          description: >-
                            Clusters not suggested because of this run's limits:
                            past the bound on clusters asked per run, or after
                            the phrases already written filled the room left in
                            the phrase bank.
                        clusters_asked:
                          type: integer
                        clusters_done:
                          type: integer
                          description: >-
                            Clusters asked about so far; equals clusters_asked
                            once the run ends.
                        clusters_failed:
                          type: integer
                        clusters_covered:
                          type: integer
                          description: Clusters the phrase bank already routes well.
                        clusters_incoherent:
                          type: integer
                          description: >-
                            Clusters that were not one kind of request, or got
                            no usable answer.
                        clusters_unreadable:
                          type: integer
                          description: >-
                            Clusters none of whose example requests could be
                            read back.
                        created:
                          type: integer
                        refreshed:
                          type: integer
                        superseded:
                          type: integer
                        cost:
                          type: number
                          description: Cost of the run's suggestion-model calls, in USD.
                        error:
                          type: string
                          description: >-
                            Why the run failed, why a skipped run did not start,
                            or, on a run that succeeded, the clusters it left
                            for the next run.
                        started_at:
                          type: string
                          format: date-time
                        finished_at:
                          type: string
                          format: date-time
                  next_run_at:
                    type: string
                    format: date-time
        '400':
          description: Invalid limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '404':
          description: The model router is not saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '500':
          description: The runs could not be read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '503':
          description: >-
            Phrase suggestions are not available (no log store, or the routing
            plugin is not loaded), or the model router is saved but not loaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
      security:
        - ManagementBearerAuth: []
        - BasicAuth: []
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:
        routing_info:
          $ref: '#/components/schemas/RoutingInfo'
        provider:
          $ref: '#/components/schemas/ModelProvider'
          deprecated: true
          description: 'Deprecated: use routing_info.provider.'
        original_model_requested:
          type: string
          deprecated: true
          description: >-
            Deprecated: use routing_info.primary_model when
            routing_info.is_fallback is true, otherwise routing_info.model. For
            the model the caller asked for, read routing_info.requested_model.
        resolved_model_used:
          type: string
          deprecated: true
          description: >-
            Deprecated: use routing_info.resolved_key_alias.model_id when an
            alias matched, otherwise routing_info.model.
        request_type:
          type: string
        mcp_request_type:
          type: string
        a2a_request_type:
          type: string
          description: Agent Gateway operation, for A2A errors
        a2a_agent_name:
          type: string
        error_type:
          type: string
          description: >-
            Normalized, low-cardinality classification of why the request
            failed, declared by whichever component refused it. Prefixed by
            fault domain (caller_, policy_, provider_, bifrost_). Absent on
            failures that were not classified at source.
        retry_after_ms:
          type: integer
          format: int64
          minimum: 1000
          maximum: 300000
          description: >-
            The provider's hint for how long to wait before retrying, in
            milliseconds, read from its retry-after-ms or Retry-After header or
            its google.rpc.RetryInfo error detail, and clamped to between 1000
            and 300000. Absent when the provider gave no explicit hint.
        raw_request:
          description: Raw provider request, when raw request capture is enabled
        raw_response:
          description: Raw provider response, when raw response capture is enabled
        converted_request_type:
          type: string
        dropped_compat_plugin_params:
          type: array
          items:
            type: string
        latency:
          type: integer
          format: int64
          description: Latency in milliseconds
        key_statuses:
          type: array
          description: >-
            Per-key results, for requests that ran on every key such as listing
            models
          items:
            type: object
            properties:
              key_id:
                type: string
              status:
                type: string
                enum:
                  - success
                  - list_models_failed
              provider:
                $ref: '#/components/schemas/ModelProvider'
              error:
                $ref: '#/components/schemas/BifrostError'
        fallback_attempts:
          type: array
          description: >-
            Set when the primary and every fallback failed and the primary's
            error was returned: what became of each fallback, in chain order. A
            fallback refused before reaching its provider (for example by a
            virtual key that does not allow it) is only visible here.
          items:
            type: object
            properties:
              provider:
                $ref: '#/components/schemas/ModelProvider'
              model:
                type: string
              status_code:
                type: integer
              type:
                type: string
              message:
                type: string
              skipped:
                type: boolean
                description: >-
                  The fallback was never attempted (no provider config, or the
                  request type has no fallback support)
        mcp_auth_required:
          type: object
          description: >-
            Set when a per-user MCP tool needs the caller to complete an inline
            auth flow
          properties:
            kind:
              type: string
            mcp_client_id:
              type: string
            mcp_client_name:
              type: string
            message:
              type: string
            authorize_url:
              type: string
            session_id:
              type: string
            subject_token_missing:
              type: boolean
              description: >-
                token_exchange only. True when there was nothing to exchange,
                including when the caller's Bifrost sign-in has expired; message
                says which
            exchange_error:
              type: string
              description: >-
                token_exchange only. The identity provider's error code and
                description when it refused the exchange
        billed_usage:
          $ref: '#/components/schemas/BifrostLLMUsage'
          description: >-
            Usage the provider reported and billed even though the request
            failed
    RoutingInfo:
      type: object
      description: >-
        Which provider, model and key handled the attempt that produced this
        response or error, and what the caller asked for. Also sent as
        x-bifrost-routing-info-* response headers.
      properties:
        provider:
          $ref: '#/components/schemas/ModelProvider'
          description: Provider that ran the attempt
        model:
          type: string
          description: Model sent to that provider
        key:
          type: string
          description: Name of the stored key used, never its ID or secret
        resolved_key_alias:
          $ref: '#/components/schemas/ResolvedKeyAlias'
        is_fallback:
          type: boolean
          description: >-
            True when a fallback served the request or returned the error.
            Omitted when false.
        primary_provider:
          $ref: '#/components/schemas/ModelProvider'
          description: The primary attempt's provider. Set only when a fallback ran.
        primary_model:
          type: string
          description: The primary attempt's model. Set only when a fallback ran.
        requested_provider:
          $ref: '#/components/schemas/ModelProvider'
          description: >-
            Provider the caller asked for, before routing rules, load balancing
            or session affinity changed it. Omitted when the caller sent a bare
            model.
        requested_model:
          type: string
          description: Model the caller asked for, before anything changed it
        server_side_fallback_model:
          type: string
          description: Model that answered when Anthropic switched models inside one call
    ModelProvider:
      type: string
      description: AI model provider identifier
      enum:
        - anthropic
        - azure
        - bedrock
        - bedrock_mantle
        - sagemaker
        - 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
        - cloudflare
        - typesafe
        - minimax
        - byteplus
        - machgen
        - baseten
        - kimchi
        - soniox
    BifrostLLMUsage:
      type: object
      description: Token usage information
      properties:
        prompt_tokens:
          type: integer
          description: >
            Total input tokens including any prompt-cache tokens (read + write).
            Subtract prompt_tokens_details.cached_read_tokens and
            prompt_tokens_details.cached_write_tokens to get the non-cached
            portion.
        prompt_tokens_details:
          $ref: '#/components/schemas/ChatPromptTokensDetails'
        completion_tokens:
          type: integer
          description: Number of output/completion tokens generated.
        completion_tokens_details:
          $ref: '#/components/schemas/ChatCompletionTokensDetails'
        total_tokens:
          type: integer
        tool_usage:
          type: object
          description: |
            Counts of provider-hosted (server-side) tool calls billed per call.
          properties:
            web_search:
              type: object
              properties:
                num_requests:
                  type: integer
                  description: Number of billable web search calls.
        cost:
          $ref: '#/components/schemas/BifrostCost'
    ResolvedKeyAlias:
      type: object
      description: Set only when the requested model matched a model alias on the key
      required:
        - model_id
      properties:
        model_id:
          type: string
          description: Model ID sent to the provider
        model_name:
          type: string
          description: Canonical model name, used for pricing and logs
        model_family:
          type: string
          description: Resolved model family
    ChatPromptTokensDetails:
      type: object
      properties:
        text_tokens:
          type: integer
        audio_tokens:
          type: integer
        image_tokens:
          type: integer
        cached_read_tokens:
          type: integer
          description: >
            Tokens served from the prompt cache (cache hit). These tokens are
            already included in prompt_tokens and are billed at the reduced
            cache-read rate. Populated for all providers that support prompt
            caching (Anthropic, Bedrock, OpenAI, Gemini, xAI, etc.).
        cached_write_tokens:
          type: integer
          description: >
            Tokens written to the prompt cache on this request (cache creation /
            write). These tokens are already included in prompt_tokens and are
            billed at the cache-creation rate. Populated for providers that
            separately report cache write tokens (Anthropic, Bedrock).
    ChatCompletionTokensDetails:
      type: object
      properties:
        text_tokens:
          type: integer
        accepted_prediction_tokens:
          type: integer
        audio_tokens:
          type: integer
        citation_tokens:
          type: integer
        num_search_queries:
          type: integer
          deprecated: true
          description: >-
            Deprecated, use tool_usage.web_search.num_requests. Will be removed
            in 3.0.0.
        reasoning_tokens:
          type: integer
        image_tokens:
          type: integer
        rejected_prediction_tokens:
          type: integer
    BifrostCost:
      type: object
      description: Cost breakdown for the request
      properties:
        input_tokens_cost:
          type: number
        output_tokens_cost:
          type: number
        reasoning_tokens_cost:
          type: number
          description: Cost for reasoning/thinking tokens (reasoning models)
        citation_tokens_cost:
          type: number
          description: Cost for citation tokens
        search_queries_cost:
          type: number
          description: Cost for web search queries
        request_cost:
          type: number
        total_cost:
          type: number
  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 the Bifrost admin username and password

        (`auth_config.admin_username` / `auth_config.admin_password`).

        Accepted on management APIs (`/api/*`, `/metrics`, `/ws`) only - the
        inference

        middleware never validates Basic credentials.
    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 <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.


        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](/api/procuring-api-keys#required-permissions)
        for how

        permissions are derived and which endpoints are exempt.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.