瀏覽 REST API 參考

端點:POST https://api.microsoft.ai/v3/browse

範例請求:

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"
  }'

段落是建議的接地格式。 擁有 完整文件存取 權的應用程式則可透過設定 contentFormat 為 text、 html、 或 markdown來請求整個頁面。 請參閱 段落與內容格式。

Parameters

參數 Required 類型 Default Description
url Yes 字串 - 瀏覽網頁的網址。
查詢 所需條件 passage 字串 - 查詢用於從頁面中選取最多 1000 個字元的段落。 請求 passage 需要一個不是空白的查詢。 其他格式則 query 為可選。 超過 1000 字元的值則會回傳 HTTP 400。 此極限與 無關 maxLength。
最大長度 No 整數 3000(10000 可完整存取文件) 中最大字元 content數為 1 到 500000。 超出該範圍的值會回傳 HTTP 400。 若無法完全存取文件, content 最多為 3000 字元,較大值上限為 3000 字元。
活爬行 No 字串 「沒有」 控制活爬行行為。 支援的值有:「無」(僅回傳已索引的內容,無即時爬取)及「備援」(若索引中找不到該網址,請即時爬取)。 對於「無」,如果索引中找不到該 URL,API 會回傳 404(找不到 URL)。

註: 即時爬蟲會受到出版商禮貌限制及可用性的限制;「備用」並不保證真的會爬行。
includeWebLinks No boolean 假的 請附上頁面的外發超連結。 被忽略了,沒有進入通道內容。
renderDynamicPages No boolean 假的 啟用 JavaScript 渲染以進行動態內容截圖。 只有在 liveCrawl 設為「備用」時才有效。
includeImageLinks No boolean 假的 請附上頁面上的圖片網址。 被忽略了,沒有進入通道內容。
語言 No 字串 「en」 語言代碼(兩字母 ISO 639-1)。 完整列表請參閱 支援語言 。
區域 No 字串 "US" 區域代碼(兩字母國家/地區代碼)。 完整列表請參閱 支援區域 。
contentFormat No 字串 「段落」(「HTML」,具備完整文件存取權) 「passage」回傳頁面中最相關的 query 部分(建議用於接地)。 「text」、「html」和「markdown」會回傳完整文件,且僅適用於具備 完整文件存取權的應用程式;若無此,則回傳 HTTP 403(AuthContentFormatForbidden)。 請參閱 段落與內容格式。

對於通道請求,設 contentFormat 為「passage」並發送非空白 query的 。 如果你省略 contentFormat了,除非你的應用程式擁有完整文件存取權,否則預設是「html」。 沒有 的 query 段落請求會回傳 HTTP 400 (HandlerInvalidInput)。

通行申請

通過請求需通過正常的請求驗證,並包含以下條件:

  • query 必須包含除留白以外的文字,且最多 1000 字元。 否則請求會回傳 HTTP 400(HandlerInvalidInput)。
  • liveCrawl 必須是「無」或「備用」。

在 MCP 上,這些失敗會回傳 HTTP 200 並帶有原始請求 ID 的工具錯誤result.isError: true()。 文章會返回現有 content 欄位;回應的形狀與其他內容格式相同。

段落內容

文章是請求頁面中以查詢為導向的擷取。 服務不會從頁面一開始回傳,而是選擇頁面中最相關的query部分,並在欄位中回傳。content

  • 選取: 頁面被劃分為多個段落,依相關 query性排序。 排名最高的單元會被選中,直到 maxLength 預算達到。
  • 排序: 所選片段依原始頁面順序回傳,而非排名順序。 非相鄰的段由 分隔 ...。
  • 段落邊界: 段落以長度定義,而非句子或段落,因此摘錄可以從句子中開始或結束。 將段落作為摘錄展示,並使用來源 url 作為歸屬。
  • 格式: 文章內容為純文字。 標記、超連結和圖片參考不包含在 content內。
  • 長度:content 永遠不會超越 maxLength 角色。 預設 maxLength 值為 3000 不需完整文件存取,10000 不需完整文件存取。 短頁可全文退回。
  • 備用: 若相關性選擇暫時無法用於請求,服務會以純文字回傳頁面開頭,並截短為 maxLength。
  • 內容限制: 在選擇前會先適用出版商與網站政策,如機器人指令及付費牆規則。 段落僅從可返回頁面的內容中選取。
  • 其他行為: URL 解析、帶「備援」的即時爬行、待處理爬行(HTTP 202)回應、回應欄位如 title、 crawledAt、 isAdult及 ,以及錯誤回應與其他內容格式相同。

