# List models

Retrieve a list of available AI models with their capabilities, pricing, and configuration details.

#### Query Parameters

**`ui_models_only`** boolean optional · Defaults to `false`

Filter to show only UI-visible models. When `true`, returns only models that should be displayed in user interfaces.

**`include_pricing`** boolean optional · Defaults to `false`

Include pricing information for each model. When enabled, returns per-model list prices in CHF per 1M synapses (`input_price_per_1m_synapses`, `output_price_per_1m_synapses`, `cache_read_price_per_1m_synapses`, `cache_creation_price_per_1m_synapses`, `category`, `currency`).

**`include_details`** boolean optional · Defaults to `false`

Include detailed model information (`provider`, `context_window`, `release_date`, `training_data_cutoff`, `added_to_aitronos_date`, `description`, `recommended_for`).

**`include_capabilities`** boolean optional · Defaults to `true`

Include model capabilities array (text_generation, vision, tool_calling, etc.).

**`include_deprecated`** boolean optional · Defaults to `false`

Include deprecated models in the response.

**`include_legacy`** boolean optional · Defaults to `false`

Include legacy models that may be phased out.

**`include_recent_usage`** boolean optional · Defaults to `false`

Include recent usage statistics for each model.

**`modality`** string optional

Filter by modality. One of `text`, `audio`, `image`, `video`, `avatar`. Chat pickers should pass `modality=text` to exclude non-chat models.

## Query parameters

**`assistant_id`** string optional

The assistant id.

**`organization_id`** string optional

The organization id.

## Returns

A list of [Model objects](/docs/api-reference/objects/model-object).

### What is and is not listed

