List Models

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

{
  "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
}

GET

models

List Models

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

{
  "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

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.

Responses

Audio Transcriptions

​Overview

​Authentication

​Response

​Model Object

​Model Metadata

​Examples

​List All Available Models

​Response Example

​Model Filtering

​API Key Restrictions

​No Restrictions

​Use Cases

​Check Model Capabilities

​Dynamic Model Selection

​Validate Model Access

​Rate Limiting

​Empty Response

​Error Handling

​Comparison with OpenAI

Overview

Authentication

Response

Model Object

Model Metadata

Examples

List All Available Models

Response Example

Model Filtering

API Key Restrictions

No Restrictions

Use Cases

Check Model Capabilities

Dynamic Model Selection

Validate Model Access

Rate Limiting

Empty Response

Error Handling

Comparison with OpenAI