Filter results with Scopes

Scopes in Microsoft Web IQ let you fine-tune grounding API requests by including or excluding URLs, sites, and domains from Web Search and News Search results.

Developers and enterprise administrators can use Scopes to ground AI experiences on approved and desired web sources. Define reusable inclusion and exclusion lists for URLs, domains, and paths to control which sources your grounding searches can return.

A scope is a named configuration of inclusion and exclusion rules. Create it in the Web IQ portal or Customer Management API for a billing account, then select it by name in your Web Search or News Search requests. Both management options work with the same named scopes. These search scopes are not Microsoft Entra OAuth permission scopes.

Business scenarios and common use cases

Scenario	Example use case	How to use Scopes
Curated research	Ground a research assistant in sources reviewed by your organization, such as approved medical publications.	Include the approved domains, subdomains, or individual pages.
Organizational source policies	Exclude domains restricted by your organization from Web Search and News Search grounding results.	Maintain an exclusion list and select the scope on each request.
Owned-property search	Limit a support assistant or employee-facing search experience to your public product, help, or company sites.	Include your owned domains and relevant documentation paths.
Curated news monitoring	Ground news summaries in a selected set of publishers.	Include the publisher domains and select the scope in News Search requests.

Scopes filter content available to the selected search endpoint. An included source doesn't guarantee that matching content is indexed or returned.

Prerequisites

An active Web IQ billing account.
To create scopes with the API, an existing Microsoft Entra application, its tenant ID and application (client) ID, and credentials for the OAuth 2.0 client credentials flow. Its workload identity must be active and have CustomerApiAccess on the intended Web IQ billing account.

Important

Access to the search APIs and the Web IQ management API is granted separately. A working search API key or an Entra application bound to a Web IQ runtime profile doesn't grant permission to create scopes. The workload needs a separate billing-account management grant.

To check portal access, open Scopes and look for the intended billing account and New scope control. If the page, account, or creation control is unavailable, ask your account administrator to check your access, or contact Web IQ Support.

Name your scope and choose sources

Choose a scope name with up to 128 characters after trimming. Supported characters are ASCII letters, digits, periods (.), underscores (_), and hyphens (-). Spaces and slashes aren't supported. Names are case-insensitively unique within the scope collection.

Scopes are shared by the Web IQ AppIDs in a Web IQ billing account, through that account's assigned scope collection. They are not separate configurations for each AppID. If billing accounts share a collection, they share the same scopes and names.

Inclusion limits results to sources that match at least one entry in the scope's included list. If the list is empty, all non-excluded sources are eligible.
Exclusion removes results that match any entry in the scope's excluded list, even if they also match an inclusion rule. Exclusion always takes precedence.

You can include or exclude domains, URL paths, or individual web pages. Each entry is called a selector:

Selector	Example	Matches
Domain	`example.com`	The domain and its descendant subdomains
Path prefix	`docs.example.org/products`	The specified path and its subpaths on that host, but not paths such as `/products-old`
Exact URL	`https://docs.example.org/products/guide`	That exact HTTPS URL, not every page under the path

Adding https:// makes a selector match an exact URL rather than a domain or path prefix. Wildcards such as *.example.com, explicit ports, query strings, and fragments aren't supported. Path casing is preserved. Named-scope selectors have no separate limit on subdirectory depth, but each selector must fit within 2,048 characters before trimming and after normalization.

The API normalizes, sorts, and deduplicates entries. An accepted selector doesn't guarantee that matching content is indexed or returned.

Create a scope in the portal

Open Scopes in the Web IQ portal.
Select the intended Billing account.
Select New scope. In Create new scope, enter a Scope name, such as ProductDocs, and create the scope.
On the scope detail page, use Add sites on the Included tab to add sources to include. Use the same button on the Excluded tab to add sources to exclude, such as ads.example.com.
Review both lists, select Publish, and confirm Publish changes?.

After publishing, propagation to search usually takes about 10 minutes, but can take up to 30 minutes in some cases. Verify the scope before relying on it in your application.

Select the scope in search requests

Configure runtime search authentication separately. The chosen Web IQ app profile must belong to the Web IQ billing account whose collection contains your scope.

Set the following optional fields in the JSON request body for POST https://api.microsoft.ai/v3/search/web or POST https://api.microsoft.ai/v3/search/news. Both endpoints use the same named-scope settings.

Parameter	Type	Behavior
`scopeName`	string	The name of an existing scope, such as `ProductDocs`. Its inclusion and exclusion rules filter the request's results. If omitted or `null`, no named scope is requested.
`failOnMissingScope`	boolean	Defaults to `true`, including when omitted or `null`. When `true`, a reported scope-application failure returns an error instead of unscoped results. When `false`, search can proceed without the scope if it cannot be applied. Use `false` only if unscoped results are acceptable. Has no effect without `scopeName`.

Use a separately configured runtime API key in the following examples.

Filter Web Search results

To search web pages allowed by ProductDocs, send:

POST /v3/search/web HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

Filter News Search results

To search news articles allowed by the same scope, use the News Search endpoint. Choose included sources with indexed news content; an included web page isn't necessarily available through News Search.

POST /v3/search/news HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product announcements",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

Interpret the results

