---
title: "Get a custom model"
description: "Retrieve a custom model by model name. Custom models are only visible to the project that owns them."
---

<a id="playground-button:docs/apis/models/get-custom-model"></a>

**GET** `https://api.respan.ai/api/models/{model_name}/`

Retrieve a custom model by model name. Custom models are only visible to the project that owns them.

## Servers

`https://api.respan.ai` — Respan API Server

<a id="request.auth"></a>

## Authentication

<a id="request.auth.Authorization"></a>

### RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer &lt;RESPAN_API_KEY&gt;. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -&gt; Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: `bearer`; format: `Respan API key`.


```http
Authorization: Bearer $RESPAN_API_KEY
```


**Or:**

### DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: `bearer`; format: `Dashboard JWT`.


```http
Authorization: Bearer $RESPAN_DASHBOARD_JWT
```


<a id="request.path"></a>

## Path parameters


| Parameter | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| <a id="request.path.model_name"></a>`model_name` | `string` | Required | The `model_name` that List models returns. Built-in models are provider-prefixed, such as `openai/gpt-4o-mini`; bare names such as `gpt-4o-mini` return 404. |


<a id="response"></a>

## Responses

### 200

Model details.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | Additional properties are allowed |
| <a id="response.body.id"></a>`id` | `string` | Required in parent | Model string ID. Same value as `model_name`.<br />Example: `"my-custom-gpt-4o"` |
| <a id="response.body.model_name"></a>`model_name` | `string` | Required in parent | Model name used in API calls.<br />Example: `"my-custom-gpt-4o"` |
| <a id="response.body.base_model_name"></a>`base_model_name` | `string` | Optional | Base model inherited from, when configured.<br />Example: `"gpt-4o"` |
| <a id="response.body.affiliation_category"></a>`affiliation_category` | `string` | Optional | `keywordsai` for built-in models, `custom` for your organization's models.<br />Allowed: `"keywordsai"`, `"custom"`<br />Example: `"custom"` |
| <a id="response.body.is_called_by_custom_name"></a>`is_called_by_custom_name` | `boolean` | Optional | Whether requests are sent upstream using this custom model name.<br />Example: `false` |
| <a id="response.body.input_cost"></a>`input_cost` | `number` | Optional | Cost per 1M input tokens in USD.<br />Example: `2.5` |
| <a id="response.body.output_cost"></a>`output_cost` | `number` | Optional | Cost per 1M output tokens in USD.<br />Example: `10` |
| <a id="response.body.cache_hit_input_cost"></a>`cache_hit_input_cost` | `number` | Optional | Cost per 1M cached input tokens in USD.<br />Example: `0.5` |
| <a id="response.body.cache_creation_input_cost"></a>`cache_creation_input_cost` | `number` | Optional | Cost per 1M cache creation input tokens in USD.<br />Example: `3` |
| <a id="response.body.max_context_window"></a>`max_context_window` | `integer` | Optional | Maximum context window size.<br />Example: `128000` |
| <a id="response.body.function_call"></a>`function_call` | `integer` | Optional | Function/tool calling support. `0` = no, `1` = yes.<br />Allowed: `0`, `1`<br />Example: `1` |
| <a id="response.body.image_support"></a>`image_support` | `integer` | Optional | Vision input support. `0` = no, `1` = yes.<br />Allowed: `0`, `1`<br />Example: `1` |
| <a id="response.body.model_type"></a>`model_type` | `string` | Optional | Model type.<br />Allowed: `"chat"`, `"embedding"`, `"audio"`<br />Example: `"chat"` |
| <a id="response.body.supported_params"></a>`supported_params` | `object` | Optional | Computed parameter support after applying model-specific overrides.<br />Additional properties are allowed |
| <a id="response.body.provider"></a>`provider` | `object or null` | Optional | Additional properties are allowed |
| `provider.id` | `string` | Required in parent | Provider string ID. Same value as `provider_id`.<br />Example: `"my-vllm"` |
| `provider.provider_id` | `string` | Required in parent | Unique provider identifier within your organization.<br />Example: `"my-vllm"` |
| `provider.provider_name` | `string` | Required in parent | Human-readable provider name.<br />Example: `"My vLLM Server"` |
| `provider.extra_kwargs` | `object` | Optional | Provider configuration such as `base_url` and timeout values. Secret values are not returned here.<br />Additional properties are allowed<br />Example: `{"base_url":"https://vllm.example.com/v1"}` |
| `provider.created_at` | `string or null` | Optional | Format: `date-time` |
| `provider.updated_at` | `string or null` | Optional | Format: `date-time` |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "required": [
    "id",
    "model_name"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Model string ID. Same value as `model_name`.",
      "example": "my-custom-gpt-4o"
    },
    "model_name": {
      "type": "string",
      "description": "Model name used in API calls.",
      "example": "my-custom-gpt-4o"
    },
    "base_model_name": {
      "type": "string",
      "description": "Base model inherited from, when configured.",
      "example": "gpt-4o"
    },
    "affiliation_category": {
      "type": "string",
      "description": "`keywordsai` for built-in models, `custom` for your organization's models.",
      "enum": [
        "keywordsai",
        "custom"
      ],
      "example": "custom"
    },
    "is_called_by_custom_name": {
      "type": "boolean",
      "description": "Whether requests are sent upstream using this custom model name.",
      "example": false
    },
    "input_cost": {
      "type": "number",
      "description": "Cost per 1M input tokens in USD.",
      "example": 2.5
    },
    "output_cost": {
      "type": "number",
      "description": "Cost per 1M output tokens in USD.",
      "example": 10
    },
    "cache_hit_input_cost": {
      "type": "number",
      "description": "Cost per 1M cached input tokens in USD.",
      "example": 0.5
    },
    "cache_creation_input_cost": {
      "type": "number",
      "description": "Cost per 1M cache creation input tokens in USD.",
      "example": 3
    },
    "max_context_window": {
      "type": "integer",
      "description": "Maximum context window size.",
      "example": 128000
    },
    "function_call": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Function/tool calling support. `0` = no, `1` = yes.",
      "example": 1
    },
    "image_support": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Vision input support. `0` = no, `1` = yes.",
      "example": 1
    },
    "model_type": {
      "type": "string",
      "description": "Model type.",
      "enum": [
        "chat",
        "embedding",
        "audio"
      ],
      "example": "chat"
    },
    "supported_params": {
      "type": "object",
      "description": "Computed parameter support after applying model-specific overrides.",
      "additionalProperties": true
    },
    "provider": {
      "type": "object",
      "required": [
        "id",
        "provider_id",
        "provider_name"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Provider string ID. Same value as `provider_id`.",
          "example": "my-vllm"
        },
        "provider_id": {
          "type": "string",
          "description": "Unique provider identifier within your organization.",
          "example": "my-vllm"
        },
        "provider_name": {
          "type": "string",
          "description": "Human-readable provider name.",
          "example": "My vLLM Server"
        },
        "extra_kwargs": {
          "type": "object",
          "description": "Provider configuration such as `base_url` and timeout values. Secret values are not returned here.",
          "additionalProperties": true,
          "example": {
            "base_url": "https://vllm.example.com/v1"
          }
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      },
      "additionalProperties": true,
      "nullable": true
    }
  },
  "additionalProperties": true
}
```

</details>

<a id="response.error"></a>

### 403

The API key is missing, invalid or expired.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `detail` | `string` | Required in parent | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
```

