---
title: Model Search API | Runware Docs
url: https://runware.ai/docs/models-api/model-search
description: Search and discover AI models available in the Runware platform. Filter and find the right model for your generation tasks.
relatedDocuments:
  - https://runware.ai/docs/learn/text-to-image
  - https://runware.ai/docs/models-api/model-upload
  - https://runware.ai/docs/models-api/introduction
---
## Introduction

The Model Search API enables discovery of available models on the Runware platform, providing search and filtering capabilities across **public models from the community** and **private models within your organization**.

Models discovered through this API can be used immediately in generation tasks **by referencing their AIR identifiers**. This enables dynamic model selection in applications and helps discover new models for specific use cases.

The search works across model names, versions, tags, and other metadata. Multiple filters can be combined to narrow results by category, type, architecture, and visibility. Results are returned in a **paginated format** with a default of 20 models per page, controlled by the `limit` and `offset` parameters.

## Request

The Runware API always accepts an array of objects as input, where each object represents a **specific task to be performed**. The structure of the object varies depending on the type of the task. For this section, we will focus on the parameters related to the **model search task**.

The following JSON snippet shows the basic structure of a request object.

**TypeScript**:

```typescript
import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const result = await client.modelSearch({
  search: 'realistic',
  tags: 'photorealistic',
  category: 'checkpoint',
  type: 'base',
  architecture: 'sdxl',
  visibility: 'all',
  offset: 0,
  limit: 20
})
```

**Python**:

```python
import asyncio
import os

from runware import Runware

async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        result = await client.model_search({
            "search": "realistic",
            "tags": "photorealistic",
            "category": "checkpoint",
            "type": "base",
            "architecture": "sdxl",
            "visibility": "all",
            "offset": 0,
            "limit": 20
        })

asyncio.run(main())
```

**cURL**:

```bash
curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "modelSearch",
      "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
      "search": "realistic",
      "tags": "photorealistic",
      "category": "checkpoint",
      "type": "base",
      "architecture": "sdxl",
      "visibility": "all",
      "offset": 0,
      "limit": 20
    }
  ]'
```

**CLI**:

```bash
runware model search \
  -q realistic \
  --tags photorealistic \
  --category checkpoint \
  --type base \
  --architecture sdxl \
  --visibility all \
  --offset 0 \
  --limit 20
```

**JSON**:

```json
{
  "taskType": "modelSearch",
  "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
  "search": "realistic",
  "tags": "photorealistic",
  "category": "checkpoint",
  "type": "base",
  "architecture": "sdxl",
  "visibility": "all",
  "offset": 0,
  "limit": 20
}
```

---

### [taskType](#request-tasktype)

- **Type**: `string`
- **Required**: true
- **Value**: `modelSearch`

Identifier for the type of task being performed.

### [taskUUID](#request-taskuuid)

- **Type**: `string`
- **Required**: true
- **Format**: `UUID v4`

UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.

### [search](#request-search)

- **Type**: `string`
- **Required**: true

Search query to find models by name, description or AIR ID.

### [source](#request-source)

- **Type**: `string`

Filter by model source.

**Allowed values**: `featured` `community`

### [category](#request-category)

- **Type**: `string`

Filter models by category.

**Allowed values**: `checkpoint` `lora` `lycoris` `vae` `embeddings`

### [architecture](#request-architecture)

- **Type**: `string`

Filter by model architecture.

### [capabilities](#request-capabilities)

- **Type**: `array of strings`

Filter by model capabilities.

### [visibility](#request-visibility)

- **Type**: `string`

Filter by visibility status.

**Allowed values**: `public` `private` `favorite` `owned`

### [limit](#request-limit)

- **Type**: `integer`
- **Min**: `1`
- **Max**: `100`
- **Default**: `20`

Maximum number of results to return.

### [offset](#request-offset)

- **Type**: `integer`
- **Min**: `0`
- **Default**: `0`

Number of results to skip for pagination.

### [sort](#request-sort)

- **Type**: `string`
- **Default**: `popularity`

