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

# Preview alias routing

> Simulate the routing resolution for this alias as it would happen at request time.

Returns the model that would be selected as primary, the ordered list of fallbacks, and any models currently excluded from routing (e.g. because they are unhealthy).

This is useful for debugging alias configuration and verifying that health checks and priority settings produce the expected routing outcome.



## OpenAPI

````yaml /api-reference/openapi-v3.yaml get /api/v3/aliases/{id}/route
openapi: 3.1.0
info:
  title: LightOn API
  version: 3.15.0 (v3)
  description: >-
    LightOn gives you an API to search, parse, and ingest documents at scale.
    Build knowledge-retrieval pipelines without managing vector databases or OCR
    models.
servers:
  - url: https://paradigm.lighton.ai
security: []
tags:
  - name: Agents
    description: Operations about agents
  - name: Threads
    description: Operations about agents conversation threads
  - name: Tools
    description: Operations about native tools
  - name: Models
    description: Operations about AI models
  - name: MCP
    description: Operations about MCP servers
  - name: Sources
    description: Operations about sources used by agents conversation threads
  - name: Artifacts
    description: Operations about artifacts generated by agents conversation threads
  - name: Agent
    description: >-
      Operations about agents (deprecated). Please use the 'Agents' API
      component instead.
  - name: Files
    description: Operations about files
  - name: Facets
    description: Operations about facets
  - name: Tags
    description: Operations about tags
  - name: Workspaces
    description: Operations about workspaces
  - name: Files Processing
    description: Operations about files processing
  - name: Users
    description: Operations about users
  - name: API Keys
    description: Operations about API keys
  - name: User Groups
    description: Operations about user groups
  - name: SCIM
    description: Operations about SCIM
paths:
  /api/v3/aliases/{id}/route:
    get:
      tags:
        - Models
      summary: Preview alias routing
      description: >-
        Simulate the routing resolution for this alias as it would happen at
        request time.


        Returns the model that would be selected as primary, the ordered list of
        fallbacks, and any models currently excluded from routing (e.g. because
        they are unhealthy).


        This is useful for debugging alias configuration and verifying that
        health checks and priority settings produce the expected routing
        outcome.
      operationId: api_v3_aliases_route_retrieve
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AliasRoutingResult'
          description: ''
        '503':
          description: >-
            API is under maintenance. Check `GET /api/v3/system/status` for
            active periods and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMaintenance503'
      security:
        - bearerAuth: []
components:
  schemas:
    AliasRoutingResult:
      type: object
      properties:
        primary:
          allOf:
            - $ref: '#/components/schemas/AliasRoutingModelRef'
          description: The model that would be selected as primary for inference
        fallbacks:
          type: array
          items:
            $ref: '#/components/schemas/AliasRoutingModelRef'
          default: []
          description: Ordered fallback models, from highest to lowest priority
        excluded:
          type: array
          items:
            $ref: '#/components/schemas/AliasRoutingExcludedModel'
          default: []
          description: Models excluded from routing (e.g. currently unhealthy)
      required:
        - primary
    ServiceMaintenance503:
      type: object
      description: >-
        Returned by the maintenance middleware when the requested endpoint is
        blocked.
      required:
        - detail
        - error
        - mode
      properties:
        detail:
          type: string
          example: System is under maintenance.
        error:
          type: string
          example: service_maintenance
        mode:
          type: string
          enum:
            - full_shutdown
            - warning_banner
          description: >-
            `full_shutdown` blocks all traffic; `warning_banner` also blocks and
            shows a dismissible toast.
        reason:
          type: string
          description: Operator-supplied maintenance reason, if any.
        started_at:
          type: string
          format: date-time
        endpoint_category_names:
          type: array
          items:
            type: string
          description: >-
            Non-empty only for category-scoped periods. Empty means all
            endpoints are affected.
    AliasRoutingModelRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID of the model
        name:
          type: string
          description: Display name of the model
        technical_name:
          type: string
          description: Technical name of the model
      required:
        - id
        - name
        - technical_name
    AliasRoutingExcludedModel:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID of the model
        name:
          type: string
          description: Display name of the model
        technical_name:
          type: string
          description: Technical name of the model
        reason:
          type: string
          description: Reason the model was excluded from routing (e.g. 'unhealthy')
      required:
        - id
        - name
        - reason
        - technical_name
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````