--- title: List AI Gateway models by canonical ID description: List all model catalog entries grouped by canonical model ID. breadcrumbs: Docs > API > List AI Gateway models by canonical ID --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List AI Gateway models by canonical ID ## v2 (latest) {% alert level="warning" %} **Note**: This endpoint is in Preview and is subject to change. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help.md). {% /alert %} | Datadog site | API endpoint | | ----------------- | ----------------------------------------------- | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/models | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/models | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/models | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/models | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/models | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/models | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/models | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/models | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/models | ### Overview List all model catalog entries grouped by canonical model ID. Requires `ai_gateway_config_read` and provider View. Catalog and pricing metadata inherit provider access. Lists omit hidden entries; direct reads of hidden resources return 404. This endpoint requires the `ai_gateway_config_read` permission. OAuth apps require the `ai_gateway_config_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#ai-gateway) to access this endpoint. ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Response containing model catalog entries grouped by canonical ID. | Parent field | Field | Type | Description | | ----------------- | --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | | | data | attributes [*required*] | object | Provider entries grouped under one canonical model ID. | | attributes | model_id_canonical [*required*] | string | Provider-independent model identifier. | | attributes | providers [*required*] | [object] | | | providers | created_at [*required*] | date-time | Time when the resource was created. | | providers | enabled [*required*] | boolean | Whether the resource is enabled. | | providers | id [*required*] | string | Resource identifier. | | providers | metadata | object | Optional, typed enrichment for a model catalog entry. Missing properties remain unknown. | | metadata | capabilities [*required*] | object | Model features reported by the enrichment source. Omitted properties are unknown. | | capabilities | attachment | boolean | Whether attachment input is supported. | | capabilities | interleaved_reasoning | boolean | Whether reasoning can be interleaved with tool use. | | capabilities | reasoning | boolean | Whether reasoning is supported. | | capabilities | structured_output | boolean | Whether structured output is supported. | | capabilities | temperature | boolean | Whether temperature can be configured. | | capabilities | tool_call | boolean | Whether tool calls are supported. | | metadata | description | string | Human-readable model description. | | metadata | display_name | string | Human-readable model name. | | metadata | family | string | Model family identifier. | | metadata | kind | enum | Primary model kind. Decision models return a choice or score instead of generated text. Allowed enum values: `language`, `embedding`, `image`, `audio`, `decision`, `reranking`. | | metadata | knowledge_cutoff | string | Knowledge cutoff reported by the source. | | metadata | last_updated | string | Date the source record was last updated. | | metadata | lifecycle | enum | Model lifecycle state. Allowed enum values: `active`, `alpha`, `beta`, `deprecated`. | | metadata | limits [*required*] | object | Token limits reported by the enrichment source. | | limits | context_window_tokens | int64 | Total model context window in tokens. | | limits | max_input_tokens | int64 | Maximum input tokens when reported separately. | | limits | max_output_tokens | int64 | Maximum output tokens. | | metadata | modalities [*required*] | object | Supported model input and output modalities. | | modalities | input | [string] | | | modalities | output | [string] | | | metadata | open_weights | boolean | Whether model weights are openly available. | | metadata | reasoning | object | Supported reasoning controls. Absence means controls are unknown or unavailable. | | reasoning | controls [*required*] | [object] | | | controls | effort_levels | [string] | Supported effort values in provider order for an effort control. | | controls | max_budget_tokens | int64 | Maximum reasoning-token budget. | | controls | min_budget_tokens | int64 | Minimum reasoning-token budget. | | controls | type [*required*] | enum | Reasoning-control mechanism. Allowed enum values: `toggle`, `effort`, `budget_tokens`. | | metadata | reference_pricing | [object] | Provider-specific reference prices from the enrichment source. Omitted for shared canonical-model fallback matches. These do not determine gateway charges. | | reference_pricing | amount [*required*] | string | Exact decimal amount per unit, zero or greater, represented as a string to preserve precision. Supports fixed decimal and exponent notation. | | reference_pricing | component [*required*] | string | Token category priced, such as input, output, cache_read, or cache_write. | | reference_pricing | context_max_tokens | int64 | Largest input length covered by this price. Omitted when there is no upper bound. | | reference_pricing | context_min_tokens [*required*] | int64 | Input length above which this price applies. Zero identifies the base tier. | | reference_pricing | currency [*required*] | string | Currency of the price. The only supported value is USD. | | reference_pricing | mode [*required*] | string | Source mode name. Standard is the base mode; other values, such as fast, are source-defined. | | reference_pricing | service_tier | string | Provider service tier explicitly associated with this mode by the source. Omitted when unknown. | | reference_pricing | unit [*required*] | string | Unit of the quoted amount. The only supported value is million_tokens. | | metadata | release_date | string | Model release date. | | metadata | source [*required*] | object | Provenance for model metadata enrichment. | | source | matched_by [*required*] | enum | Identifier strategy used to match the gateway catalog entry. Date-suffix and shared canonical-model fallback matches produce partial metadata. Allowed enum values: `override`, `wire_id`, `canonical_id`, `wire_id_date_suffix`, `canonical_model`. | | source | model_id [*required*] | string | Model identifier in the metadata source provider catalog. | | source | name [*required*] | string | Metadata source name. | | source | observed_at | date-time | Last successful observation of this valid source record. Retained invalid entries keep their previous timestamp. | | source | provider [*required*] | string | Provider namespace in the metadata source, or canonical for a shared model record. | | source | revision | string | SHA-256 content revision of the source snapshot that supplied this record. | | metadata | status [*required*] | enum | Completeness of the matched source record. Partial also identifies metadata from a base model for a dated snapshot or from a shared canonical-model fallback. Allowed enum values: `available`, `partial`. | | providers | model_id_wire [*required*] | string | Model identifier sent to the provider. | | providers | provider_id [*required*] | int64 | Provider identifier. | | providers | source [*required*] | enum | How a model catalog entry is managed. Allowed enum values: `discovered`, `manual`. | | providers | supported_operations [*required*] | [string] | Operations supported by the model. | | providers | updated_at [*required*] | date-time | Time when the resource was last updated. | | data | id [*required*] | string | Resource identifier. | | data | type [*required*] | enum | Canonical model grouping resource type. Allowed enum values: `models-by-canonical`. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "model_id_canonical": "gpt-5.2-codex", "providers": [ { "created_at": "2026-08-24T12:00:00Z", "enabled": true, "id": "101", "metadata": { "capabilities": { "attachment": false, "interleaved_reasoning": false, "reasoning": false, "structured_output": false, "temperature": false, "tool_call": false }, "description": "string", "display_name": "string", "family": "string", "kind": "string", "knowledge_cutoff": "string", "last_updated": "string", "lifecycle": "string", "limits": { "context_window_tokens": 400000, "max_input_tokens": "integer", "max_output_tokens": 128000 }, "modalities": { "input": [ "text" ], "output": [ "text" ] }, "open_weights": false, "reasoning": { "controls": [ { "effort_levels": [ "high" ], "max_budget_tokens": "integer", "min_budget_tokens": "integer", "type": "effort" } ] }, "reference_pricing": [ { "amount": "2.5", "component": "input", "context_max_tokens": 272000, "context_min_tokens": 0, "currency": "USD", "mode": "standard", "service_tier": "priority", "unit": "million_tokens" } ], "release_date": "string", "source": { "matched_by": "wire_id", "model_id": "gpt-5.2-codex", "name": "models.dev", "observed_at": "2019-09-19T10:00:00.000Z", "provider": "openai", "revision": "string" }, "status": "available" }, "model_id_wire": "gpt-5.2-codex-20260801", "provider_id": 42, "source": "discovered", "supported_operations": [ "OPENAI_CHAT_COMPLETIONS" ], "updated_at": "2026-08-24T12:00:00Z" } ] }, "id": "gpt-5.2-codex", "type": "models-by-canonical" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/models" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}