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

# Models (Beta)

> Browse gateway-native models through AI Stats Gateway, including optional non-routable availability details.

Returns the public gateway catalogue for gateway-visible models. By default the route only returns models that are currently publicly routable through the gateway. Set `availability=all` to include models that are known but not currently routable, along with provider-level availability status.

Notes:

* `endpoints` use public names like `chat.completions`, `responses`, and `messages`.
* `status` filters by the canonical model lifecycle state, for example `active`, `deprecated`, or `retired`.
* `provider` filters by public provider id, for example `openai`, `anthropic`, or `google_vertex`.
* `provider_status` filters the provider rollout tier inside each model, for example `active`, `beta`, `alpha`, or `not_ready`.
* `provider_routing_status` filters the provider-level routing gate for the mapping, for example `active`, `deranked_lvl1`, `deranked_lvl2`, `deranked_lvl3`, or `disabled`.
* `model_routing_status` filters the model-level routing gate for the mapping, using the same routing-state values.
* `capability_status` filters the provider capability state for the requested endpoint mapping, for example `active`, `coming_soon`, `internal_testing`, `disabled`, or a deranked state.
* `provider_availability_status` filters the provider-side rollout state inside each model, for example `active`, `coming_soon`, or `inactive`.
* `provider_availability_reason` filters the provider-side rollout explanation, for example `preview_only`, `provider_not_ready`, `gated`, `access_limited`, `region_limited`, `project_limited`, `paused`, `soft_blocked`, `scheduled`, `provider_disabled`, `model_disabled`, or `internal_testing`.
* `organisation` filters by the prefix in the public model ID, for example `anthropic` in `anthropic/claude-3-haiku`.
* `privacy_scope=shared` is supported today. `privacy_scope=team` is reserved and currently returns `501`.
* `availability=active` is the default and keeps the response limited to currently servable routes.
* `availability=all` includes models or providers that are `coming_soon`, `inactive`, or not yet listed as routable.
* Future-dated `effective_from` mappings and `internal_testing` capabilities stay hidden from the default active catalogue, but appear as `coming_soon` under `availability=all` so upcoming activations can be prepared safely before public rollout.
* Provider entries can now expose:
  * `availability_status`
  * `availability_reason`
  * `provider_status`
  * `provider_routing_status`
  * `model_routing_status`
  * `capability_status`

### Response

```json theme={null}
{
  "ok": true,
  "privacy_scope": "shared",
  "availability_mode": "all",
  "limit": 50,
  "offset": 0,
  "total": 99,
  "models": [
    {
      "id": "anthropic/claude-3-haiku",
      "canonical_slug": "anthropic/claude-3-haiku",
      "model_id": "anthropic/claude-3-haiku",
      "name": "anthropic/claude-3-haiku",
      "description": "anthropic/claude-3-haiku via AI Stats Gateway. Supports chat.completions, messages, responses.",
      "created": null,
      "release_date": null,
      "deprecation_date": null,
      "retirement_date": null,
      "status": "active",
      "availability": {
        "status": "coming_soon",
        "provider_count": 1,
        "active_provider_count": 0,
        "inactive_provider_count": 0
      },
      "organisation_id": "anthropic",
      "organisation_name": null,
      "organisation_colour": null,
      "aliases": [],
      "endpoints": ["chat.completions", "messages", "responses"],
      "input_types": ["text"],
      "output_types": ["text"],
      "architecture": {
        "modality": "text->text",
        "input_modalities": ["text"],
        "output_modalities": ["text"],
        "tokenizer": null,
        "instruct_type": "chat"
      },
      "providers": [
        {
          "api_provider_id": "anthropic",
          "api_provider_name": "Anthropic",
          "is_active_gateway": false,
          "availability_status": "coming_soon",
          "availability_reason": "preview_only",
          "provider_status": "beta",
          "provider_routing_status": "active",
          "model_routing_status": "active",
          "capability_status": "coming_soon",
          "effective_from": "2026-06-01T00:00:00Z",
          "effective_to": null,
          "endpoints": ["responses"],
          "params": [
            "max_tokens",
            "response_format",
            "stop",
            "structured_outputs",
            "temperature",
            "tool_choice",
            "tools",
            "top_k",
            "top_p"
          ]
        }
      ],
      "supported_params": [
        "max_tokens",
        "response_format",
        "stop",
        "structured_outputs",
        "temperature",
        "tool_choice",
        "tools",
        "top_k",
        "top_p"
      ],
      "supported_parameters": [
        "max_tokens",
        "response_format",
        "stop",
        "structured_outputs",
        "temperature",
        "tool_choice",
        "tools",
        "top_k",
        "top_p"
      ],
      "top_provider_id": null,
      "top_provider": {
        "context_length": null,
        "max_completion_tokens": null,
        "is_moderated": false
      },
      "pricing": {
        "prompt": null,
        "completion": null,
        "request": null,
        "image": null,
        "input_cache_read": null,
        "input_cache_write": null,
        "web_search": null
      },
      "pricing_detail": {
        "pricing_plan": "standard",
        "meters": {}
      },
      "per_request_limits": null
    }
  ]
}
```

