list_ai_models

ArtificialIntelligenceApi.list_ai_models(role_id, limit=None, offset=None, sortorder=None, sortby=None, filter_expression=None, projection_expression=None, input_modality=None, output_modality=None, action=None, component=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List AI models

Returns available AI models. Three list modes: - When action is omitted, returns all available models. - When action is list_by_modality, returns models whose enabled modality entries intersect both input_modality and output_modality. - When action is list_by_component, returns the models allow-listed for the given component. component is required; an unknown component returns IPV-1041.

Parameters:

• role_id (str) – User role id (required)

• limit (str) – Maximum number of models to return. Defaults to 100. Values above 1000 are rejected with IPV-1050 as a 400.

• offset (str) – 1-based index of the first model to return. Defaults to 1. offset=1 returns the first model.

• sortorder (str) – Sort direction. Use asc or desc. Defaults to desc.

• sortby (str) – Model attribute to sort by. Defaults to LastModifiedTime. Sorting is a case-insensitive string comparison.

• filter_expression (str) – Substring filter applied to ModelName before sorting and pagination. total_count reflects the filtered result set.

• projection_expression (str) – Comma-separated list of attribute names to keep on each returned model. Applied after pagination, so it narrows the shape of the items.

• input_modality (str) – Used when action=list_by_modality. Input modality the model must support. Supported values are TEXT, IMAGE, and VIDEO. Defaults to ANY, which matches every supported input modality. An unrecognized value matches nothing.

• output_modality (str) – Output modality filter. Supported values are TEXT, EMBEDDING, and RERANK. - With action=list_by_modality, defaults to ANY (matches every supported output modality). - With action=list_by_component, optional with no default. When supplied, filters the component’s allow-listed models. If any requested modality is outside the component’s supported output modalities, an empty list is returned. - Ignored when action is omitted.

• action (str) – List mode. Omit to list all models. list_by_modality filters on input_modality/output_modality; list_by_component requires component. Any other value returns IPV-1041 as a 400.

• component (str) – Amorphic component whose allow-listed models should be returned. Required when action=list_by_component; omitting it returns IPV-1001 and an unknown value returns IPV-1041, both as a 400.

• _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

• _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

• _content_type (str, Optional) – force content-type for the request.

• _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

• _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

AIModelsListResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /ai/models

Success (HTTP 200)

A page of AI models. Iterate by incrementing offset by limit while next_available is “yes”, and stop when it is “no”. next_available is a string (“yes” or “no”). total_count is the size of the full result set before pagination. For the default listing and action=list_by_modality, each item uses the listing projection documented by AIModelsListObject. For action=list_by_component, items are returned with full model metadata.

Default listing, first page of a larger result set

{
  "models": [
    {
      "ModelId": "anthropic.claude-sonnet-4-6",
      "ModelName": "Claude Sonnet 4.6",
      "ModelArn": "arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-sonnet-4-6",
      "ProviderName": "Anthropic",
      "ModelStatus": "Enabled",
      "ModelStatusMessage": "Model is enabled and ready to use.",
      "ModelVersion": "v1",
      "ModelTokenLimit": "1M",
      "ModelType": "BASE",
      "ModelTraits": "Hybrid reasoning, Extended thinking, Agents, Code generation, Computer use, Long-context reasoning, Tool use, Text and image inputs, Long context",
      "ModelDescription": "Full upgrade of Anthropic's mid-tier model with improved coding, computer use, long-context reasoning, and agent planning. 1M context, 64K max output.",
      "OutputModalities": [
        "TEXT"
      ],
      "AdaptiveThinking": true,
      "Effort": [
        "low",
        "medium",
        "high",
        "max"
      ],
      "LastModifiedTime": "2026-08-11 08:55:34",
      "LastModifiedBy": "user1"
    },
    {
      "ModelId": "amazon.nova-lite-v1:0",
      "ModelName": "Nova Lite",
      "ModelArn": "arn:aws:bedrock:us-west-2::foundation-model/amazon.nova-lite-v1:0",
      "ProviderName": "Amazon",
      "ModelStatus": "Disabled",
      "ModelStatusMessage": "Enable the model to use it.",
      "ModelVersion": "1.0",
      "ModelTokenLimit": "300K",
      "ModelType": "BASE",
      "ModelTraits": "Agents, Chat optimized, Conversation, Math, Multilingual support, Question answering, RAG, Text generation, Text summarization, Translation, Text, Image, Video-to-text",
      "ModelDescription": "Nova Lite is a multimodal understanding foundation model. It is multilingual and can reason over text, images and videos.",
      "OutputModalities": [
        "TEXT"
      ],
      "AdaptiveThinking": false,
      "Effort": [],
      "LastModifiedTime": "2026-08-11 05:10:09",
      "LastModifiedBy": "user2"
    }
  ],
  "count": 2,
  "total_count": 2,
  "next_available": "no"
}

No models matched the modality or component filter

{
  "models": [],
  "count": 0,
  "total_count": 0,
  "next_available": "no"
}

Errors

Documented error codes: IPV-1050, IPV-1041, IPV-1001, GE-1010, GE-1008, DB-1002.

HTTP 400

Input validation failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1050 (limit above 1000), IPV-1041 (unknown action or component), IPV-1001 (component missing when action=list_by_component), GE-1010 (method/resource combination not routable).

limitTooLarge

{
  "Message": "IPV-1050 - Out of range for items per page, Limit is 1000"
}

invalidAction

{
  "Message": "IPV-1041 - Invalid parameter - action, allowed values/keys are list_by_modality, list_by_component"
}

componentMissing

{
  "Message": "IPV-1001 - Parameter component is a required value."
}

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. Codes: GE-1008 (catch-all), DB-1002 (DynamoDB failure).

Request / response example

{
  "Message": "GE-1008 - Could not complete the request. Please try again."
}