---
title: "List the models this provider can run"
method: GET
path: "/v1/projects/{project_id}/ai-providers/{ai_provider_id}/models"
tags: ["AI Providers"]
---

# List the models this provider can run

`GET /v1/projects/{project_id}/ai-providers/{ai_provider_id}/models`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/ai-providers/{ai_provider_id}/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`)

Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — the same strings `default_model` and an agent's `model` carry.
Which models are reachable is a property of the credential, not of the provider type: a Vertex provider sees only the publisher models its Google Cloud project and location serve, and a Bedrock provider only the foundation models enabled in its region. Reading the list is how a caller avoids pinning a model that fails at generation time.
Not every provider type can answer. `azure` lists deployments an operator named rather than models, and `ollama` lists whatever was pulled onto that host, so both return `400 MODEL_LISTING_UNSUPPORTED`.
Listing resolves credentials the same way generation does, so a record that can generate can list. The API-key types (`openai`, `groq`, `xai`, `gateway`, `custom`, `anthropic`, `google`) use the record's linked secret and cannot list without one. `bedrock` and `vertex` use the linked secret — IAM keys or a Bedrock API key, a Google service-account key. A record with no `secret_id` would fall back to the server's own credentials (the AWS default credential chain, Google Application Default Credentials); it can list only on a deployment that allows a record to use them, and returns `400 AI_PROVIDER_MISCONFIGURED` otherwise.
A Vertex record needs no `config.project` when its secret is a service-account key, since the key file names its own project. A Vertex record in express mode (API key) cannot list at all: the publisher-model listing rejects API keys and needs a credential that asserts a principal, so it returns `400 MODEL_LISTING_UNSUPPORTED`.
The Vertex answer is the publisher catalogue the record's `config.location` region serves. The project behind the credential is billed and quota'd for the call but does not filter the result, so a listed model may still be unavailable to that project at generation time.
The provider answers its whole catalogue in one call; `q`, `limit` and `offset` narrow and page what it returned. A request without `limit` gets the first 50 models.

## Path parameters

- `ai_provider_id` string, required

## Query parameters

- `q` string
- `limit` integer
- `offset` integer

## Response `200`

The models this provider can run

- ProviderModelsResponse
  - `total` integer, required: Models matching `q` across every page
  - `limit` integer, required
  - `offset` integer, required
  - `data` object[], required
    - `id` string, required: The provider-native model id, ready to use as `default_model` or an agent's `model`
    - `display_name` string: The provider's own human-readable name, when it reports one
    - `vendor` string: Who makes the model, when the provider reports it
    - `input_modalities` string[]: Lowercased input modalities, when the provider reports them
    - `output_modalities` string[]: Lowercased output modalities, when the provider reports them
    - `streaming` boolean: Whether the model supports streaming responses
    - `lifecycle` 'active' | 'legacy' | 'deprecated': `active`, `legacy` or `deprecated`, as the provider reports it. A model that is not `active` still serves today but should not be pinned by anything new.
    - `inference_types` string[]: Lowercased inference types the model supports, when reported. A Bedrock model offering only `inference_profile` must be invoked through a cross-region profile id rather than the bare model id.

## Other responses

- `400`: The provider type or authentication mode cannot enumerate models (including Vertex express mode), or the record is missing configuration the listing needs (a Vertex project from either `config.project` or the service-account key file, a Bedrock region, or — for the API-key provider types — a linked secret).
- `401`: Unauthorized
- `403`: Forbidden
- `404`: AI provider not found
- `502`: The provider rejected the listing request

---

[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)