要求標頭

Field 類型 Description
主持人 字串 Microsoft AI API 主機: api.microsoft.ai
x-apikey 或 授權 字串 你的 API 金鑰或 Entra ID 存取權杖用於認證。
內容類型 字串 請求實體的 MIME 類型。 請使用 application/json。

回應

Field 類型 Description
url 字串 網頁的網址,或爬行待處理時重試的網址。
title 字串 網頁的標題。
內容 字串 網頁中擷取的內容(也就是接地)。 對於通道請求,選取的 query通道。
最後更新時間 字串 網頁最後更新日期依照ISO8601格式。
crawledat 字串 網頁最後爬取日期依ISO8601格式呈現。
traceId 字串 用於除錯的追蹤識別碼。
重試之後 字串 最早重試時間,作為 ISO 8601 UTC 時間戳記(例如, "2026-10-30T01:01:00Z")。 當隨需爬蟲進行時(202 頁),以及一些錯誤時會顯示。
是成人 boolean 顯示該網頁是否包含成人內容。

Note

title, content, isAdult, lastUpdatedAt, crawledAt 和 欄位僅出現在成功(200)個回應中。 重試(202)回答中未包含這些選項。

範例:通過請求與回應

上述範例中的請求回傳如下回應。 該服務選擇了頁面中不相鄰的區段,並與 合併。...

{
  "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"
}

錯誤代碼

狀態代碼 錯誤類別 Description 常見的原因
200 Success 請求成功。 -
202 已接受 請求已接受處理(即時爬蟲)。 隨選爬行進行中
400 錯誤的請求 請求參數無效。 缺少必填欄位、無效參數值、JSON格式錯誤、文章請求缺少或空白query
401 Unauthorized 驗證失敗或缺失。 API 金鑰無效,缺少 x-apikey 標頭
403 禁止 憑證有效但無法完成申請。 API 金鑰缺乏必要的權限,URL 被政策封鎖,內容被過濾,text或htmlmarkdown請求但無法完整存取文件
404 找不到 找不到文件。 網址無效或無法存取
410 消失了 需要 HTTPS 認證。 請求是透過 HTTP 而非 HTTPS 進行的
415 不支援媒體類型 內容類型不支援。 缺少或錯誤的內容類型標頭
429 過多要求 速率上限或按需爬取上限已超過。 時間窗口內請求過多,或是過多的即時爬取請求
430 太多隨選爬蟲 太多隨選爬蟲(舊有錯誤代碼)。 過度的即時爬蟲請求
500 內部伺服器錯誤 未預期的伺服器錯誤。 臨時伺服器問題
503 服務不可用 服務暫時無法使用。 維護或暫時停電
504 閘道逾時 要求已逾時。 上游服務逾時
520 內容處理失敗 該頁面被檢索,但無法產生可用的內容。 文件處理失敗或逾時,或動態渲染逾時
523 爬行取消 由於網站爬取配額有限,這次爬取無法產生內容。 原始主機的有限爬取配額
524 爬行暫停 爬行因為逾時而無法產生內容。 遠端主機超時了

通道請求錯誤

這些錯誤適用於通過申請。 當「passage」是預設格式時,這些規則也適用。

條件 HTTP 狀態 錯誤碼
query 缺少、空白或超過1000字元 400 HandlerInvalidInput
沒有完整文件存取請求text的應用程式,或 htmlmarkdown 403 AuthContentFormatForbidden

粒度錯誤碼

瀏覽時預設啟用細緻錯誤碼。 它們會明確指出頁面無法回傳的具體原因,例如內容過濾、文件遺失或爬取失敗,並在適用時附上重試指引。 不需要主動加入或請求支援。

完整代碼清單及建議操作,請參見 瀏覽 API 特定錯誤。

如需詳細的錯誤處理指引,請參見 錯誤處理。


另見:網站搜尋 | 影片 搜尋 | 新聞 搜尋 | 圖片 搜尋 | MCP