List Models

Retrieve the list of available models

GET /v1/models

List Models

cURL

curl --request GET \
  --url https://api.example.com/v1/models \
  --header 'Authorization: <authorization>'

200

{
  "object": "<string>",
  "data": [
    {}
  ],
  "id": "<string>",
  "created": 123,
  "owned_by": "<string>",
  "metadata": {},
  "metadata.display_name": "<string>",
  "metadata.description": "<string>",
  "metadata.context_window": 123,
  "metadata.input_modalities": [
    {}
  ],
  "metadata.supported_reasoning_levels": [
    {}
  ],
  "metadata.default_reasoning_level": {},
  "metadata.supports_reasoning_summaries": true,
  "metadata.support_verbosity": true,
  "metadata.default_verbosity": {},
  "metadata.prefer_websockets": true,
  "metadata.supports_parallel_tool_calls": true,
  "metadata.supported_in_api": true,
  "metadata.minimal_client_version": {},
  "metadata.priority": 123
}

Overview

The /v1/models endpoint returns a list of models available to your API key. The response is filtered based on your API key’s allowed_models configuration if present.

This endpoint is useful for:

• Discovering available models before making requests
• Checking model capabilities and metadata
• Validating model access for your API key
• Understanding model restrictions and features

Authentication

Authorization · string · required

Bearer token for API authentication. Format: Bearer YOUR_API_KEY

Response

Returns a list of model objects.

object · string

Always "list".

data · array

Array of model objects. Each model object contains:

Model Object

id · string

Model identifier (slug). Use this value in the model parameter for completions.

Examples: "gpt-4.1", "gpt-5.2", "o3-pro"

object · string

Always "model".

created · integer

Unix timestamp when the model list was generated.

owned_by · string

Owner identifier. Always "codex-lb".

metadata · object

Extended model metadata with capabilities and configuration.

Model Metadata

metadata.display_name · string

Human-readable model name.

Example: "GPT-4.1 Turbo", "O3 Pro"

metadata.description · string

Model description explaining capabilities and use cases.

metadata.context_window · integer

Maximum context window size in tokens.

Example: 128000, 200000

metadata.input_modalities · array

Supported input modalities.

Possible values:

• "text": Text input
• "image": Image input
• "audio": Audio input
• "video": Video input

metadata.supported_reasoning_levels · array

Available reasoning effort levels for this model.

Each level object contains:

• effort (string): Effort level identifier (e.g., "low", "medium", "high")
• description (string): Description of the reasoning level

metadata.default_reasoning_level · string | null

Default reasoning effort level when not specified.

Example: "medium"

metadata.supports_reasoning_summaries · boolean · default: false

Whether the model supports reasoning summaries.

metadata.support_verbosity · boolean · default: false

Whether the model supports verbosity control.

metadata.default_verbosity · string | null

Default verbosity level when not specified.

Example: "normal", "concise"

metadata.prefer_websockets · boolean · default: false

Whether the model prefers WebSocket connections for streaming.

metadata.supports_parallel_tool_calls · boolean · default: false

Whether the model supports calling multiple tools in parallel.

metadata.supported_in_api · boolean · default: true

Whether the model is available via API endpoints.

metadata.minimal_client_version · string | null

Minimum client version required to use this model.

Example: "1.2.0"

metadata.priority · integer · default: 0

Model priority for selection and display ordering. Higher values indicate higher priority.

Examples

