> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/list-models/.

# List models

Lists every model ID accepted when creating a generation, along with its status (`hosted`, `alias`, or `retired`), serving model, and hourly USD list price. Public; requires no API key.

GET `https://api.diffio.ai/v2/models`

- Key scope: None (public)
- Auth header: No API key needed
- Body: None

## Request

Takes no parameters, headers, or request body.

## Example request

**Python**

```python
from diffio import DiffioClient

# A public call: no API key needed.
client = DiffioClient()

models = client.models.list()
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

// A public call: no API key needed.
const client = new DiffioClient()

const models = await client.models.list()
```

**cURL**

```bash
curl "https://api.diffio.ai/v2/models"
```

## Response

Returns a `list` object containing all model entries (`next_cursor` is always `null`).

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"list"`. |
| `data` | array | Always | All accepted model entries: hosted models first, then tier aliases (`diffio-flash`, `diffio-pro`), then retired model names. [Fields below](#fields-data) |
| `next_cursor` | string \| null | Always | Always `null`; all models are returned in one response. |

**`data[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `data[].id` | string | Always | Model identifier accepted in `model` when creating a generation. |
| `data[].object` | string | Always | Resource type, always `"model"`. |
| `data[].status` | string | Always | `hosted` for active models, `alias` for rolling tier pointers, or `retired` for older names that substitute to a hosted model. |
| `data[].label` | string \| null | Always | Display name for hosted models and aliases, or `null` for retired model names. |
| `data[].served_by` | string | Always | Hosted model ID that executes generations requesting this model. |
| `data[].price_per_hour_usd` | number | Always | Hourly list price in USD (`5` for Flash, `10` for Pro; retired models report the lower of their last list price and `served_by`). |

## Example response (200)

**Excerpt: Response: excerpt (one entry of each kind)**

```json
{
  "object": "list",
  "data": [
    {
      "id": "diffio-4.7-flash",
      "object": "model",
      "status": "hosted",
      "label": "Diffio 4.7 Flash",
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-flash",
      "object": "model",
      "status": "alias",
      "label": "Diffio 4.7 Flash",
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-2",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    }
  ],
  "next_cursor": null
}
```

**Full response: Successful response**

```json
{
  "object": "list",
  "data": [
    {
      "id": "diffio-4.7-flash",
      "object": "model",
      "status": "hosted",
      "label": "Diffio 4.7 Flash",
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-4.7-pro",
      "object": "model",
      "status": "hosted",
      "label": "Diffio 4.7 Pro",
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-flash",
      "object": "model",
      "status": "alias",
      "label": "Diffio 4.7 Flash",
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-pro",
      "object": "model",
      "status": "alias",
      "label": "Diffio 4.7 Pro",
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-2",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-2-flash",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-2.0",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-2.0-flash",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-3.0",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-3.2",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-3.4",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-3.5",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-4.0",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-4.0-flash",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-4.0-pro",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-4.5-flash",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-4.5-pro",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    },
    {
      "id": "diffio-4.6-flash",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-flash",
      "price_per_hour_usd": 5
    },
    {
      "id": "diffio-4.6-pro",
      "object": "model",
      "status": "retired",
      "label": null,
      "served_by": "diffio-4.7-pro",
      "price_per_hour_usd": 10
    }
  ],
  "next_cursor": null
}
```

## Return codes

- `200` Returns every model entry with its serving model and hourly USD price.
- **`405` Same on every endpoint**

  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

**Error response**

```json
{
  "error": {
    "code": "method_not_allowed",
    "message": "/models accepts GET.",
    "request_id": "70968c6cd6534e1e9f1547f19966f424"
  }
}
```

## Notes

- Pass `diffio-flash` or `diffio-pro` to always run the newest hosted model in that tier without changing your code.
- Requests naming a `retired` model run on `served_by` with `substituted: true` on the generation and bill the lower of the two list prices.
- See [Models](https://diffio.ai/docs/overview/models/) for quality and speed guidance between Flash and Pro.

## Related pages

- Previous: [API reference introduction](https://diffio.ai/docs/api-reference/introduction/): Base URL, authentication, errors and every endpoint.
- Next: [Create a project](https://diffio.ai/docs/api-reference/create-project/): Create a project for one audio or video file and receive multipart upload instructions.

- [Models](https://diffio.ai/docs/overview/models/): Choosing between Diffio 4.7 Flash and Pro.
- [API pricing](https://diffio.ai/api-pricing/): The current rate per hour for each model.