`availability_reason` is the stable single-field explanation for why a provider entry is active, preview-only, or inactive. It mirrors the main rollout/routability states already encoded by the lower-level status fields, for example `preview_only`, `provider_not_ready`, `gated`, `access_limited`, `region_limited`, `project_limited`, `paused`, `soft_blocked`, `scheduled`, `coming_soon`, `internal_testing`, `provider_disabled`, `model_disabled`, `capability_disabled`, `provider_inactive`, `inactive`, or `retired`.


## OpenAPI

````yaml GET /gateway/models
openapi: 3.0.3
info:
  title: AI Stats Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: AI Stats
    url: https://docs.ai-stats.phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core AI Stats Gateway operations.
paths:
  /gateway/models:
    get:
      tags:
        - Gateway
      summary: List gateway models
      description: >-
        Returns shared non-hidden gateway models. Defaults to currently publicly
        routable models; use availability=all to include non-routable
        availability records.
      operationId: listModels
      parameters:
        - name: endpoints
          in: query
          description: Filter by endpoints
          schema:
            type: array
            items:
              type: string
        - name: organisation
          in: query
          description: Filter by organisation
          schema:
            oneOf:
              - $ref: '#/components/schemas/OrganisationId'
              - type: array
                items:
                  $ref: '#/components/schemas/OrganisationId'
        - name: provider
          in: query
          description: Filter by provider id
          schema:
            type: array
            items:
              type: string
        - name: provider_status
          in: query
          description: Filter by provider rollout status
          schema:
            type: array
            items:
              type: string
        - name: provider_routing_status
          in: query
          description: Filter by provider routing status
          schema:
            type: array
            items:
              type: string
        - name: model_routing_status
          in: query
          description: Filter by model routing status
          schema:
            type: array
            items:
              type: string
        - name: capability_status
          in: query
          description: Filter by provider capability status
          schema:
            type: array
            items:
              type: string
        - name: provider_availability_status
          in: query
          description: Filter by provider availability status
          schema:
            type: array
            items:
              type: string
        - name: provider_availability_reason
          in: query
          description: Filter by provider availability reason
          schema:
            type: array
            items:
              type: string
        - name: status
          in: query
          description: Filter by model status
          schema:
            type: array
            items:
              type: string
        - name: input_types
          in: query
          description: Filter by input types
          schema:
            type: array
            items:
              type: string
        - name: output_types
          in: query
          description: Filter by output types
          schema:
            type: array
            items:
              type: string
        - name: params
          in: query
          description: Filter by params
          schema:
            type: array
            items:
              type: string
        - name: availability
          in: query
          description: >-
            Availability filter. active returns publicly routable models only;
            all includes non-routable availability records.
          schema:
            type: string
            enum:
              - active
              - all
            default: active
        - name: limit
          in: query
          description: Limit the number of results
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 250
        - name: offset
          in: query
          description: Offset for pagination
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 5000
        - name: format
          in: query
          description: Response format. Defaults to json.
          schema:
            type: string
            enum:
              - json
              - rss
              - atom
            default: json
        - name: feed
          in: query
          description: Alias for format. Accepts json, rss, or atom.
          schema:
            type: string
            enum:
              - json
              - rss
              - atom
      responses:
        '200':
          description: List of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayModelsResponse'
            application/rss+xml:
              schema:
                type: string
                description: RSS 2.0 XML feed
            application/atom+xml:
              schema:
                type: string
                description: Atom XML feed
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    OrganisationId:
      type: string
      description: Organisation identifier.
      enum:
        - ai21
        - aion-labs
        - allenai
        - amazon
        - anthropic
        - arcee-ai
        - baidu
        - black-forest-labs
        - bytedance
        - cohere
        - cursor
        - deepseek
        - eleven-labs
        - essential-ai
        - google
        - ibm
        - inception
        - inclusionai
        - kwaipilot
        - lg
        - liquid-ai
        - meituan
        - meta
        - microsoft
        - minimax
        - mistral
        - moonshotai
        - naver-hyperclova
        - nous
        - nvidia
        - openai
        - perplexity
        - prime-intellect
        - qwen
        - relace
        - sourceful
        - stepfun
        - suno
        - upstage
        - vercel
        - voyage
        - x-ai
        - xiaomi
        - z-ai
    GatewayModelsResponse:
      type: object
      required:
        - ok
        - privacy_scope
        - availability_mode
        - limit
        - offset
        - total
        - models
      properties:
        ok:
          type: boolean
          example: true
        privacy_scope:
          type: string
          enum:
            - shared
            - team
          example: shared
        availability_mode:
          type: string
          enum:
            - active
            - all
          example: active
        limit:
          type: integer
          minimum: 1
          maximum: 250
          example: 50
        offset:
          type: integer
          minimum: 0
          maximum: 5000
          example: 0
        total:
          type: integer
          minimum: 0
          example: 128
        models:
          type: array
          items:
            $ref: '#/components/schemas/Model'
      additionalProperties: false
    InvalidRequestResponse:
      type: object
      required:
        - ok
        - error
        - message
      properties:
        ok:
          type: boolean
          enum:
            - false
          example: false
        error:
          type: string
          example: invalid_request
        message:
          type: string
          example: Invalid request parameters.
        max_offset:
          type: integer
          minimum: 0
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        ok:
          type: boolean
          example: false
        error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          example: error_type
        message:
          type: string
          example: Human-readable error message
        description:
          type: string
          example: Additional error details.
        generation_id:
          type: string
          example: G-abc123
        status_code:
          type: integer
          example: 502
        error_type:
          type: string
          enum:
            - user
            - system
          example: system
        error_origin:
          type: string
          enum:
            - user
            - gateway
            - upstream
          example: upstream
        reason:
          type: string
          example: all_candidates_failed
        attempt_count:
          type: integer
          example: 2
        failed_providers:
          type: array
          items:
            type: string
          example:
            - google-ai-studio
            - openai
        failed_statuses:
          type: array
          items:
            type: integer
          example:
            - 403
            - 429
        upstream_error:
          $ref: '#/components/schemas/ErrorUpstreamError'
        failure_sample:
          type: array
          items:
            $ref: '#/components/schemas/ErrorFailureSampleItem'
        provider_failure_diagnostics:
          $ref: '#/components/schemas/ErrorProviderFailureDiagnostics'
        routing_diagnostics:
          $ref: '#/components/schemas/ErrorRoutingDiagnostics'
        provider_candidate_diagnostics:
          $ref: '#/components/schemas/ErrorProviderCandidateDiagnostics'
        provider_enablement:
          $ref: '#/components/schemas/ErrorProviderEnablementDiagnostics'
        missing_pricing_providers:
          type: array
          items:
            type: string
        provider_payment_required_provider:
          type: string
          example: openai
        provider_payment_required_support_notice:
          type: string
          example: >-
            Our upstream provider billing appears to be unavailable. If this
            persists, contact support.
        details:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    Model:
      type: object
      properties:
        id:
          type: string
        canonical_slug:
          type: string
        model_id:
          type: string
        name:
          type: string
          nullable: true
        description:
          type: string
        created:
          type: integer
          nullable: true
        release_date:
          type: string
          nullable: true
        deprecation_date:
          type: string
          nullable: true
        retirement_date:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        availability:
          $ref: '#/components/schemas/ModelAvailability'
        lifecycle:
          $ref: '#/components/schemas/ModelLifecycle'
        organisation_id:
          type: string
          nullable: true
        organisation_name:
          type: string
          nullable: true
        organisation_colour:
          type: string
          nullable: true
        aliases:
          type: array
          items:
            type: string
        endpoints:
          type: array
          items:
            type: string
        input_types:
          type: array
          items:
            type: string
        output_types:
          type: array
          items:
            type: string
        providers:
          type: array
          items:
            $ref: '#/components/schemas/ModelProviderAvailability'
        supported_params:
          type: array
          items:
            type: string
        supported_parameters:
          type: array
          items:
            type: string
        architecture:
          type: object
          properties:
            modality:
              type: string
            input_modalities:
              type: array
              items:
                type: string
            output_modalities:
              type: array
              items:
                type: string
            tokenizer:
              type: string
              nullable: true
            instruct_type:
              type: string
              nullable: true
        top_provider_id:
          type: string
          nullable: true
        top_provider:
          type: object
          properties:
            context_length:
              type: integer
              nullable: true
            max_completion_tokens:
              type: integer
              nullable: true
            is_moderated:
              type: boolean
        pricing:
          type: object
          properties:
            prompt:
              type: string
              nullable: true
            completion:
              type: string
              nullable: true
            request:
              type: string
              nullable: true
            image:
              type: string
              nullable: true
            input_cache_read:
              type: string
              nullable: true
            input_cache_write:
              type: string
              nullable: true
            web_search:
              type: string
              nullable: true
        pricing_detail:
          type: object
          properties:
            pricing_plan:
              type: string
            meters:
              type: object
              additionalProperties: true
        per_request_limits:
          type: object
          nullable: true
          additionalProperties: true
    ErrorUpstreamError:
      type: object
      properties:
        code:
          type: string
          nullable: true
          example: PERMISSION_DENIED
        message:
          type: string
          nullable: true
          example: The caller does not have permission.
        description:
          type: string
          nullable: true
        param:
          type: string
          nullable: true
    ErrorFailureSampleItem:
      type: object
      properties:
        provider:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        upstream_error_code:
          type: string
          nullable: true
        upstream_error_message:
          type: string
          nullable: true
        upstream_error_description:
          type: string
          nullable: true
        upstream_error_param:
          type: string
          nullable: true
        upstream_payload_preview:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
      additionalProperties: true
    ErrorProviderFailureDiagnostics:
      type: object
      properties:
        category:
          type: string
          enum:
            - credentials_not_configured
            - credentials_invalid_or_forbidden
            - provider_access_missing
            - region_or_project_restriction
            - model_unavailable_for_endpoint
            - rate_limited
            - server_error
        hint:
          type: string
        provider:
          type: string
          nullable: true
    ErrorRoutingDiagnostics:
      type: object
      properties:
        filterStages:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
              beforeCount:
                type: integer
              afterCount:
                type: integer
              droppedProviders:
                type: array
                items:
                  type: object
                  properties:
                    providerId:
                      type: string
                      nullable: true
                    reason:
                      type: string
                      nullable: true
                  additionalProperties: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderCandidateDiagnostics:
      type: object
      properties:
        totalProviders:
          type: integer
        supportsEndpointCount:
          type: integer
        candidateCount:
          type: integer
        droppedUnsupportedEndpoint:
          type: array
          items:
            type: string
        droppedMissingAdapter:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              endpoint:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderEnablementDiagnostics:
      type: object
      properties:
        capability:
          type: string
        providersBefore:
          type: array
          items:
            type: string
        providersAfter:
          type: array
          items:
            type: string
        dropped:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              reason:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ModelAvailability:
      type: object
      required:
        - status
        - provider_count
        - active_provider_count
        - inactive_provider_count
      properties:
        status:
          type: string
          enum:
            - active
            - coming_soon
            - inactive
            - not_listed
        provider_count:
          type: integer
          minimum: 0
        active_provider_count:
          type: integer
          minimum: 0
        inactive_provider_count:
          type: integer
          minimum: 0
    ModelLifecycle:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - deprecated
            - retired
          nullable: true
        deprecation_date:
          type: string
          nullable: true
        retirement_date:
          type: string
          nullable: true
        replacement_model_id:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
    ModelProviderAvailability:
      type: object
      required:
        - api_provider_id
        - is_active_gateway
        - availability_status
        - availability_reason
        - provider_status
        - provider_routing_status
        - model_routing_status
        - capability_status
        - endpoints
        - params
      properties:
        api_provider_id:
          type: string
        api_provider_name:
          type: string
          nullable: true
        is_active_gateway:
          type: boolean
        availability_status:
          type: string
          enum:
            - active
            - coming_soon
            - inactive
        availability_reason:
          type: string
          enum:
            - active
            - preview_only
            - gated
            - access_limited
            - region_limited
            - project_limited
            - paused
            - soft_blocked
            - deranked_lvl1
            - deranked_lvl2
            - deranked_lvl3
            - internal_testing
            - scheduled
            - coming_soon
            - provider_disabled
            - model_disabled
            - capability_disabled
            - provider_not_ready
            - provider_inactive
            - inactive
            - retired
        provider_status:
          type: string
          enum:
            - active
            - beta
            - alpha
            - not_ready
            - gated
            - access_limited
            - region_limited
            - project_limited
            - paused
            - soft_blocked
        provider_routing_status:
          type: string
          enum:
            - active
            - deranked_lvl1
            - deranked_lvl2
            - deranked_lvl3
            - disabled
        model_routing_status:
          type: string
          enum:
            - active
            - deranked_lvl1
            - deranked_lvl2
            - deranked_lvl3
            - disabled
        capability_status:
          type: string
          enum:
            - active
            - coming_soon
            - deranked_lvl1
            - deranked_lvl2
            - deranked_lvl3
            - disabled
            - internal_testing
        effective_from:
          type: string
          nullable: true
        effective_to:
          type: string
          nullable: true
        endpoints:
          type: array
          items:
            type: string
        params:
          type: array
          items:
            type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````