Get Route Health

Returns a per-route operational view of upstream health. Useful for dashboards, alerting integrations, and incident triage.

Route states

cooldown_reason explains why a route is in cooldown:

• rolling_failures — too many upstream errors in the rolling window.
• rate_limited — the upstream returned 429s faster than the route's retry policy could absorb them.

Recovery

Routes recover automatically as cooldown windows expire and probe traffic succeeds. To force a route back to healthy immediately — for example after an upstream incident is resolved — call POST /admin/llm-gw/route-health/{provider_id}/reset.

OpenAPI

get /admin/llm-gw/route-health
openapi: 3.1.0
info:
  title: Barndoor LLM Gateway API
  version: 1.0.0
  description: >
    REST API for the Barndoor LLM Gateway: configure providers, model routes,
    pricing, governance, and operate a multi-provider LLM platform programmatically.

## Base URL

All requests are issued against your Barndoor instance:

```
    https://app.barndoor.ai/api/llm-gateway
    ```

Replace `app.barndoor.ai` with your tenant host if you run on Enterprise.

## Authentication

Endpoints accept a JWT Bearer token issued by your Barndoor identity provider.
    The token must be sent in the `Authorization` header on every request:

```
    Authorization: Bearer eyJhbGciOi...
    ```

Note: the `bd-...` API keys you create through these endpoints are for
    runtime LLM traffic (`/v1/chat/completions`, `/v1/messages`, etc.), not for
    administrative calls.
    
    ## Errors

Errors are returned as JSON with a stable shape:

```json
    { "error": "BadRequest", "message": "request_timeout_secs must be between 1 and 3600" }
    ```
  contact:
    name: Barndoor Support
    url: https://barndoor.ai
servers:
  - url: https://{host}/api/llm-gateway
    description: >-
      Production / Trial (Barndoor SaaS). The gateway lives on your Barndoor
      control-plane host.
  - url: https://app.barndooruat.com/api/llm-gateway
    description: UAT
  - url: https://app.barndoordev.com/api/llm-gateway
    description: Dev
security:
  - BearerAuth: []
tags:
  - name: Route Health
    description: Operational view of upstream route ejection and recovery
paths:
  /admin/llm-gw/route-health:
    get:
      tags:
        - Route Health
      summary: Get route health
      description: |
        Returns a per-route operational view of upstream health: which routes
        are currently healthy, half-open (probing), or ejected (cooling
        down), along with consecutive-failure counts and recent state
        transitions. Useful for dashboards and incident triage.
      operationId: getRouteHealth
      responses:
        '200':
          description: Route health snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteHealthResponse'
components:
  schemas:
    RouteHealthResponse:
      type: object
      required:
        - routes
      properties:
        routes:
          type: array
          items:
            $ref: '#/components/schemas/RouteHealthEntry'
    RouteHealthEntry:
      type: object
      required:
        - provider_id
        - provider_name
        - model_provider
        - upstream_model
        - state
        - consecutive_failures
        - multiplier
      properties:
        provider_id:
          type: string
          format: uuid
        provider_name:
          type: string
        model_provider:
          $ref: '#/components/schemas/ModelProviderSlug'
        upstream_model:
          type: string
        state:
          type: string
          enum:
            - healthy
            - half_open
            - ejected
        eject_remaining_secs:
          type: integer
          nullable: true
        consecutive_failures:
          type: integer
        multiplier:
          type: integer
          description: Cooldown back-off multiplier
        in_flight:
          type: integer
          nullable: true
        concurrency_cap:
          type: integer
          nullable: true
        cooldown_reason:
          type: string
          nullable: true
          enum:
            - rolling_failures
            - rate_limited
        recent_transitions:
          type: array
          items:
            type: object
            properties:
              from:
                type: string
              to:
                type: string
              reason:
                type: string
              window_secs:
                type: integer
                nullable: true
              age_secs:
                type: integer
    ModelProviderSlug:
      type: string
      description: Slug of the upstream model provider this resource speaks to
      enum:
        - openai
        - anthropic
        - azure_openai
        - google_ai
        - bedrock
        - vertex
        - groq
        - together
        - mistral
        - cohere
        - xai
        - fireworks
        - perplexity
        - openrouter
        - deepseek
        - custom
      example: openai
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT obtained through Barndoor's authentication flow. Pass the token
        verbatim in `Authorization: Bearer <token>`. Use the Barndoor SDK's
        `loginInteractive()` helper to obtain a token in scripts and notebooks.