Splitting the Bill: Isolating Semantic Ranker Costs from
Agentic Retrieval Plans in Azure AI Search
One property used to control the billing consent for two very different features. That consolidation ended with REST API version 2026-04-01 — and if your service is about to migrate to it, the consent you signed for semantic ranker does not carry over to agentic retrieval. Miss this transition and one of two things happens: the ranker keeps billing while agentic retrieval silently falls to Free (breaking Foundry IQ), or agentic retrieval bills on capacity you thought was still under the single old switch.
# Microsoft's own migration warning, from the "Enable or Disable Agentic
# Retrieval Billing" documentation, restated exactly as it applies to you:
#
# "If you previously relied on semanticSearch to enable paid agentic
# retrieval usage, you must explicitly set knowledgeRetrieval to
# standard before you migrate agentic retrieval workloads to Search
# Service REST API version 2026-04-01 or later. Existing
# semanticSearch=standard consent doesn't carry over to
# knowledgeRetrieval."
# What that produces in practice — TWO opposite failure modes:
# ─── FAILURE MODE A ── Foundry IQ knowledge base returns nothing paid ──
POST /agents/{agent-name}/retrieve?api-version=2026-04-01
{
"messages": [ { "role": "user", "content": "..." } ]
}
HTTP/1.1 403 Forbidden
{
"error": {
"code": "FeatureNotEnabled",
"message": "Agentic retrieval requires the 'knowledgeRetrieval'
billing property to be set to 'standard'.
Current value: 'free' (default).
Free quota is exhausted."
}
}
# → Foundry IQ hard-stops the moment monthly free allowance runs out.
# ─── FAILURE MODE B ── surprise bill after a portal action ────────────
# Team went to Portal → Premium features → Semantic ranker: Standard.
# Portal uses REST 2025-11-01-preview, which sets semanticSearch,
# and (per Microsoft's own note) ALSO affects agentic retrieval billing.
az cost management query ... --timeframe MonthToDate
{
"Meter": "Cost"
"Semantic ranker · Standard · queries" $ 1,240
"Knowledge retrieval · agentic reasoning tokens" $ 18,600 ← unexpected
"Knowledge retrieval · query planning + answer formulation" $ 4,110 ← unexpected
}
# → You enabled one plan, the portal quietly enabled another.Symptom: Either agentic retrieval silently downgrades to the free tier the moment monthly allowance is exhausted (breaking Foundry IQ), or an intended semantic-ranker plan change unexpectedly enables agentic retrieval billing on top of it. Failure point: Two features that share one billing property in REST 2025-11-01-preview and earlier were separated into two independent properties in 2026-04-01 — with no automatic migration of the old consent. Default platform behaviour: The default value of knowledgeRetrieval is free. Existing semanticSearch=standard does not propagate.
Azure AI Search has quietly become two products stapled together. The old one — a search index with BM25, keyword, hybrid, and vector queries, and an optional Microsoft-hosted reranker called semantic ranker — is the one your team probably built with. The new one is agentic retrieval: a multi-query pipeline that uses an LLM to plan subqueries, runs them in parallel against knowledge bases, semantically reranks each of them, and merges the results. They share a service, they share indexes, and until recently they shared a single billing property. That last part changed with REST API version 2026-04-01, and the change is exactly the kind of technical detail that costs money quietly. The old consent doesn't carry over. The default is Free. And the portal still uses an older API that behaves like the old world. So the pre-upgrade window is the moment to get this right — before the platform decides for you.
The change is small, and it is the whole story. Before 2026-04-01, a single Search Management REST property — semanticSearch, with values "free" or "standard" — controlled billing consent for both semantic ranker and paid agentic retrieval on a search service. From 2026-04-01 forward, that property controls only semantic ranker, and a new property — knowledgeRetrieval — controls agentic retrieval independently. Both features can now be Free or Standard in any combination.
| Version | Property controlling semantic ranker | Property controlling agentic retrieval |
|---|---|---|
| ≤ 2025-11-01-preview | semanticSearch | semanticSearch (same property — one switch, two features) |
| ≥ 2026-04-01 | semanticSearch (now scoped to ranker only) | knowledgeRetrieval (NEW, independent) |
What Microsoft is careful to spell out — and worth reading verbatim from their own documentation — is what happens to your existing consent when the upgrade occurs. It does not carry over. If you previously relied on semanticSearch=standard to enable paid agentic retrieval, you must explicitly set knowledgeRetrieval=standard before migrating agentic retrieval workloads to the new API version.
There are two REST APIs involved and it is easy to confuse them. The Search Service (data-plane) REST API is the one your application code calls to run queries, index documents, and hit knowledge bases — that is where 2026-04-01 is the version at which the billing split takes effect for agentic retrieval workloads. The Search Management REST API is a different API, and is the one you use to set the semanticSearch and knowledgeRetrieval properties themselves. As of writing you set them via version 2026-03-01-preview. Do not mix them up — a PATCH against the data-plane API version to change billing consent will not work.
Before the fix, understand what you are actually being billed for. Agentic retrieval is not a single meter — it decomposes into four distinct billable operations, and they land on two different services on your invoice.
| Meter | What it counts | Billed by |
|---|---|---|
| Semantic reranking | Reranking passes per subquery, inside the agentic pipeline | Azure AI Search — semantic ranker meter |
| Agentic reasoning tokens | Tokens consumed by the multi-turn planner reasoning about your query | Azure AI Search — knowledge retrieval meter |
| Query planning + answer formulation | The LLM calls that decompose your question into subqueries and (optionally) synthesise the final answer | Azure OpenAI — standard PAYG on your assigned model |
| Remote knowledge source access | Separate charges for SharePoint (remote) and Web knowledge sources | Azure AI Search — per remote source |
The financial architecture here is the point of this article: your semantic ranker line item is completely separate from your agentic retrieval line items, and both are separate from the Azure OpenAI PAYG your knowledge base drives on the assigned model. Once you know that, the reason Microsoft split the consent property makes sense — it is so you can enable one without enabling the other, and see them independently on your bill.
The LLM you assign to the knowledge base drives the query planning and (optionally) answer formulation. As Microsoft's docs are explicit, the only supported model families for that role are gpt-4o, gpt-4.1, and gpt-5 series. This is not a soft "recommended" list — it is what the pipeline will accept. Point your knowledge base at gpt-4o-mini or one of the smaller supported variants when planning cost matters; the answer synthesis LLM can be a different, larger model called downstream by your own application.
This is where teams that thought they were being careful end up with surprise bills. The Azure portal has not yet caught up with the property split. The portal's Premium features blade currently uses Search Service REST API version 2025-11-01-preview — the old API where semanticSearch is still the single shared property. So when you go to the portal and toggle "Semantic ranker: Standard," you are setting a property that in your data-plane world now only affects the ranker, but that Microsoft's own note in the documentation flags: "Currently, using the portal to switch plans also affects agentic retrieval billing."
| Action | What you probably thought would happen | What actually happens today |
|---|---|---|
| Portal → Premium features → Semantic ranker: Standard | Enable semantic ranker billing only | Sets semanticSearch=standard via the old API — also affects agentic retrieval billing |
| Portal → Premium features → Knowledge retrieval: Standard | A distinct button that enables agentic retrieval only | Portal is being updated. Behaviour of the two toggles may still overlap during transition |
| Do nothing; migrate the data-plane API to 2026-04-01 | Existing consent carries over | Consent does not carry over. knowledgeRetrieval defaults to free. Free quota then depletes |
The safe move during this transition window is to bypass the portal entirely for billing changes and go straight to the Management REST API at version 2026-03-01-preview. The API is precise about which property you are setting and does not have the "also affects the other feature" side-effect. Section 6 walks through the exact PATCH calls. You can and should go back to the portal for everything else — this specific decision is the one to do in code.
Architectural Topology: Failing vs Remediated
| Aspect | Failing configuration (default drift) | Remediated configuration (fix) |
|---|---|---|
| Consent property (semantic ranker) | semanticSearch — value implicit or set through portal | semanticSearch — explicitly set to free or standard via Management REST |
| Consent property (agentic retrieval) | Not set — inherits free default at upgrade time | knowledgeRetrieval — explicitly set to free or standard via Management REST |
| Migration path | Data-plane API upgraded to 2026-04-01 with no billing consent changes | Both properties set to intended state BEFORE data-plane migration to 2026-04-01 |
| Change surface | Portal — uses old API, side-effects the other feature | Management REST at 2026-03-01-preview — precise, single-property |
| Cost visibility | Line items co-mingle on the bill; hard to attribute | Cost tags per feature; alerts scoped per meter |
| Foundry IQ dependency | Assumed to "just work" post-upgrade | Explicit dependency on knowledgeRetrieval=standard documented and monitored |
| Access rule | Anyone with Contributor can flip either plan via portal | Azure Policy denies portal-driven changes; only pipeline can set via REST |
| Free-quota exhaustion | Silent 403 in production | Alert fires at 80% free quota consumption per feature |
Before you set anything, know where you are. Read both properties on every search service in your subscription, so the change you make is deliberate rather than a guess.
The point of the audit is not to change everything to standard; it is to make the current state deliberate. A dev/test search service should almost certainly stay at free/free. A production Foundry IQ knowledge base needs knowledgeRetrieval=standard. A production classic RAG that never uses agentic retrieval should have knowledgeRetrieval=free and semanticSearch=standard — enabling agentic retrieval on it "just in case" is unnecessary spend. Match your state to your intent, service by service.
This is the fix. Two PATCH calls, one per property, using the Management REST API version 2026-03-01-preview. Do them before the workload migrates to data-plane REST 2026-04-01, so the state is deliberate when the split takes effect.
The PATCH above sets both properties in a single call, which is efficient but harder to roll back if something misbehaves. When you are doing this the first time on a production service, do the semantic ranker property in one PATCH and the knowledge retrieval property in a second — that way if a downstream monitor fires you know precisely which switch caused it. Once you have run the pattern a few times, batching is fine.
If you provision search services via IaC, both properties belong in the resource definition, not as a post-hoc PATCH. In Bicep, add semanticSearch and knowledgeRetrieval under properties on Microsoft.Search/searchServices. Provider support arrives in AzureRM and AzAPI as the property matures — for anything not yet in the mainline resource, use AzAPI (Terraform) or Microsoft.Resources/deploymentScripts (Bicep) to make the PATCH call from within your pipeline. The point is: whichever state you land on, encode it, so a future portal click can't undo it silently.
Setting the properties once is the fix. Keeping them set is the guardrail. Three cheap controls make it robust:
1. Cost alerts, per feature, per meter
Both features have Free plans with a monthly allowance and Standard plans that are pay-as-you-go past the allowance. That means the single most useful alert is one that fires at ~80% of your free-quota consumption for each feature — before the paid meter starts.
2. Azure Policy to prevent portal drift
Because the portal still uses the older API, a well-meaning teammate can flip a plan and unintentionally affect both features. An Azure Policy that audits (or denies, if you're feeling brave) any change to properties.semanticSearch or properties.knowledgeRetrieval outside a pipeline gives you a paper trail. In audit mode, the compliance dashboard tells you when something drifted; in deny mode, only your IaC pipeline can change it.
3. Tags for cost attribution
Neither of the two premium meters lands on your bill with a "team" or "cost centre" label unless you put one there. Tag the search service resource with costCentre, workload, and featureIntent (classic-rag, agentic-only, foundry-iq), and pipe those tags into your Cost Management exports. Splitting the properties bought you separate line items; tags let you attribute them.
Agentic retrieval bills across two services: Azure AI Search for reranking and reasoning tokens, and Azure OpenAI for the query planner + answer formulation model calls. If you only monitor the AI Search side, you'll miss a hot planning workload that is burning Azure OpenAI tokens without changing your Search bill much. Add a matching alert on the AOAI resource for the specific model deployment your knowledge base is pointed at.
If your service backs Microsoft Foundry IQ — the managed knowledge layer used by agents in the Foundry portal — the setting is not optional. Foundry IQ knowledge bases require a subscription and a standard knowledgeRetrieval plan. This is Microsoft's own published requirement, not an operational guideline.
Practically:
- Any search service you point at from a Foundry IQ knowledge source must have knowledgeRetrieval=standard.
- The billing appears under "Azure AI Search" on the bill, even when the caller is Foundry IQ.
- Free-tier usage still gets a monthly allowance, but as an integration path for real agent workloads it will hit the ceiling in hours, not weeks.
- Turning knowledgeRetrieval back to free "to save money" on a service that Foundry IQ agents depend on returns a 403 the moment allowance runs out. Foundry IQ knowledge bases don't degrade gracefully — they hard-stop.
Foundry IQ agentic retrieval activity is billed under Azure AI Search regardless of which Foundry portal, app, or agent triggered it. So on the invoice, you see a bigger Search bill — not a Foundry IQ line item. This is not a design flaw, but it does mean the finance team's dashboard needs a note attaching the Search spike to the responsible workload upstream, or the wrong team gets asked to explain the number.
Because the property split looks simple, the wrong instincts are strong. These are the reactions that make the situation worse.
| Anti-pattern | Why it feels right | Why it isn't |
|---|---|---|
| Set both to standard "to be safe" | "I don't want to break anything post-upgrade" | You've now enabled a paid meter that may have been free until now. If the workload never uses agentic retrieval, you'll pay for a monthly allowance you don't touch and beyond |
| Set both to free "to cut costs" | "We were spending a lot, this must save money" | Silent 403s in production as soon as the free allowance is exhausted. Foundry IQ will hard-stop |
| Toggle "Semantic ranker: Standard" in the portal | "It's the same UI I always use" | The portal still calls the old REST API. On some services it will also enable agentic retrieval billing as a side-effect — the exact thing this split was created to prevent |
| Leave everything unset and see what happens | "Microsoft will migrate the consent" | They don't. The docs are explicit: existing semanticSearch=standard consent does not carry over to knowledgeRetrieval |
| Fix production first, dev/test later | "Prod is where the money is" | Dev/test on standard is a common source of quiet spend — nobody watches the bill on the sandbox account. Fix the whole subscription in one pass |
| Use "disabled" to fully block a feature | "That value used to work" | "disabled" is no longer valid in Search Management REST 2026-03-01-preview and later. Only "free" and "standard". Use "free" plus a query-side guard rail if you need to prevent usage |
Validation & Verification: Confirm the Fix
Two failure modes are symmetric: the properties look right and the bill is wrong, or the properties look wrong and the workload starts failing. Verify both.
Four conditions must hold together. One: the audit output shows both semanticSearch and knowledgeRetrieval set to their intended values on every search service in scope. Two: your data-plane clients have migrated to REST 2026-04-01 and both feature tests above return the response you expected for the configured plan. Three: budget alerts fire on each meter individually — proving the line items are actually separated on the bill. Four: your IaC has the properties encoded, so a future portal click cannot silently undo the fix. Miss any of the four and the win is fragile.
Key Takeaways
Frequently Asked Questions
Related FAVRITE Articles
- Azure AI Search RAG Runbook
- The Missing Data RAG Pipeline Bug: 30-Second Timeouts in Azure AI Search
- The Runaway Vector Index Bill: Tuning Vector Dimensions in Azure Cosmos DB
- The PTU Math Trap: When to Pivot from Pay-As-You-Go to Provisioned Throughput