Sort order for results. A bare field name sorts ascending and a `-` prefix sorts descending, except `popularity`, whose bare value is already descending (most popular first).

**Allowed values**: `popularity` `-popularity` `name` `-name` `addedUnixTimestamp` `-addedUnixTimestamp` `updatedDateUnixTimestamp` `-updatedDateUnixTimestamp`

## Response

Results will be delivered in the format below.

```json
{
  "data": [
    {
      "results": [
        {
          "name": "Promissing_Realistic_XL",
          "air": "civitai:305149@392545",
          "tags": [
            "photorealistic",
            "base model",
            "sci-fi",
            "photo",
            "woman",
            "fantasy",
            "photorealism",
            "rpg",
            "general use",
            "close up",
            "close up shot",
            "promissing_realistic_xl"
          ],
          "heroImage": "https://mim.runware.ai/r/66a70a0bb7c38-450x450.jpg",
          "category": "checkpoint",
          "private": false,
          "comment": "",
          "version": "v22",
          "architecture": "sdxl",
          "type": "base",
          "defaultWidth": 1024,
          "defaultHeight": 1024,
          "defaultSteps": 20,
          "defaultScheduler": "Default",
          "defaultCFG": 7.5
        }
      ],
      "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
      "taskType": "modelSearch",
      "totalResults": 2
    }
  ]
}
```

---

### [taskType](#response-tasktype)

- **Type**: `string`
- **Required**: true
- **Value**: `modelSearch`

Identifier for the type of task this response belongs to.

### [taskUUID](#response-taskuuid)

- **Type**: `string`
- **Required**: true
- **Format**: `UUID v4`

UUID v4 identifier echoed from the original request, used to match async responses to their tasks.

### [totalResults](#response-totalresults)

- **Type**: `integer`
- **Required**: true
- **Min**: `0`

Total number of models matching the search criteria.

### [results](#response-results)

- **Path**: `results.air`
- **Type**: `array of objects (13 properties)`
- **Required**: true

List of models found.

#### [air](#response-results-air)

- **Path**: `results.air`
- **Type**: `string`
- **Required**: true

Artificial Intelligence Resource identifier.

#### [name](#response-results-name)

- **Path**: `results.name`
- **Type**: `string`
- **Required**: true

Model name.

#### [category](#response-results-category)

- **Path**: `results.category`
- **Type**: `string`
- **Required**: true

Model category.

**Possible values**: `checkpoint` `lora` `lycoris` `vae` `embeddings`

#### [architecture](#response-results-architecture)

- **Path**: `results.architecture`
- **Type**: `string | null`
- **Required**: true

Model architecture.

#### [capabilities](#response-results-capabilities)

- **Path**: `results.capabilities`
- **Type**: `array of strings`
- **Required**: true

Model capabilities.

#### [source](#response-results-source)

- **Path**: `results.source`
- **Type**: `string`
- **Required**: true

Model source.

**Possible values**: `featured` `community`

#### [heroImage](#response-results-heroimage)

- **Path**: `results.heroImage`
- **Type**: `string | null`
- **Required**: true
- **Format**: `uri`

Representative image URL.

#### [private](#response-results-private)

- **Path**: `results.private`
- **Type**: `boolean`
- **Required**: true

Whether the model is private.

#### [isFavorite](#response-results-isfavorite)

- **Path**: `results.isFavorite`
- **Type**: `boolean`

Whether the model is favorited.

#### [provider](#response-results-provider)

- **Path**: `results.provider`
- **Type**: `string`

Model provider.

#### [shortDescription](#response-results-shortdescription)

- **Path**: `results.shortDescription`
- **Type**: `string`

Short description.

#### [positiveTriggerWords](#response-results-positivetriggerwords)

- **Path**: `results.positiveTriggerWords`
- **Type**: `string`

Positive trigger words.

#### [negativeTriggerWords](#response-results-negativetriggerwords)

- **Path**: `results.negativeTriggerWords`
- **Type**: `string`

Negative trigger words.