---
title: "Model search"
method: GET
path: "/models"
tags: ["Models"]
---

# Model search

`GET /models`

Unified endpoint for discovering model endpoints. Supports three usage modes:

**1. List Mode** (no parameters):
Paginated list of all available model endpoints with minimal metadata.

**2. Find Mode** (`endpoint_id` parameter):
Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs.

**3. Search Mode** (search parameters):
Filter models by free-text query, category, or status.

**Expansion:**
Use `expand` to include additional data in each model object:
- `openapi-3.0` — full OpenAPI 3.0 schema in the `openapi` field
- `enterprise_status` — enterprise readiness status (`ready` or `pending`) in the `enterprise_status` field

**Examples of `endpoint_id` values:**
- `fal-ai/flux/dev`
- `fal-ai/wan/v2.2-a14b/text-to-video`
- `fal-ai/minimax/video-01/image-to-video`
- `fal-ai/hunyuan3d-v21`

See [fal.ai Model APIs](https://fal.ai/docs/documentation/model-apis/overview) for more details.

**Authentication:** Optional. Providing an API key grants higher rate limits.

**Common Use Cases:**
- Browse available models for integration
- Retrieve metadata for specific endpoints
- Search for models by category or keywords
- Get OpenAPI schemas for code generation
- Build model selection interfaces

## Query parameters

- `limit` integer — Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
- `cursor` string — Pagination cursor from previous response. Encodes the page number.
- `endpoint_id` union — Endpoint ID(s) to retrieve (e.g., 'fal-ai/flux/dev'). Can be a single value or multiple values (1-50 models). When combined with search params, narrows results to these IDs. Use array syntax: ?endpoint_id=model1&endpoint_id=model2
  - string
  - string[]
- `q` string — Free-text search query to filter models by name, description, or category
- `category` string — Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')
- `status` 'active' | 'deprecated' — Filter models by status - omit to include all statuses
- `expand` union — Fields to expand in the response. Supported values: 'openapi-3.0' (includes full OpenAPI 3.0 schema in 'openapi' field), 'enterprise_status' (includes enterprise readiness status)
  - string
  - string[]

## Response `200`

Successfully retrieved model endpoints

- object — Response containing model data with pagination support
  - `models` object[], required — Array of model information
    - `endpoint_id` string, required — Stable identifier used to call the model (e.g., 'fal-ai/wan/v2.2-a14b/text-to-video', 'fal-ai/minimax/video-01/image-to-video', 'fal-ai/hunyuan3d-v21')
    - `metadata` object — Model metadata (optional - may be absent for endpoints without registry entries)
      - `display_name` string, required — Human-readable label shown on Explore/Model pages
      - `category` string, required — Model category (e.g., 'text-to-image', 'image-to-video', 'text-to-video', 'image-to-3d', 'training')
      - `description` string, required — Brief description of the model's capabilities and use cases
      - `status` 'active' | 'deprecated', required — 'active' or 'deprecated'. Newest models are surfaced in Explore and may be flagged as 'new/beta' in tags
      - `tags` string[], required — Freeform tags such as 'new', 'beta', 'pro', or 'turbo' (Explore badges)
      - `updated_at` string, required — ISO8601 timestamp of when the model was last updated
      - `is_favorited` boolean, nullable, required — Whether the model is favorited by the authenticated user (null when unauthenticated)
      - `thumbnail_url` string, required — Main thumbnail image URL
      - `thumbnail_animated_url` string — Animated thumbnail URL (optional)
      - `model_url` string, required — Full model endpoint URL (e.g., https://fal.run/...)
      - `github_url` string — License or GitHub URL (optional)
      - `license_type` 'commercial' | 'research' | 'private' — License type for the model (optional)
      - `date` string, required — ISO8601 timestamp of model creation
      - `group` object — Model group information (optional)
        - `key` string, required — Group key identifier
        - `label` string, required — Human-readable group label
      - `highlighted` boolean, required — Whether the model is highlighted (deprecated, always false)
      - `kind` 'inference' | 'training' — Model kind - inference or training (optional)
      - `training_endpoint_ids` string[] — Related training endpoint IDs (optional, only present when non-empty, for inference models)
      - `inference_endpoint_ids` string[] — Related inference endpoint IDs (optional, only present when non-empty, for training models)
      - `stream_url` string — Streaming endpoint URL (optional)
      - `duration_estimate` number — Estimated duration in minutes (optional)
      - `pinned` boolean, required — Whether the model is pinned (deprecated, always false)
    - `openapi` union — OpenAPI 3.0 specification or error (present when expand=openapi-3.0 is requested)
      - object — OpenAPI 3.0 specification for the model
        - `openapi` string, required — OpenAPI version (e.g., '3.0.4')
      - object — Error encountered while expanding OpenAPI schema
        - `error` object, required — Error details for failed OpenAPI expansion
          - `code` string, required — Error code (e.g., 'expansion_failed')
          - `message` string, required — Human-readable error message
    - `enterprise_status` union — Enterprise readiness status (present when expand=enterprise_status is requested)
      - 'ready' | 'pending' — 'ready' means approved for enterprise use, 'pending' means awaiting approval
      - object — Error encountered while expanding enterprise status
        - `error` object, required — Error details for failed enterprise status expansion
          - `code` string, required — Error code (e.g., 'expansion_failed')
          - `message` string, required — Human-readable error message
  - `next_cursor` string, nullable — Cursor for the next page of results, null if no more pages
  - `has_more` boolean, required — Boolean indicating if more results are available (convenience field derived from next_cursor)

## Other responses

- `400` — Invalid request parameters
- `404` — Resource not found
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) · [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fal/platform-apis/revisions/0c7dabf80b00/schema)