Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This reference lists the exact endpoints, headers, request and response fields, errors, and resource properties for model router in Microsoft Foundry. Use it to look up an identifier quickly. For step-by-step guidance, follow the links in each section.
- Set
modeltoautofor Auto (model router without a deployment, preview), or to your model router deployment name. - Responses and Chat Completions use the
/openai/v1/path, and Messages uses/anthropic/v1/. Noapi-versionquery parameter is needed. - Per-request controls, session affinity, and routing metadata (preview) require the
Foundry-Features: ModelRouterControls=V1Previewheader. - The
modelfield in every response names the model that answered.
Important
Features or capabilities marked (preview) in this article are in public preview and are subject to the Supplemental Terms of Use for Microsoft Azure Previews. Previews are provided without a service-level agreement, and Microsoft doesn't recommend them for production workloads. Certain features might not be supported or might have constrained capabilities.
Endpoints
| API | Resource endpoint | Project endpoint |
|---|---|---|
| Responses | https://<resource>.services.ai.azure.com/openai/v1/responses |
https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1/responses |
| Chat Completions | https://<resource>.services.ai.azure.com/openai/v1/chat/completions |
https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1/chat/completions |
| Messages (preview) | https://<resource>.services.ai.azure.com/anthropic/v1/messages |
Not available |
- All five endpoints accept Auto and model router deployments.
- The
https://<resource>.openai.azure.com/openai/v1/host also works for Responses and Chat Completions. - Only Claude models answer Messages requests, and each one must be deployed in the same Foundry resource.
For guidance, see Choose an endpoint.
Authentication
| Setting | Responses and Chat Completions | Messages (preview) |
|---|---|---|
| API key header | api-key: <key> or Authorization: Bearer <key> |
x-api-key: <key>. Sending api-key instead of x-api-key returns HTTP 401. |
| Microsoft Entra ID header | Authorization: Bearer <token> |
Authorization: Bearer <token> |
| Token scope | https://ai.azure.com/.default |
https://ai.azure.com/.default |
| Role for Microsoft Entra ID | Foundry User on the resource or project | Foundry User on the resource or project |
For code samples, see Authenticate. For roles, see Role-based access control for Microsoft Foundry.
Request fields
| Field | Type | API | Description |
|---|---|---|---|
model |
string | All | auto for Auto, or your model router deployment name. model-router also works for Auto when your resource has no deployment with that name. If your resource has a deployment named auto, requests with model set to auto go to that deployment. |
max_tokens |
integer | Messages | Required. |
previous_response_id |
string | Responses | Continues a conversation. Model router considers the earlier turns when it ranks models, and uses the ID to identify the conversation for session affinity. |
conversation |
string or object | Responses | Continues a conversation. Model router considers the earlier turns when it ranks models, and uses the conversation ID to identify the conversation for session affinity. |
routing_config (preview) |
object | All | Per-request controls. Requires the Foundry-Features: ModelRouterControls=V1Preview header. Without the header, model router ignores the object. |
routing_config.mode |
string | All | balanced, quality, or cost (case-insensitive). Overrides the routing mode for this request. |
routing_config.models |
array of strings | All | Model names without versions, for example ["gpt-5.6-sol", "claude-sonnet-5"]. Case-insensitive; duplicates are ignored; must be non-empty. Routes only across these models for this request, and one model pins the request to that model. Narrows routing only: listed models that the deployment's model subset or Auto's model list doesn't include are ignored, and HTTP 400 is returned if none remain. With require_parameters set to true, any such model returns HTTP 400. Claude models need a deployment in your resource. |
routing_config.require_parameters |
boolean | All | false (default) or true. When true, only models that support every parameter you sent are eligible. If none qualify, the request fails with HTTP 400, and no model is called. |
routing_config.session_affinity |
object | All | Session affinity for this request. |
routing_config.session_affinity.strategy |
string | All | adaptive (the default when you send the header), sticky, or none. The older field name mode is still accepted. |
routing_config.session_affinity.session_id |
string | All | Identifies a conversation for session affinity. 1–256 characters, and not only whitespace. Mustn't contain secrets or personal data. Model router ignores an invalid value and doesn't return the ID in the response. |
Send reasoning effort in each API's native field. routing_config has no reasoning-effort field.
| API | Reasoning effort field |
|---|---|
| Chat Completions | reasoning_effort |
| Responses | reasoning.effort |
| Messages | output_config.effort |
By default, model router drops optional parameters that the selected model doesn't support, such as temperature, top_p, presence_penalty, frequency_penalty, logit_bias, logprobs, and stop on reasoning models, or a reasoning effort on non-reasoning models. With routing_config.require_parameters set to true, the request fails with HTTP 400 instead. For details, see How model router handles parameters and Control model router routing per request.
Request headers
| Header | API | Value | Description |
|---|---|---|---|
Foundry-Features |
All | ModelRouterControls=V1Preview |
Preview. Turns on per-request controls, session affinity (adaptive by default), and routing metadata in the response. Without it, model router ignores routing_config and routes each request independently. |
x-ms-session-id |
All | A session ID of 1–256 characters | Preview. Identifies a conversation for session affinity when the body has no valid routing_config.session_affinity.session_id. Mustn't contain secrets or personal data. |
api-key |
Responses, Chat Completions | <key> |
API key. The Messages API doesn't accept it in place of x-api-key (HTTP 401). |
Authorization |
All | Bearer <token>, or Bearer <key> for Responses and Chat Completions |
Microsoft Entra ID token with scope https://ai.azure.com/.default, or an API key. |
x-api-key |
Messages | <key> |
API key for the Messages API. |
anthropic-version |
Messages | For example, 2023-06-01 |
Optional. Defaults to 2023-06-01. |
anthropic-beta |
Messages | Anthropic beta feature names | Passed through to the selected model. Support depends on the model. |
Response fields
Every response includes model. With the Foundry-Features: ModelRouterControls=V1Preview header, responses also include model_selection_details (preview). Its fields are optional during the preview, so parse them defensively and tolerate fields that you don't recognize.
| Field | Type | Description |
|---|---|---|
model |
string | The model that served the request, for example gpt-5.6-luna-2026-07-09. |
reasoning.effort |
string | Responses API only. The reasoning effort that an OpenAI reasoning model used. Claude models don't report it. |
model_selection_details.model_router_details |
object | Preview. Routing metadata for the request. |
model_selection_details.model_router_details.mode |
string | The routing mode used: balanced, quality, or cost. |
model_selection_details.model_router_details.routing_trace |
array | Ordered routing entries. One entry for Chat Completions. Responses can include one entry per output item. |
model_selection_details.model_router_details.routing_trace[].output_id |
string | Responses only. The output item that the entry describes. |
model_selection_details.model_router_details.routing_trace[].latency_ms |
number | The latency reported for the entry, in milliseconds. |
model_selection_details.model_router_details.routing_trace[].attempts |
array | The ordered model attempts. More than one attempt means that failover happened. |
model_selection_details.model_router_details.routing_trace[].attempts[].model |
string | The model attempted, for example gpt-5.6-luna. |
model_selection_details.model_router_details.routing_trace[].attempts[].result.status |
integer | The HTTP status of the attempt. |
model_selection_details.model_router_details.routing_trace[].attempts[].result.error.code |
string | The error code, when the attempt failed. |
model_selection_details.model_router_details.routing_trace[].attempts[].result.error.message |
string | The error message, when the attempt failed. |
model_selection_details.model_router_details.session_affinity |
object | The session affinity outcome. Omitted when model router can't look up or save the model association. |
model_selection_details.model_router_details.session_affinity.strategy |
string | adaptive, sticky, or none. |
model_selection_details.model_router_details.session_affinity.source |
string | Where the conversation identity came from: session_id_payload, session_id_header, derived_fingerprint, or not_available. Omitted when the strategy is none. |
model_selection_details.model_router_details.session_affinity.decision |
string | initialize (first turn or new association), retain (same model as the previous turn), or switch (a different model served this turn). Omitted when the strategy is none. |
Where the routing metadata appears:
| Response | Location of model_selection_details |
|---|---|
| Responses, Chat Completions, or Messages, without streaming | The response body |
| Responses, streaming | The response object in the response.completed event |
| Chat Completions, streaming | The final chunk, which has no choices |
| Messages, streaming | The message_delta event |
The response doesn't show whether your own deployment or router-managed capacity served the request. The following Chat Completions response, from a later turn of a conversation, shows model and model_selection_details:
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1794000000,
"model": "gpt-5.6-luna-2026-07-09",
"choices": [
{
"index": 0,
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": "Retrieval-augmented generation retrieves relevant passages from your data and adds them to the prompt, so the model can ground its answer in them."
}
}
],
"usage": {
"prompt_tokens": 412,
"completion_tokens": 31,
"total_tokens": 443
},
"model_selection_details": {
"model_router_details": {
"mode": "balanced",
"session_affinity": {
"strategy": "adaptive",
"source": "derived_fingerprint",
"decision": "retain"
},
"routing_trace": [
{
"latency_ms": 840,
"attempts": [
{ "model": "gpt-5.6-luna", "result": { "status": 200 } }
]
}
]
}
}
}
For parsing code, see Get per-request routing details and Check the affinity decision.
Errors
| Error | API | Cause | Resolution |
|---|---|---|---|
HTTP 400, invalid_routing_config |
All | routing_config isn't a JSON object. |
Send an object, for example { "mode": "cost" }. |
HTTP 400, invalid_routing_mode |
All | routing_config.mode isn't balanced, quality, or cost. |
Use one of the three values. |
HTTP 400, invalid_routing_models |
All | routing_config.models isn't a non-empty array of non-empty strings. |
Send at least one model name, without a version. |
HTTP 400, invalid_require_parameters |
All | routing_config.require_parameters isn't a boolean. |
Send true or false. |
HTTP 400, invalid_session_affinity |
All | routing_config.session_affinity isn't an object, or its strategy isn't supported. |
Send an object with strategy set to adaptive, sticky, or none. |
| HTTP 400, with a message that no model in the routing pool can preserve all requested parameters | All | routing_config.require_parameters is true, and no eligible model supports every parameter you sent. No model is called. |
Remove the unsupported parameter, add models that support it to routing_config.models, or set require_parameters to false. |
| HTTP 400 | All (Auto) | Auto is turned off for the resource: properties.instant.modelAllowList doesn't include the model-router entry. |
Add the model-router entry to modelAllowList, or call your model router deployment. See Turn off Auto. |
| HTTP 400 | Messages | No Claude deployment is available to the model router deployment or to Auto. | Deploy a Claude model from the pool in the same Foundry resource. See Add Claude models. |
| HTTP 401 | Messages | The request sent api-key instead of x-api-key. |
Send x-api-key or a Microsoft Entra token. |
| HTTP 429 | All | The request exceeded the TPM or RPM limit of your model router deployment, or Auto's limit. | Retry with exponential backoff, or add capacity. See When you reach the limit. |
Insufficient quota available for instant inference |
All (Auto) | All of the subscription's Global Standard model router quota is assigned to deployments. | Reduce or delete unused model router deployments, or request more quota. See Quota for Auto. |
Without the Foundry-Features header, model router ignores routing_config instead of returning an error. Model router also ignores an invalid session ID instead of returning an error. For more symptoms, see Troubleshoot model router.
Deployment properties
Create or update a model router deployment with the Azure Resource Manager API:
PUT https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource>/deployments/<deployment>?api-version=2025-10-01-preview
| Property | Values | Description |
|---|---|---|
sku.name |
GlobalStandard, DataZoneStandard |
The deployment type. |
sku.capacity |
Integer | The capacity in units. One unit is 1,000 TPM and 1 RPM. The default when you deploy is 10 units (10,000 TPM). |
properties.model.format |
OpenAI |
The model format of model router. |
properties.model.name |
model-router |
The model name of model router. |
properties.model.version |
2025-11-18 |
The generally available version and the default for new deployments. The preview versions 2025-08-07 and 2025-05-19 retire on January 27, 2027. |
properties.routing.mode |
balanced (default), quality, cost |
The deployment's routing mode. |
properties.routing.models[] |
Array of { "format", "name", "version" } objects |
The model subset. Each entry names a model from the model pool by format, name, and version. Omit it to route across the full pool. |
properties.raiPolicyName |
A content filter (guardrail) name | The content filter for all traffic to and from the deployment. |
Changes to the routing mode or model subset take up to five minutes to take effect. The following request body deploys model router with the Balanced mode and a three-model subset. The Claude model in the subset needs its own deployment in the same resource.
{
"sku": { "name": "GlobalStandard", "capacity": 10 },
"properties": {
"model": { "format": "OpenAI", "name": "model-router", "version": "2025-11-18" },
"routing": {
"mode": "balanced",
"models": [
{ "format": "OpenAI", "name": "gpt-5.6-sol", "version": "2026-07-09" },
{ "format": "OpenAI", "name": "gpt-5.6-luna", "version": "2026-07-09" },
{ "format": "Anthropic", "name": "claude-sonnet-5", "version": "1" }
]
}
}
}
For portal, Azure CLI, and Bicep steps, see Deploy model router.
Resource properties for Auto
Auto's settings apply to the whole Foundry resource (account), in properties.instant. Set them with Azure Resource Manager API version 2026-01-15-preview:
- REST API or
az rest:PATCH https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource>?api-version=2026-01-15-preview - Bicep:
Microsoft.CognitiveServices/accounts@2026-01-15-preview
| Property | Values | Description |
|---|---|---|
properties.instant.routing.mode |
balanced, quality, cost (case-insensitive) |
Auto's default routing mode for the resource. Without it, Auto uses the Balanced mode. A request's routing_config.mode overrides it. |
properties.instant.routing.models[] |
Array of { "format", "name", "version" } objects |
Auto's model subset for the resource. Can't be empty when present. Model router ignores models that aren't available to Auto. A request's routing_config.models can narrow it, but can't add models. |
properties.instant.modelAllowList[] |
Array of { "format", "name", "version" } objects |
The models that can be called without a deployment (instant access). An empty array ([]) turns off all instant access, including Auto. Outside West US 3, Auto is the only instant-access model. In West US 3, to turn off Auto but keep other instant-access models, leave out { "format": "OpenAI", "name": "model-router", "version": "2025-11-18" }. A new list replaces the old one; it doesn't merge. |
properties.instant.raiPolicyName |
A content filter policy name, for example Microsoft.DefaultV2 |
The content filter policy for Auto and other instant-access models. |
An update to properties.instant resets routing and raiPolicyName when you leave them out, and keeps the current modelAllowList. Each model in modelAllowList must support instant access in the resource's region, or the update fails with HTTP 400. After you set modelAllowList, you can replace it but not remove it.
The properties.instant.routing object has this shape:
{
"mode": "quality",
"models": [
{ "format": "OpenAI", "name": "gpt-5.6-sol", "version": "2026-07-09" },
{ "format": "OpenAI", "name": "gpt-6-sol", "version": "2026-09-22" }
]
}
For steps, see Configure Auto for your resource and Govern Auto. For instant access in general, see Enterprise controls.
REST API reference
- Create a model response: the Responses API request and response schema.
- Create a chat completion: the Chat Completions API request and response schema.
- Deployments - Create Or Update: the Azure Resource Manager operation that creates and updates model router deployments.
- Claude Messages API: Anthropic's reference for the Messages API format.