---
title: "List models"
method: GET
path: "/v1/models"
tags: ["Models"]
---

# List models

`GET /v1/models`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/models`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Lists the models naturali offers, sorted by name. Filter by vendor, input/output modality or lifecycle status.
Every model listed here is available to any project with a `provider: "naturali"` [AI provider](/docs/api/ai-providers/create-ai-provider) — there is no second class to filter for. Models naturali cannot serve (unpriced, or producing something other than text) are not in this catalog; to generate on one of those, register your own credentials as an [AI provider](/docs/api/ai-providers/create-ai-provider) and ask that provider what it serves with [`GET /v1/projects/{project_id}/ai-providers/{ai_provider_id}/models`](/docs/api/ai-providers/list-ai-provider-models).

## Query parameters

- `limit` integer
- `cursor` string
- `vendor` string
- `modality` string
- `status` 'available' | 'deprecated'

## Response `200`

A page of models.

- ModelList
  - `data` Model[], required
    - `model` string, required: The model's name, and the only model string this API accepts or returns. Use it verbatim as a provider's `default_model` and as an agent's `model`. It is naturali's own name, not the vendor's: it states a version explicitly and never changes, so a vendor relabelling its model cannot move a name you have already written down. A vendor's own invocation string is refused where this is expected — one model has one name.
    - `vendor` string, required: The model maker.
    - `input_modalities` string[], required: Accepted input modalities.
    - `output_modalities` string[], required
    - `streaming` boolean, required
    - `status` 'available' | 'deprecated', required: Lifecycle status, from the provider's own listing at the last sync. A model the provider stops listing — or reports as legacy or deprecated — flips to `deprecated` and stays in the catalog, so a project already generating on it can see what happened to it. A `deprecated` model cannot be chosen as the `default_model` of a new `provider: "naturali"` provider.
    - `pricing` object, required: What generating on this model costs in credit, in USD per token: the figure the managed provider's price book holds, `/usage` reports as `cost_usd` and the balance is debited. Always present: a model naturali cannot price is not in this catalog. Refreshed by the daily sync.
      - `input_usd_per_token` number, required: USD per input (uncached) token.
      - `output_usd_per_token` number, required: USD per output token. Reasoning ("thinking") tokens are output tokens: on a model that reasons by default they are counted in `output_tokens` and billed at this rate, and can be most of the output on a short answer. A rate alone therefore does not size a request on such a model.
      - `cached_input_usd_per_token` number, nullable, required: USD per cache-read input token; null when the model does not price caching (cached tokens are then billed at the input rate).
    - `synced_at` string, date-time, required: When the catalog last confirmed this entry against the provider.
  - `next_cursor` string, nullable, required: Cursor for the next page, or null at the end.

## Other responses

- `400`: The request was malformed or failed validation.
- `401`: Missing or invalid credentials.

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)