Browse REST API reference

Endpoint: POST https://api.microsoft.ai/v3/browse

Sample Request:

curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    "query": "How fast is Web IQ",
    "contentFormat": "passage",
    "maxLength": 3000,
    "liveCrawl": "fallback",
    "language": "en",
    "region": "US"
  }'

Passages are the recommended format for grounding. Applications with full document access can instead request the whole page by setting contentFormat to text, html, or markdown. See Passages and content formats.

Parameters

For passage requests, set contentFormat to "passage" and send a nonblank query. If you leave out contentFormat, "passage" is the default unless your application has full document access, where the default is "html". A passage request without a query returns HTTP 400 (HandlerInvalidInput).

Passage requests

A passage request is subject to the normal request validation, plus the following:

• query must contain text other than whitespace and be at most 1000 characters. Otherwise the request returns HTTP 400 (HandlerInvalidInput).
• liveCrawl must be "none" or "fallback".

Over MCP, these failures return HTTP 200 with a tool error (result.isError: true) that carries the original request ID. The passage is returned in the existing content field; the response has the same shape as for other content formats.

Passage content

A passage is a query-focused extract of the requested page. Instead of returning the page from the beginning, the service selects the parts of the page most relevant to query and returns them in the content field.

• Selection: the page is divided into segments, which are ranked by relevance to query. The highest-ranked segments are selected until the maxLength budget is reached.
• Ordering: selected segments are returned in their original page order, not in ranking order. Non-adjacent segments are separated by ....
• Segment boundaries: segments are defined by length rather than by sentence or paragraph, so an excerpt can begin or end mid-sentence. Display passages as excerpts and use the source url for attribution.
• Format: passage content is plain text. Markup, hyperlinks, and image references aren't included in content.
• Length: content never exceeds maxLength characters. The default maxLength is 3000 without full document access and 10000 with full document access. Short pages can be returned in full.
• Fallback: if relevance selection is temporarily unavailable for a request, the service returns the beginning of the page as plain text, truncated to maxLength.
• Content restrictions: publisher and site policies, such as robots directives and paywall rules, are applied before selection. Passages are selected only from content that can be returned for the page.
• Other behavior: URL resolution, live crawling with "fallback", pending crawl (HTTP 202) responses, response fields such as title, crawledAt, and isAdult, and error responses are the same as for other content formats.

Request Headers

Response

Example: passage request and response

The request in the sample above returns a response like the following. The service selected non-adjacent segments of the page and joined them with ....

{
  "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
  "title": "Why AI agents need external grounding | Microsoft Web IQ",
  "content": "Why AI agents need external grounding | Microsoft Web IQ Microsoft Community Hub Azure Microsoft Developer Community Blog nodeTitle minReadText Why AI Agents Need External Grounding bkingms Microsoft Oct 18, 2026 Earlier this year, we introduced Microsoft Web IQ, a suite of AI-native web search and grounding APIs that gives LLMs, AI agents, and applications access to current, relevant web information. This post explores why web grounding is becoming a foundational layer of AI, how it helps deliver answers customers can use and verify, and how we’re addressing the quality, speed, and efficiency developers need. -- When customers ask an AI agent or application for help, the answer may do more than inform them—it may shape a recommendation, trigger a workflow, or guide an action. If that answer relies on... ... an engineering approach that treats quality, speed, and token efficiency as a connected problem. You can read more on our engineering approach here. Highest grounding satisfaction. On a 3,000 query blind test sampled from production traffic, Web IQ scored 79.05 against 75.70 for the next best service and more than 14 points ahead of the lowest. It gets there by returning more complete, structured context drawn from web, news, images, and video. What your users see is answers that hold up: more accurate, more consistent, and properly attributed. In the domains where source quality, freshness, and attribution drive the decision, that is the difference between an agent people act on and one they quietly double check. 2.5x faster than today's best alternative. P95 latency measured 164 milliseconds across five datacenter regions, against 406 for the closest competitor and 2,090 for the slowest. Latency compounds in agent workloads, because a multi-step chain pays the retrieval cost at every hop. Cutting it at each step keeps workflows moving and keeps interactive agents feeling interactive instead of batch. Highest quality answers with the fewest tokens. Web IQ sits on a new Pareto curve of efficiency, reaching peak quality at around 40,000 tokens per query while competing services spend 60,000 to 100,000 to score lower. Prioritizing the most relevant passages and cutting unnecessary context reduces both token spend and reasoning time, and those savings compound across high volume production workloads. Most web search APIs force a tradeoff — fast or accurate, cost-efficient or complete. Web IQ is delivers across the board: industry-leading quality, fastest performance, and fewest tokens per query — all in an enterprise-ready solution. For teams evaluating Web IQ, those results provide a starting point. We recommend testing your own questions, sources, models, and end-to-end workflows to understand how retrieval quality and efficiency translate into customer outcomes. Grounding satisfaction is a benchmark score, not an accuracy percentage, and retrieval latency is only one part of the time required to complete a task. Within Microsoft IQ,...",
  "isAdult": false,
  "lastUpdatedAt": "2026-10-18T00:00:00",
  "crawledAt": "2026-10-29T07:44:00Z",
  "traceId": "6ae4fd995e3d425f847c07c2f0839e38"
}

Error Codes

Passage request errors

These errors apply to passage requests. They also apply when "passage" is the default format.

Granular error codes

Granular error codes are enabled by default for Browse. They identify the specific reason a page couldn't be returned, such as content filtering, a missing document, or a crawl failure, and include retry guidance where applicable. No opt-in or Support request is required.

For the full list of codes and recommended actions, see Browse API specific errors.

For detailed error handling guidance, see Error Handling.

See also: Web Search | Videos Search | News Search | Images Search | MCP