# Search AI models

Search and filter AI models with pagination. Returns models matching all specified criteria
with scoped enablement state.

Searching for embedding models with specific vector dimension:

For embedding models, the maxOutputTokens field in the model limits represents the embedding vector dimension
(e.g., 1536 for OpenAI ada-002, 3072 for text-embedding-3-large).

To find embedding models with a specific vector size, combine:
- capabilities=EMBEDDINGS - filter to embedding models only
- minMaxOutputTokens and maxMaxOutputTokens set to the desired dimension

Example: To find embedding models with 1536-dimensional vectors:
?scope=global&capabilities=EMBEDDINGS&minMaxOutputTokens=1536&maxMaxOutputTokens=1536

RBAC:
- requires ANY of AIModels.Read, GroupAIModels.Read

Endpoint: GET /api/v1/ai-models
Version: 1.0
Security: header

## Query parameters:

  - `sortBy` (string,null)
    Supported sortBy values for this endpoint: model_name, provider_name, family, release_date, enabled

  - `builtInTools` (array,null)
    Filter by built-in tools (comma-separated: WEB_SEARCH,CODE_EXECUTION,etc)
    Enum: "WEB_SEARCH", "CODE_EXECUTION", "FILE_SEARCH", "COMPUTER_USE", "IMAGE_GENERATION", "TEXT_EDITOR", "BASH", "URL_CONTEXT", "MCP"

  - `capabilities` (array,null)
    Filter by capabilities (comma-separated: CHAT,TOOLS,VISION,etc)
    Enum: "CHAT", "EMBEDDINGS", "TOOLS", "JSON_SCHEMA", "VISION", "STREAMING", "REASONING", "ATTACHMENTS", "TEMPERATURE"

  - `deprecated` (boolean,null)
    Filter by deprecated status

  - `enabled` (boolean,null)
    Filter by enablement state in the requested scope (true=enabled only, false=disabled/unconfigured, omit for all)

  - `lastId` (string,null)
    Get older records (records with IDs less than this value) Alias maxId/max_id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `limit` (integer,null)

  - `maxContextWindow` (integer,null)
    Maximum context window size

  - `maxInputPrice` (number,null)
    Maximum input price per 1M tokens (USD)

  - `maxMaxOutputTokens` (integer,null)
    Maximum max output tokens (for embedding models, this is the vector dimension)

  - `maxOutputPrice` (number,null)
    Maximum output price per 1M tokens (USD)

  - `minContextWindow` (integer,null)
    Minimum context window size

  - `minMaxOutputTokens` (integer,null)
    Minimum max output tokens (for embedding models, this is the vector dimension)

  - `modalities` (array,null)
    Filter by modalities (comma-separated: TEXT,IMAGE,AUDIO,VIDEO,PDF)
    Enum: "TEXT", "IMAGE", "AUDIO", "VIDEO", "PDF"

  - `offset` (integer,null)

  - `openWeights` (boolean,null)
    Filter by open weights status

  - `providerId` (string,null)
    Filter by provider ID
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `scope` (string, required)
    Scope: 'global' or group TypeId

  - `search` (string,null)
    Search in name, family, and external ID (case-insensitive partial match)

  - `sortOrder` (string,null)
    Sort order. Supported values: ASC or DESC

  - `untilId` (string,null)
    Get newer records (records with IDs greater than this value) Alias minId/min_id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

## Response 200 fields (application/json):

  - `models` (array, required)
    List of AI models matching the filter criteria

  - `models.modelId` (object, required)
    Model unique identifier

  - `models.providerId` (object, required)
    Provider this model belongs to

  - `models.externalId` (string, required)
    External model ID used by the provider (e.g., 'gpt-4.1')

  - `models.name` (string, required)
    Display name for the model

  - `models.enabled` (boolean,null, required)
    Whether the model is enabled in the requested scope (null if no scoped record)

  - `models.deprecated` (boolean, required)
    Whether the model is deprecated

  - `models.successorModelId` (string,null, required)
    Successor model ID if deprecated
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `models.capabilities` (object, required)
    Model capabilities

  - `models.capabilities.supportsChat` (boolean)
    Supports chat completions

  - `models.capabilities.supportsEmbeddings` (boolean)
    Supports embeddings generation

  - `models.capabilities.supportsTools` (boolean)
    Supports tool/function calling

  - `models.capabilities.supportsJsonSchema` (boolean)
    Supports JSON schema response format

  - `models.capabilities.supportsVision` (boolean)
    Supports image input (vision)

  - `models.capabilities.supportsStreaming` (boolean)
    Supports streaming responses

  - `models.capabilities.supportsReasoning` (boolean)
    Supports reasoning/chain-of-thought

  - `models.capabilities.supportsAttachments` (boolean)
    Supports file attachments (images, PDFs, etc.)

  - `models.capabilities.supportsTemperature` (boolean)
    Supports temperature parameter

  - `models.modalities` (array, required)
    Supported input/output modalities
    Enum: "TEXT", "IMAGE", "AUDIO", "VIDEO", "PDF"

  - `models.builtInTools` (array, required)
    Built-in tools supported natively by the provider for this model
    Enum: "WEB_SEARCH", "CODE_EXECUTION", "FILE_SEARCH", "COMPUTER_USE", "IMAGE_GENERATION", "TEXT_EDITOR", "BASH", "URL_CONTEXT", "MCP"

  - `models.limits` (object, required)
    Token limits

  - `models.limits.maxInputTokens` (integer,null)
    Maximum input tokens

  - `models.limits.maxOutputTokens` (integer,null)
    Maximum output tokens

  - `models.limits.contextWindow` (integer,null)
    Total context window size

  - `models.pricing` (object,null, required)
    Pricing information

  - `models.pricing.inputPer1MTokens` (number,null)
    Cost per 1M input tokens in USD

  - `models.pricing.outputPer1MTokens` (number,null)
    Cost per 1M output tokens in USD

  - `models.pricing.cacheReadPer1MTokens` (number,null)
    Cost per 1M cached read tokens in USD

  - `models.pricing.cacheWritePer1MTokens` (number,null)
    Cost per 1M cached write tokens in USD

  - `models.family` (string,null, required)
    Model family (e.g., 'gpt-4o', 'claude-opus')

  - `models.releaseDate` (string,null, required)
    Model release date

  - `models.knowledgeCutoff` (string,null, required)
    Knowledge cutoff date

  - `models.openWeights` (boolean, required)
    Whether model has open weights

  - `models.createdAt` (string, required)
    When the model was created
    Example: "2022-03-10T16:15:50Z"

  - `models.updatedAt` (string, required)
    When the model was last updated
    Example: "2022-03-10T16:15:50Z"

  - `totalCount` (integer, required)
    Total number of models matching the filter (before pagination)

  - `pageCount` (integer, required)
    Total number of pages

  - `page` (integer, required)
    Current page number (0-indexed)

  - `pageSize` (integer, required)
    Number of items per page