# Models

List the models in the Spicepod of a project, with their status and metadata, as JSON or CSV.

`GET /v1/models` lists the models in the Spicepod of the project: language models and machine learning models.

## List Models

`GET /v1/models`

List all models, both machine learning and language models, available in the runtime.
When `status=true` and a model is in `Error`, the response also includes:

- `error`: structured code object with `category`, `type`, and stable `code`
- `error_message`: user-visible details

### Query parameters

- `format` (string, optional): The format of the response (e.g., `json` or `csv`). Allowed values: `json`, `csv`.
- `status` (boolean, optional): If true, includes the status of each model in the response.
- `metadata_fields` (string, optional): A comma-separated list of metadata fields to include in the response (e.g., `supports_responses_api`)

### Header parameters

- `X-API-Key` (string, required): Your project API key. See [API keys](https://spice.ai/docs/cloud/portal/apps/api-keys).

### Example request

```bash
curl "https://data.spiceai.io/v1/models" \
  -H "X-API-Key: <project-api-key>"
```

```http
GET /v1/models HTTP/1.1
Host: data.spiceai.io
X-API-Key: <project-api-key>
```

### Responses

**200 OK**

List of models in JSON format

Content type: `application/json`

Response wrapper for the `/v1/models` endpoint (OpenAI-compatible format).

- `data` (array of object, required): The list of models
  - `datasets` (array of string | null): The datasets associated with this model, if any
  - `error` (object | null): An optional error type/code for the model status.
    Only populated when `status=true` and the model status is `Error`.
    Example:
    `{ "category": "model", "type": "auth", "code": "model.auth" }`.
    - `category` (string, required): High-level component category where the error originated. Allowed values: `dataset`, `model`, `worker`, `runtime`.
    - `code` (string, required): Stable machine-readable code (`{category}.{type}`), e.g. `dataset.auth`.
    - `type` (string, required): Canonical error type intended for programmatic handling. Allowed values: `auth`, `connection`, `timeout`, `validation`, `not_found`, `permission`, `rate_limit`, `internal`, `unknown`.
  - `error_message` (string | null): An optional error message describing why the model entered an error state.
    Only populated when `status=true`, the model status is `Error`, and an error message was recorded.
    This value is intended for user-visible display.
  - `id` (string, required): The name/identifier of the model
  - `metadata` (object | null): Optional metadata fields, included when requested via query parameters
    - `supports_responses_api` (boolean, required): Whether this model supports the Responses API
  - `object` (string, required): The type of the object (always `model`)
  - `owned_by` (string, required): The source from which the model was loaded (e.g., `openai`, `spiceai`)
  - `status` ("Initializing" | "Ready" | "Disabled" | object | "Refreshing" | "ShuttingDown" | "NotLoaded" | null): The status of the model (e.g., `Ready`, `Initializing`, `Error`). Example: `Ready`.

    One of:
    - **"Initializing"** (string): The component is initializing and not yet ready. Value: `Initializing`.
    - **"Ready"** (string): The component is ready to accept connections. Value: `Ready`.
    - **"Disabled"** (string): The component is disabled and not running. Value: `Disabled`.
    - **object with Error** (object): An error occurred in the component, with an optional error message
      - `Error` (string | null, required): An error occurred in the component, with an optional error message
    - **"Refreshing"** (string): The component is in the process of refreshing its state. Value: `Refreshing`.
    - **"ShuttingDown"** (string): The component is in the process of shutting down. Value: `ShuttingDown`.
    - **"NotLoaded"** (string): The component is configured but not loaded yet. Value: `NotLoaded`.
- `object` (string, required): The type of the response (always `list`)

Example:

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "owned_by": "openai",
      "datasets": null,
      "status": "ready",
      "error": null,
      "error_message": null
    },
    {
      "id": "text-embedding-ada-002",
      "object": "model",
      "owned_by": "openai-internal",
      "datasets": [
        "text-dataset-1",
        "text-dataset-2"
      ],
      "status": "error",
      "error": {
        "category": "model",
        "type": "auth",
        "code": "model.auth"
      },
      "error_message": "Invalid API key"
    }
  ]
}
```

Content type: `text/csv`

Type: `string`

Example:

```text
id,object,owned_by,datasets,status,error,error_message
gpt-4,model,openai,,ready,,
text-embedding-ada-002,model,openai-internal,"text-dataset-1,text-dataset-2",error,model.auth,Invalid API key
```

**500 Internal Server Error**

Internal server error occurred while processing models

Content type: `application/json`

Type: `any`

Example:

```json
{
  "error": "App not initialized"
}
```

OpenAPI: [spiceai/spiceai v2.3.2](https://github.com/spiceai/spiceai/blob/v2.3.2/.schema/openapi.json)