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.
Endpoint: POST https://api.microsoft.ai/v3/search/web
Sample Request:
curl -X POST "https://api.microsoft.ai/v3/search/web" \
-H "host: api.microsoft.ai" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "latest trends in LLM RAG",
"maxResults": 10,
"language": "en",
"region": "US",
"maxLength": 3000,
"contentFormat": "passage"
}'
Parameters
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
| query | Yes | string | - | A search query string. Maximum length is 1000 characters. Supports "site:" and "-site:" operators to include or exclude results from specific sites (e.g. "query site:example.com"). Use these operators only when necessary, as they inherently reduce result relevance. |
| maxResults | No | integer | 10 | Maximum number of results to return. Default is 10 and maximum value is 50. |
| language | No | string | "en" | A 2-letter ISO 639-1 language code for interface language in the search results. See Supported Languages for the full list. |
| region | No | string | "US" | A 2-letter country/region code for where the results should come from (e.g. "US", "JP", "GB", etc.). See Supported Regions for the full list. |
| location | No | string | - | Location information in format "lat:<float>;long:<float>", e.g. "lat:40.753250;long:-74.003807". If not specified, location in the query would be inferred. |
| contentFormat | No | string | "passage" | passage returns the parts of each page most relevant to the query (recommended for grounding). text, html and markdown apply only to applications enabled for full-page content; see Full-page content. Note: the web API does not return a snippet field. |
| maxLength | No | integer | 3000 | Maximum characters in content per result. Accepts 1 to 3000; higher values return at most 3000 characters. Applications enabled for full-page content can use larger values; see Full-page content. |
| safeSearch | No | string | "strict" | Level of safe search filtering. Values: "off", "strict". Default is "strict". |
Content formats
By default, each result returns the parts of the page most relevant to the query (contentFormat = passage), up to 3000 characters (maxLength = 3000). passage is also the recommended format for grounding; see What is passage, and why use it? in the FAQ. Using a format your application isn't enabled for returns HTTP 403; see Full-page content.
SafeSearch
SafeSearch modes let you control how much sensitive web content the Web API filters out before results are returned. Sensitive content includes violence, self-harm, and other categories. Default value is strict.
| Value | Description | Recommended For |
|---|---|---|
strict |
Blocks content related to adult, racy, violence, hate, and self-harm topics. | Child-safe, education, consumer/conservative deployments. |
off |
Still blocks illegal content. For other potentially harmful content, shifts responsibility for final filtering to the user. | Research, analysis, opt-in enterprise, advanced 3P use cases. |
Note
If you use the site: query operator, the response may contain adult content regardless of the safeSearch value. Use site: only if you are aware of the content on the site and your scenario supports the possibility of adult content.
Request Headers
| Field | Type | Description |
|---|---|---|
| host | string | Host for Microsoft AI APIs: api.microsoft.ai. |
| x-apikey or Authorization | string | Your API key or Entra ID access token for authentication. |
| content-type | string | MIME type of the request body. Use application/json. |
Response
Web Response
| Field | Type | Description |
|---|---|---|
| webResults | array of webResult | List of web page results. |
| querySignals | querySignals | Query-level ranking signals for the search query. |
| riskLevel | string | The safety risk level assessed for the query. Possible values: low, moderate, high, veryHigh. |
| instrumentationClickBase | string | Base URL for click ping requests. Append an instrumentationSuffix value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and instrumentationClickBase will not be included in the response. See the Instrumentation guide for setup instructions. |
| instrumentationCitationBase | string | Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. |
| traceId | string | Trace ID for debugging. |
querySignals
| Field | Type | Description |
|---|---|---|
| freshness | boolean | Indicates whether fresh documents should be prioritized over other documents for this query. |
webResult
| Field | Type | Description |
|---|---|---|
| title | string | The title of the webpage. |
| url | string | The source URL of the webpage. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl. |
| domain | string | The destination host for the result. Returned only for China users with URL redirection enabled. |
| content | string | The detailed content (aka grounding) of the webpage. |
| crawledAt | string | The last crawled date of the webpage, follows ISO8601 format. |
| lastUpdatedAt | string | The last updated date of the webpage, follows ISO8601 format. |
| language | string | The language of the webpage, uses ISO 639-1 language code. |
| isAdult | boolean | Indicates whether the result includes adult content. |
| clickUrl | string | Redirect URL that proxies the click through Bing. Only present when click redirect is enabled. |
| instrumentationSuffix | string | Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the clickUrl redirect. Present when instrumentation ping is enabled. |
| contentTier | string | The content tier of the result, describing the commercial access characteristics of the content source. Possible values: standard (standard content available to all customers under the default service offering), entitled (content available through existing customer licensing agreements, including Bring Your Own License (BYOL) content that customers have licensed directly from publishers and access through their own contractual arrangements), premium (premium content that provides additional value beyond the standard offering and is subject to billing). |
Note
Values of crawledAt and lastUpdatedAt fields are optional. That is, their coverage is not 100%. You may see empty values for these fields.
Error Codes
| Status Code | Error Category | Description | Common Causes |
|---|---|---|---|
| 200 | Success | The request succeeded. | - |
| 400 | Bad Request | Invalid request parameters. | Missing required fields, invalid parameter values, malformed JSON |
| 401 | Unauthorized | Authentication failed or missing. | Invalid API key, missing x-apikey header |
| 403 | Forbidden | Valid credentials but insufficient permissions. | API key lacks required permissions |
| 410 | Gone | HTTPS required. | Request made over HTTP instead of HTTPS |
| 415 | Unsupported Media Type | Content type not supported. | Missing or incorrect content-type header |
| 429 | Too Many Requests | Rate limit exceeded. | Too many requests in time window |
| 500 | Internal Server Error | Unexpected server error. | Temporary server issue |
| 503 | Service Unavailable | Service temporarily unavailable. | Maintenance or temporary outage |
| 504 | Gateway Timeout | Request timed out. | Upstream service timeout |
For detailed error handling guidance, see Error Handling.
See also: Videos Search | Browse | News Search | Images Search | MCP