Enable or disable semantic ranker

Semantic ranker is a premium feature billed by usage. By default, all search services are enrolled in the free plan, which provides a monthly request allowance at no charge. To enable continued access after the free quota is consumed, you can switch to the standard plan.

Check availability

To check if semantic ranker is available in your region, see the Azure AI Search regions list.

Enable semantic ranker

Semantic ranker might not be enabled on older services. Follow these steps to enable semantic ranker at the service level. Once enabled, it's available to all indexes. You can't turn it on or off for specific indexes.

Azure portal
REST

Go to your search service in the Azure portal.
On the Overview page, make sure the pricing tier is set to Basic or higher.
On the left-navigation pane, select Settings > Premium features.
Select either the Free plan (default) or the Standard plan. You can switch between the free plan and the standard plan at any time.

The free plan is capped at 1,000 queries per month. After the first 1,000 queries in the free plan, an error message indicates you exhausted your quota on the next semantic query. When quota is exhausted, you can upgrade to the standard plan to continue using semantic ranking.

To enable semantic ranker, you can use Services - Create Or Update (REST API).

Management REST API calls are authenticated through Microsoft Entra ID. For instructions on how to authenticate, see Manage your Azure AI Search service with REST APIs.

Management REST API version 2023-11-01 or later provides the configuration property.
Owner or Contributor permissions are required to enable or disable features.

Note

Create or Update supports two HTTP methods: PUT and PATCH. Both PUT and PATCH can be used to update existing services, but only PUT can be used to create a new service. If PUT is used to update an existing service, it replaces all properties in the service with their defaults if they aren't specified in the request. When PATCH is used to update an existing service, it only replaces properties that are specified in the request. When using PUT to update an existing service, it's possible to accidentally introduce an unexpected scaling or configuration change. When enabling semantic ranking on an existing service, it's recommended to use PATCH instead of PUT.

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01
    {
      "properties": {
        "semanticSearch": "standard"
      }
    }

Disable semantic ranker using the REST API

To turn off feature enablement, or for full protection against accidental usage and charges, you can disable semantic ranker by using the Create or Update Service API on your search service. After the feature is disabled, any requests that include the semantic query type are rejected.

Management REST API calls are authenticated through Microsoft Entra ID. For instructions on how to authenticate, see Manage your Azure AI Search service with REST APIs.

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01
    {
      "properties": {
        "semanticSearch": "disabled"
      }
    }

To re-enable semantic ranker, run the previous request again and set semanticSearch to either Free (default) or Standard.

Next step

Configure semantic ranker

Last updated on 2026-06-01

Enable or disable semantic ranker

Check availability

Enable semantic ranker

Disable semantic ranker using the REST API

Next step

Additional resources