Web Search returns results in webResults; News Search returns results in newsResults. A valid scope can return no matching results, for example when no indexed content matches both the query and the scope's rules.

With failOnMissingScope: true (the default), a reported scope-application failure returns an error instead of unscoped results. A confirmed missing scope returns HTTP 400 (HandlerInvalidInput); other scope-application failures return HTTP 500 (ScopeFailedToApply). See named-scope errors for recovery guidance.

If you set failOnMissingScope to false and the scope can't be found, the search runs against the entire index without the scope, and the response contains "scopeApplied": false. This can happen when the name is incorrect or the scope hasn't yet propagated to the partition or replica handling the request.

When the requested scope is found and applied, the response contains "scopeApplied": true, even if failOnMissingScope is false. This confirms application of the scope for that request, not that its latest definition was used or that the change reached every partition or replica. The response omits scopeApplied when no application outcome is reported; don't treat an absent property as proof that the scope was applied.

If you omit scopeName or set it to null, no named scope is requested and failOnMissingScope has no effect. Don't expect scopeApplied to always be present with a value of false for requests without a named scope.

Only use false if your application can accept unscoped results, and check scopeApplied in the response. When a scope is required, don't implement a fallback that removes it and retries an unrestricted request. See the Web Search and News Search references for the request parameters and response fields.

Create a scope with the API

All management requests use https://api.microsoft.ai with paths beginning /v1/customer/. Replace <billingAccountId> and <access-token> in the examples with the intended account ID and an app-only access token. The authorized-resources reference and scope management reference describe the endpoint contracts.

Grant management API access to the application

A billing-account or customer administrator grants access:

Use an existing Microsoft Entra app registration or register an application in the Azure portal.
Open Account settings in the Web IQ portal.
Select the intended billing account.
Under Management API access, select Grant access to an Entra app.
In the Grant an Entra application access to this billing account dialog, confirm the billing account name and ID. Enter the application's Tenant ID and Application (client) ID, and a nonblank value for the required Display name.
Select Grant management API access to this application, then select Grant access.

Granting access authorizes an existing identity. It doesn't create an Entra application, secret, certificate, or search API key. The grant applies to the selected billing account.

The grant assigns the CustomerApiAccess role. It isn't a scopes-only or read-only permission: it allows account discovery, scope reads and writes, and runtime profile Entra ID management. It doesn't allow the application to grant access to other applications. Limit the grant to applications that need these management capabilities.

Acquire an app-only token

Use your application's existing credentials and the client credentials flow to request a Microsoft Entra access token:

Setting	Value
Authority	`https://login.microsoftonline.com/<tenant-id>`
Token-request scope	`https://api.microsoft.ai/.default`

Use the exact .default scope, not the name of the search scope you're creating. Send the token on every management request:

Authorization: Bearer <access-token>

Don't use a search API key for these management calls. Keep access tokens and application credentials out of source control and diagnostic reports.

Discover the billing account

Call GET https://api.microsoft.ai/v1/customer/authorized-resources with your app-only token. Select the intended account's billingAccounts[].billingAccountId for the create request; don't automatically choose the first account.

Use the authorized-resources reference for the response schema, ID definitions, and permission-field interpretation.

Send the create request

Using the selected billing account ID, send POST /v1/customer/billing-accounts/{billingAccountId}/scopes with your scope name and rules. For example:

{
  "name": "ProductDocs",
  "includeSites": ["example.com", "docs.example.org/products"],
  "excludeSites": ["ads.example.com"]
}

Provide both arrays, using [] for an intentionally empty list. On 201 Created, save the returned definition and ETag for later changes.

For headers, validation rules, and response details, see the create-scope contract. To change an existing scope rather than create a new one, use the update operations.

Verify the scope before using it

Read the saved scope and confirm that its rules match your intended sources.
Run representative Web Search and News Search requests with failOnMissingScope: true. Check included and excluded cases before enabling dependent traffic.

Important

Propagation usually takes about 10 minutes, but can take up to 30 minutes in some cases. There is no propagation SLA, and these timings are not guaranteed. A successful management write or read, Publish, or scopeApplied: true doesn't prove that the latest definition is active. Don't use elapsed time alone as a readiness check. See search propagation for details.

Roll out a changed definition

If temporarily using a previous definition is unacceptable, create a scope with a new name, such as ProductDocs-v2. Complete the verification steps above before switching callers, and retain the previous scope until callers no longer depend on it.

This keeps the old name's meaning unchanged during validation; it doesn't provide an atomic global switch.

Preserve concurrency protection for later changes

Read the current scope before editing or deleting it, and send its quoted ETag in If-Match. Follow concurrency and uncertain-outcome guidance when reconciling concurrent edits or retrying a write. Keep reviewed definitions in your own source of truth if you need change history.

Troubleshoot creation

If the intended account is absent from discovery, ask the administrator to check the workload's identity, management grant, and account eligibility. For other failures, use the discovery status reference or scope management error reference.

For persistent failures, contact Web IQ Support with the billing account ID, scope name, operation time in UTC, HTTP status, and available request IDs. Include sanitized expected and actual behavior, never tokens, API keys, or application credentials.

Feedback

Was this page helpful?

Last updated on 2026-11-11