# List models

> GET /v1/models on BigModel.io lists the model IDs your API key's group serves. Works with OpenAI and Anthropic clients; needs a positive balance or an active plan.

Web version: https://bigmodel.io/docs/api-models · Updated 2026-10-18

`GET https://bigmodel.io/v1/models`

Lists the models your key's group serves, so tools can fill their model picker. The list depends on the key's group, not on your account. Unlike [`GET /v1/usage`](https://bigmodel.io/docs/api-usage), this endpoint goes through billing checks: with a zero balance and no active plan it returns `403` `INSUFFICIENT_BALANCE`.

## Request

```http
GET https://bigmodel.io/v1/models
```

### Authentication

| Header | Value |
|---|---|
| `Authorization` | `Bearer $BIGMODEL_API_KEY` |
| `x-api-key` | `$BIGMODEL_API_KEY` |

Send one of these.

### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `configured_only` | boolean |  | Return an empty list instead of built-in defaults when the group has no configured models. |

## Response

| Status | Meaning |
|---|---|
| `200` | The model list. |
| `400` | `api_key_in_query_deprecated` (key sent in the query string), or `invalid_request_error`: empty or invalid JSON, missing `model`, a non-boolean `stream`, or another malformed field. |
| `401` | `API_KEY_REQUIRED`, `INVALID_API_KEY`, `API_KEY_DISABLED`, `USER_NOT_FOUND`, `USER_INACTIVE`. |
| `403` | `INSUFFICIENT_BALANCE`, `API_KEY_EXPIRED`, `ACCESS_DENIED` (IP rule), `SUBSCRIPTION_NOT_FOUND`, `SUBSCRIPTION_INVALID`, or a `permission_error` (key without a group, endpoint not allowed for the group). |
| `429` | `API_KEY_QUOTA_EXHAUSTED`, `USAGE_LIMIT_EXCEEDED` (plan limit), or `rate_limit_exceeded` / `rate_limit_error` (key 5h/1d/7d limit, requests per minute, concurrency, upstream). RPM limits send `Retry-After`. |

### Response fields

| Field | Type | Description |
|---|---|---|
| `object` | any |  |
| `data` | array<object> |  |
| `data[].id` | string | Model ID to send as `model`. |
| `data[].type` | string |  |
| `data[].display_name` | string | Currently the same as `id` for configured models. |
| `data[].created_at` | string | Present on Anthropic-style entries; a fixed placeholder date, not a release date. |
| `data[].object` | string | Present on OpenAI-style entries. |
| `data[].owned_by` | string | Present on OpenAI-style entries. |


## Examples

```bash [cURL]
curl https://bigmodel.io/v1/models \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

```python [Python]
import os
from openai import OpenAI

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])

for model in client.models.list():
    print(model.id)
```

```js [Node.js]
import OpenAI from 'openai'

const client = new OpenAI({baseURL: 'https://bigmodel.io/v1', apiKey: process.env.BIGMODEL_API_KEY})

for await (const model of client.models.list()) console.log(model.id)
```

Example response for a group with configured models (IDs depend on your group):

```json
{
  "object": "list",
  "data": [
    {"id": "glm-5.3", "type": "model", "display_name": "glm-5.3", "created_at": "2024-01-01T00:00:00Z"},
    {"id": "kimi-k3", "type": "model", "display_name": "kimi-k3", "created_at": "2024-01-01T00:00:00Z"}
  ]
}
```

## Notes

- **Use `id` as `model`.** For configured models, `display_name` is the same as `id`, and `created_at` is a fixed placeholder, not a release date.
- **Empty or default lists.** When a group has no configured models, chat-only groups (DeepSeek, GLM platforms) return an empty list, and other groups may return a built-in default list for their platform. Those defaults do not prove the group serves the models. Pass `?configured_only=true` to get an empty list instead of defaults.
- **Prices and descriptions** are not in this response. See the [model catalog](https://bigmodel.io/models) and [Model IDs](https://bigmodel.io/docs/model-ids).
- **`403` `INSUFFICIENT_BALANCE`** with a zero balance, even though listing is free. Top up in [Billing](https://bigmodel.io/purchase), or use [`GET /v1/usage`](https://bigmodel.io/docs/api-usage), which works without balance. Full list: [Errors](https://bigmodel.io/docs/errors).

## Related

- [Model IDs](https://bigmodel.io/docs/model-ids)
- [Model catalog](https://bigmodel.io/models)
- [Authentication](https://bigmodel.io/docs/authentication)