- **Gateway models.** Models served through the OpenRouter gateway carry `provider: "openrouter"`, a key starting with `or-`, and a `vendor` / `family` naming the company and model family behind them. They sort after every directly integrated provider. They are listed only while every request to them is guaranteed to use zero-data-retention hosts that do not collect data; if that guarantee cannot be confirmed, all `or-` models are left out of the list. See [Gateway Models (OpenRouter)](/docs/documentation/core-concepts/openrouter-models).
- **Router models.** `or-jev-router` (**Auto (best model per turn)**) picks a model for every turn, and each turn is billed as a turn of the model it chose. With `include_pricing=true` its listed prices are an upper bound used for estimates and spend-limit checks.
- **Auto.** Where the Auto model is switched on for your organisation, the list carries one row with key `auto` and name **Auto** (`provider: "aitronos"`, `family: "auto"`, `pricing: null`). Send `model: "auto"` and Auto picks the model, reasoning effort and speed tier for each message within your organisation's rules; each reply is billed as a reply of the model it picked. See [Auto Model](/docs/documentation/core-concepts/auto-model).
- **Intelligence and cost ratings.** Every model carries `intelligence` and `cost`, whatever `include_*` flags you send: a plain-language rating such as `{"level": 3, "max": 5, "label": "Smart"}`. Show `label` as is and draw `level` out of `max`; `max` is the same for every model in the response. A model that cannot be rated has `null`. See [Model object](/docs/api-reference/objects/model-object#intelligence--cost).
- **Decision models are never listed.** System One decision models answer typed questions rather than chat and cannot be used as a chat `model`, so they are excluded whatever filters you pass. They are chosen inside FlowPlate decision nodes; see [System One Decision Models](/docs/documentation/core-concepts/system-one-decision-models).


### Availability

The model catalog is a start-up resource, so it is designed never to fail hard:

- If a dependency is temporarily unavailable, the endpoint replies with the last
catalog it served for the same query, sent as `Cache-Control: private, no-cache`
so your client revalidates on the next request instead of holding a stale list.
- If no previous catalog is available (for example on a freshly started
instance), the endpoint replies `503` with
`{"status": "warming", "ready_in_seconds": <number or null>}` and a
`Retry-After` header. Wait for `Retry-After` seconds and retry; the response is
a signal to be patient, not an error to surface to the user.


Basic

```bash cURL
curl "https://api.aitronos.com/v1/models" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

models = client.models.list_models(
    organization_id="org_12345",
)
print(models)
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/models", headers={"X-API-Key": api_key}
)

models = response.json()
print(f"Found {models['total_count']} models")
for model in models["models"]:
    print(f"- {model['name']} ({model['id']})")
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/models', {
  headers: {
    'X-API-Key': apiKey
  }
});

const models = await response.json();
console.log(`Found ${models.total_count} models`);
models.models.forEach(model => {
  console.log(`- ${model.name} (${model.id})`);
});
```

**Response:**


```json 200 OK
{
  "models": [
    {
      "id": "mdl_09adacc3e5d3",
      "key": "gpt-4o",
      "name": "GPT-4o",
      "is_visible_in_ui": true,
      "is_deprecated": false,
      "capabilities": ["text_generation", "vision", "tool_calling"]
    }
  ],
  "total_count": 1
}
```

With Pricing & Details

```bash cURL
curl "https://api.aitronos.com/v1/models?include_pricing=true&include_details=true" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

models = client.models.list_models(
    organization_id="org_12345",
)
print(models)
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/models",
    headers={"X-API-Key": api_key},
    params={"include_pricing": True, "include_details": True},
)

models = response.json()
for model in models["models"]:
    p = model.get("pricing")
    if p:
        print(f"{model['name']}: {p['input_price_per_1m_synapses']} CHF/1M input")
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/models?include_pricing=true&include_details=true', {
  headers: {
    'X-API-Key': apiKey
  }
});

const models = await response.json();
models.models.forEach(model => {
  const p = model.pricing;
  if (p) {
    console.log(`${model.name}: ${p.input_price_per_1m_synapses} CHF/1M input`);
  }
});
```

**Response:**


```json 200 OK
{
  "models": [
    {
      "id": "mdl_09adacc3e5d3",
      "key": "gpt-4o",
      "name": "GPT-4o",
      "description": "Most advanced multimodal model with vision, audio, and tool calling capabilities",
      "provider": "openai",
      "provider_icon_url": "/v1/models/providers/openai/icon",
      "vendor": "openai",
      "vendor_name": "OpenAI",
      "vendor_icon_url": "/v1/models/providers/openai/icon",
      "family": "gpt",
      "family_name": "GPT",
      "is_visible_in_ui": true,
      "is_deprecated": false,
      "context_window": 128000,
      "pricing": {
        "input_price_per_1m_synapses": 2.50,
        "output_price_per_1m_synapses": 10.00,
        "currency": "CHF"
      },
      "intelligence": { "level": 2, "max": 5, "label": "Capable" },
      "cost": { "level": 3, "max": 4, "label": "High" },
      "release_date": "2024-05-13T00:00:00Z",
      "training_data_cutoff": null
    }
  ],
  "total_count": 1
}
```

Minimal Response

```bash cURL
curl "https://api.aitronos.com/v1/models?include_capabilities=false" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

models = client.models.list_models(
    organization_id="org_12345",
)
print(models)
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/models",
    headers={"X-API-Key": api_key},
    params={"include_capabilities": False},
)

models = response.json()
# Returns only: id, key, name, is_visible_in_ui, is_deprecated, intelligence, cost
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/models?include_capabilities=false', {
  headers: {
    'X-API-Key': apiKey
  }
});

const models = await response.json();
// Returns only: id, key, name, is_visible_in_ui, is_deprecated, intelligence, cost
```

**Response:**


```json 200 OK
{
  "models": [
    {
      "id": "mdl_09adacc3e5d3",
      "key": "gpt-4o",
      "name": "GPT-4o",
      "is_visible_in_ui": true,
      "is_deprecated": false,
      "intelligence": { "level": 2, "max": 5, "label": "Capable" },
      "cost": { "level": 3, "max": 4, "label": "High" }
    }
  ],
  "total_count": 1
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "trace_id": "req_abc123xyz",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource.",
    "system_message": "Insufficient permissions for organization",
    "type": "authorization_error",
    "status": 403,
    "trace_id": "req_def456uvw",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```


```json 429 Rate Limit
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "system_message": "Rate limit exceeded for endpoint",
    "type": "rate_limit_error",
    "status": 429,
    "trace_id": "req_ghi789rst",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```


```json 500 Server Error
{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred. Please try again later.",
    "system_message": "Database connection timeout",
    "type": "server_error",
    "status": 500,
    "trace_id": "req_jkl012mno",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

## Related Resources

- [Recently Used Models](/docs/api-reference/models/recent-usage)
- [Get provider icon](/docs/api-reference/models/provider-icon) — the `provider_icon_url` each model carries
- [List provider icons](/docs/api-reference/models/provider-icons-manifest) — every provider's icon URL in one request
- [Get Usage Analytics](/assets/get-usage.5798478bf02850cd268552d2e3f624bca950345e4b7dcd69de107396cfbdbc92.96f20eaa.md)
- [Gateway Models (OpenRouter)](/docs/documentation/core-concepts/openrouter-models) — `or-` models, data protection and the Auto router
- [Model object](/docs/api-reference/objects/model-object) — `vendor`, `family` and `pricing`