# List models

> Retrieve enabled Router model editions, enforced limits, and observed provider counts.

**GET** `/v1/models`: Bearer token required

Returns every model edition enabled for the developer API, including editions with no provider currently online.

## Example request

```bash
curl "$ROUTER_BASE_URL/models" \
  -H "Authorization: Bearer $ROUTER_API_KEY"
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "gemma3:1b",
      "object": "model",
      "title": "Gemma 3 1B",
      "brand": "Gemma",
      "owned_by": "Google",
      "digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "context_length": 32000,
      "max_output_tokens": 2048,
      "max_prompt_bytes": 192000,
      "capabilities": ["text-chat", "streaming"],
      "ready_providers": 2,
      "online_providers": 3
    }
  ]
}
```

The values are illustrative. Always use the current response.

## Model fields

| Field                        | Meaning                                                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                         | Exact edition ID to send in a chat request.                                                                                                |
| `title`, `brand`, `owned_by` | Display metadata for the model.                                                                                                            |
| `digest`                     | Exact configured model artifact revision.                                                                                                  |
| `context_length`             | Maximum combined context tokens enforced for the edition.                                                                                  |
| `max_output_tokens`          | Maximum accepted `max_tokens` value.                                                                                                       |
| `max_prompt_bytes`           | Maximum combined UTF-8 bytes across message text.                                                                                          |
| `capabilities`               | Capabilities of this enabled API edition.                                                                                                  |
| `ready_providers`            | Matching providers currently free that serve the edition’s full request size. Providers still serving a shorter size count only as online. |
| `online_providers`           | Matching connected providers, including busy ones.                                                                                         |

> **Zero is different from unknown**
> This authenticated response reports current process observations. Capacity can change immediately after the response; listing a model never reserves a provider.

## Errors

Authentication failures return 401. Account request limits return 429. A required account or catalog dependency can return 503. Error responses use the common [error envelope](https://router.optimai.network/docs/api/errors.md).

Next, send the selected ID to [chat completions](https://router.optimai.network/docs/api/chat-completions.md).