List All Available Models

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4.1",
      "object": "model",
      "created": 1709481600,
      "owned_by": "codex-lb",
      "metadata": {
        "display_name": "GPT-4.1 Turbo",
        "description": "Advanced language model with enhanced reasoning",
        "context_window": 128000,
        "input_modalities": ["text", "image"],
        "supported_reasoning_levels": [
          {
            "effort": "low",
            "description": "Fast responses with minimal reasoning"
          },
          {
            "effort": "medium",
            "description": "Balanced reasoning and speed"
          },
          {
            "effort": "high",
            "description": "Deep reasoning for complex problems"
          }
        ],
        "default_reasoning_level": "medium",
        "supports_reasoning_summaries": false,
        "support_verbosity": true,
        "default_verbosity": "normal",
        "prefer_websockets": false,
        "supports_parallel_tool_calls": true,
        "supported_in_api": true,
        "minimal_client_version": null,
        "priority": 100
      }
    },
    {
      "id": "gpt-5.2",
      "object": "model",
      "created": 1709481600,
      "owned_by": "codex-lb",
      "metadata": {
        "display_name": "GPT-5.2",
        "description": "Next-generation model with advanced capabilities",
        "context_window": 200000,
        "input_modalities": ["text", "image", "audio"],
        "supported_reasoning_levels": [
          {
            "effort": "low",
            "description": "Quick responses"
          },
          {
            "effort": "medium",
            "description": "Standard reasoning"
          },
          {
            "effort": "high",
            "description": "Extended reasoning"
          },
          {
            "effort": "max",
            "description": "Maximum reasoning capability"
          }
        ],
        "default_reasoning_level": "medium",
        "supports_reasoning_summaries": true,
        "support_verbosity": true,
        "default_verbosity": "normal",
        "prefer_websockets": true,
        "supports_parallel_tool_calls": true,
        "supported_in_api": true,
        "minimal_client_version": "2.0.0",
        "priority": 200
      }
    },
    {
      "id": "o3-pro",
      "object": "model",
      "created": 1709481600,
      "owned_by": "codex-lb",
      "metadata": {
        "display_name": "O3 Pro",
        "description": "Specialized model for complex reasoning tasks",
        "context_window": 128000,
        "input_modalities": ["text"],
        "supported_reasoning_levels": [
          {
            "effort": "high",
            "description": "Deep reasoning only"
          }
        ],
        "default_reasoning_level": "high",
        "supports_reasoning_summaries": true,
        "support_verbosity": false,
        "default_verbosity": null,
        "prefer_websockets": false,
        "supports_parallel_tool_calls": false,
        "supported_in_api": true,
        "minimal_client_version": null,
        "priority": 150
      }
    }
  ]
}

Model Filtering

API Key Restrictions

If your API key has allowed_models configured, the response will only include those models:

API Key with restrictions:

{
  "allowed_models": ["gpt-4.1", "gpt-5.2"]
}

Response (filtered):

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4.1",
      ...
    },
    {
      "id": "gpt-5.2",
      ...
    }
  ]
}

Models not in your allowed_models list will not appear in the response.

No Restrictions

If your API key has no allowed_models restrictions (or allowed_models is null/empty), all available models are returned.

Use Cases

Check Model Capabilities

Use the metadata to determine if a model supports the features you need:

const response = await fetch('https://api.example.com/v1/models', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const { data: models } = await response.json();

// Find models that support parallel tool calls
const parallelToolModels = models.filter(
  m => m.metadata.supports_parallel_tool_calls
);

// Find models with large context windows
const largeContextModels = models.filter(
  m => m.metadata.context_window >= 128000
);

// Find models that support image input
const imageModels = models.filter(
  m => m.metadata.input_modalities.includes('image')
);

Dynamic Model Selection

Select the best model for your use case:

// Get highest priority model
const topModel = models.sort(
  (a, b) => b.metadata.priority - a.metadata.priority
)[0];

// Get model with largest context window
const largestContext = models.sort(
  (a, b) => b.metadata.context_window - a.metadata.context_window
)[0];

// Get reasoning-capable model
const reasoningModel = models.find(
  m => m.metadata.supports_reasoning_summaries
);

Validate Model Access

Check if you have access to a specific model:

const hasAccess = models.some(m => m.id === 'gpt-5.2');

if (!hasAccess) {
  console.error('API key does not have access to gpt-5.2');
}

Rate Limiting

The /v1/models endpoint is subject to the same rate limiting as other API endpoints. Each request counts toward your API key’s request quota.

Empty Response

If no models are available (e.g., model registry not yet loaded), the endpoint returns:

{
  "object": "list",
  "data": []
}

Error Handling

Errors return OpenAI-compatible error envelopes:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Common error scenarios:

• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: API key lacks permission
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Comparison with OpenAI

This endpoint follows the OpenAI /v1/models format with the following additions:

Standard OpenAI fields:

• id, object, created, owned_by

Codex-LB extensions:

• metadata object with comprehensive model capabilities
• Model filtering based on API key restrictions
• Priority-based model ordering
• Detailed reasoning and verbosity support information

The extended metadata helps clients make informed decisions about model selection without requiring external documentation.