</details>

##### Example


```json
{
  "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
```


### 404

Not Found

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `detail` | `string` | Optional | — |
| `error` | `string` | Optional | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}
```

</details>

##### Example


```json
{
  "error": "Not found"
}
```


## OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

<!-- openapi-operation:start -->
<details class="api-schema-source">
<summary>OpenAPI operation</summary>


```json
{
  "summary": "Get a custom model",
  "operationId": "retrieveCustomModel",
  "tags": [
    "Models"
  ],
  "description": "Retrieve a custom model by model name. Custom models are only visible to the project that owns them.",
  "parameters": [
    {
      "name": "model_name",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "The `model_name` that List models returns. Built-in models are provider-prefixed, such as `openai/gpt-4o-mini`; bare names such as `gpt-4o-mini` return 404."
    }
  ],
  "responses": {
    "200": {
      "description": "Model details.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "id",
              "model_name"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Model string ID. Same value as `model_name`.",
                "example": "my-custom-gpt-4o"
              },
              "model_name": {
                "type": "string",
                "description": "Model name used in API calls.",
                "example": "my-custom-gpt-4o"
              },
              "base_model_name": {
                "type": "string",
                "description": "Base model inherited from, when configured.",
                "example": "gpt-4o"
              },
              "affiliation_category": {
                "type": "string",
                "description": "`keywordsai` for built-in models, `custom` for your organization's models.",
                "enum": [
                  "keywordsai",
                  "custom"
                ],
                "example": "custom"
              },
              "is_called_by_custom_name": {
                "type": "boolean",
                "description": "Whether requests are sent upstream using this custom model name.",
                "example": false
              },
              "input_cost": {
                "type": "number",
                "description": "Cost per 1M input tokens in USD.",
                "example": 2.5
              },
              "output_cost": {
                "type": "number",
                "description": "Cost per 1M output tokens in USD.",
                "example": 10
              },
              "cache_hit_input_cost": {
                "type": "number",
                "description": "Cost per 1M cached input tokens in USD.",
                "example": 0.5
              },
              "cache_creation_input_cost": {
                "type": "number",
                "description": "Cost per 1M cache creation input tokens in USD.",
                "example": 3
              },
              "max_context_window": {
                "type": "integer",
                "description": "Maximum context window size.",
                "example": 128000
              },
              "function_call": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ],
                "description": "Function/tool calling support. `0` = no, `1` = yes.",
                "example": 1
              },
              "image_support": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ],
                "description": "Vision input support. `0` = no, `1` = yes.",
                "example": 1
              },
              "model_type": {
                "type": "string",
                "description": "Model type.",
                "enum": [
                  "chat",
                  "embedding",
                  "audio"
                ],
                "example": "chat"
              },
              "supported_params": {
                "type": "object",
                "description": "Computed parameter support after applying model-specific overrides.",
                "additionalProperties": true
              },
              "provider": {
                "type": "object",
                "required": [
                  "id",
                  "provider_id",
                  "provider_name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Provider string ID. Same value as `provider_id`.",
                    "example": "my-vllm"
                  },
                  "provider_id": {
                    "type": "string",
                    "description": "Unique provider identifier within your organization.",
                    "example": "my-vllm"
                  },
                  "provider_name": {
                    "type": "string",
                    "description": "Human-readable provider name.",
                    "example": "My vLLM Server"
                  },
                  "extra_kwargs": {
                    "type": "object",
                    "description": "Provider configuration such as `base_url` and timeout values. Secret values are not returned here.",
                    "additionalProperties": true,
                    "example": {
                      "base_url": "https://vllm.example.com/v1"
                    }
                  },
                  "created_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                },
                "additionalProperties": true,
                "nullable": true
              }
            },
            "additionalProperties": true
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "404": {
      "description": "Not Found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string"
              },
              "error": {
                "type": "string"
              }
            }
          },
          "example": {
            "error": "Not found"
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}
```

</details>
<!-- openapi-operation:end -->

<!-- openapi-path-item:start -->
<details class="api-schema-source">
<summary>OpenAPI path metadata</summary>


```json
{}
```

</details>
<!-- openapi-path-item:end -->

<!-- openapi-components:start -->
<details class="api-schema-source">
<summary>Referenced OpenAPI components</summary>


```json
{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}
```

</details>
<!-- openapi-components:end -->