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

接地には、パッサージュが推奨される形式です。完全なドキュメントアクセス権を持つアプリケーションは、text、html、またはmarkdownにcontentFormatを設定することで、ページ全体を要求できます。「パッセージとコンテンツ形式」を参照してください。

Parameters

パラメーター	Required	タイプ	Default	Description
url	はい	文字列	-	参照する Web ページの URL。
クエリ	必須 `passage`	文字列	-	ページから一節を選択するために使用されるクエリ。最大 1,000 文字。 `passage`要求には、空白ではないクエリが必要です。その他の形式の場合、 `query` は省略可能です。 1000 文字を超える値は、HTTP 400 を返します。この制限は、 `maxLength`とは無関係です。
マックスレングス	いいえ	整数	3000 (完全なドキュメントアクセス権を持つ 10000)	`content`内の最大文字数 (1 から 500000)。その範囲外の値は HTTP 400 を返します。完全なドキュメントアクセスがない場合、 `content` は最大 3,000 文字で、大きい値は 3,000 文字に制限されます。
liveCrawl	いいえ	文字列	"none"	ライブクロール動作を制御します。サポートされている値: "none" (ライブクロールなしでインデックス付きコンテンツのみを返す) と "フォールバック" (URL がインデックスに見つからない場合はライブクロールを要求します)。 "none" の場合、インデックスに URL が見つからない場合、API は 404 (URL が見つかりません) を返します。注: ライブクロールは、発行元の丁寧性の制限と可用性の対象となります。"フォールバック" では、実際のクロールは保証されません。
includeWebLinks	いいえ	boolean	偽り	ページからの送信ハイパーリンクを含めます。継代コンテンツの場合は無視されます。
renderDynamicPages	いいえ	boolean	偽り	動的コンテンツのスクリーンショットに対して JavaScript レンダリングを有効にします。 liveCrawl が "フォールバック" に設定されている場合にのみ機能します。
includeImageLinks	いいえ	boolean	偽り	ページの画像 URL を含めます。継代コンテンツの場合は無視されます。
言語	いいえ	文字列	"en"	言語コード (2 文字の ISO 639-1)。完全な一覧については、「サポートされている言語」を参照してください。
リージョン	いいえ	文字列	"US"	地域コード (2 文字の国/地域コード)。完全な一覧については、「サポートされているリージョン」を参照してください。
コンテンツフォーマット	いいえ	文字列	"passage" ("html" with full document access)	"passage" は、 `query` に最も関連するページの部分を返します (接地に推奨)。 "text", "html", and "markdown" は完全なドキュメントを返し、完全なドキュメントアクセス権を持つアプリケーションにのみ適用されます。これを指定しないと、HTTP 403 (`AuthContentFormatForbidden`) が返されます。「パッセージとコンテンツ形式」を参照してください。

通過要求の場合は、 contentFormat を "passage" に設定し、非空白の queryを送信します。 contentFormatを省略した場合、アプリケーションが完全なドキュメントアクセスを持っていない限り、既定値は "passage" です。既定値は "html" です。 queryのないパッセージ要求は、HTTP 400 (HandlerInvalidInput) を返します。

パッサージュリクエスト

通過要求は、通常の要求検証と次の条件の対象となります。

query は、空白以外のテキストを含み、最大 1,000 文字にする必要があります。それ以外の場合、要求は HTTP 400 (HandlerInvalidInput) を返します。
liveCrawl は、"none" または "fallback" である必要があります。

MCP を使用すると、元の要求 ID を含むツールエラー (result.isError: true) で HTTP 200 が返されます。通路は既存の content フィールドに返されます。応答の形状は、他のコンテンツ形式と同じです。

パッサージュコンテンツ

一節は、要求されたページのクエリに焦点を当てた抽出です。サービスは、最初からページを返す代わりに、 query に最も関連するページの部分を選択し、 content フィールドに返します。

選択: ページはセグメントに分割され、 queryとの関連性によってランク付けされます。最も高いランクのセグメントは、 maxLength 予算に達するまで選択されます。
順序付け: 選択したセグメントは、ランク付け順ではなく、元のページ順で返されます。隣接していないセグメントは、 ...で区切ります。
セグメントの境界: セグメントは文または段落ではなく長さで定義されるため、抜粋は文の途中で開始または終了できます。抜粋として一節を表示し、属性のソース url を使用します。
形式: 通路の内容はプレーンテキストです。マークアップ、ハイパーリンク、およびイメージ参照は、 contentには含まれません。
Length:content が maxLength 文字を超えることはありません。既定の maxLength は、フルドキュメントアクセスなしで 3000、完全なドキュメントアクセス権を持つ 10000 です。短いページは完全に返すことができます。
フォールバック: 要求に対して関連性の選択が一時的に使用できない場合、サービスはページの先頭をプレーンテキストとして返し、 maxLengthに切り捨てます。
コンテンツの制限: ロボットディレクティブやペイウォールルールなど、発行元とサイトのポリシーは、選択前に適用されます。パッサージュは、ページに対して返すことができるコンテンツからのみ選択されます。
その他の動作: URL 解決、"フォールバック" によるライブクロール、保留中のクロール (HTTP 202) 応答、 title、 crawledAt、 isAdultなどの応答フィールド、エラー応答は、他のコンテンツ形式の場合と同じです。

要求ヘッダー

Field	タイプ	Description
ホスティング	文字列	Microsoft AI API のホスト: `api.microsoft.ai`。
x-apikey または Authorization	文字列	認証用の API キーまたはEntra IDアクセストークン。
コンテンツタイプ	文字列	要求本文の MIME の種類。 `application/json` を使用してください。

応答

Field	タイプ	Description
url	文字列	Web ページの URL、またはクロールが保留中のときに再試行する URL。
title	文字列	ウェブページのタイトル。
コンテンツ	文字列	Web ページの抽出されたコンテンツ (別名グラウンド)。継代要求の場合、 `query`のために選択された通路。
lastUpdatedAt	文字列	Web ページの最終更新日は、ISO8601形式に従います。
crawledAt	文字列	Web ページの最後のクロール日は、ISO8601形式に従います。
traceId	文字列	デバッグ用のトレース ID。
retryAfter	文字列	ISO 8601 UTC タイムスタンプ (たとえば、 `"2026-10-30T01:01:00Z"`) として再試行する最も早い時刻。オンデマンドクロールが進行中 (202)、およびいくつかのエラー時に表示されます。
isAdult	boolean	Web ページに成人用コンテンツが含まれているかどうかを示します。

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	成功	要求は成功しました。	-
202	承認済み	処理を受け入れた要求 (ライブクロール)。	進行中のオンデマンドクロール
400	正しくない要求	要求パラメーターが無効です。	必須フィールドが見つからない、パラメーター値が無効、JSON の形式が正しくない、通過要求の `query` がない、または空白である
401	Unauthorized	認証に失敗したか、見つかりません。	無効な API キー、x-apikey ヘッダーがありません
403	許可されていません	有効な資格情報ですが、要求を満たすことはできません。	API キーに必要なアクセス許可がない、ポリシーによってブロックされた URL、フィルター処理されたコンテンツ、`text`、`html`、または完全なドキュメントアクセスなしで要求された`markdown`
404	見つかりません	ドキュメントが見つかりません。	無効またはアクセスできない URL
410	使用されていないリソース (Gone)	HTTPS が必要です。	HTTPS ではなく HTTP 経由で行われた要求
415	サポートされていないメディアの種類	コンテンツタイプはサポートされていません。	コンテンツタイプヘッダーが見つからないか、正しくない
429	要求が多すぎます	レート制限またはオンデマンドクロール制限を超えました。	時間枠内の要求が多すぎる、または過剰なライブクロール要求
430	オンデマンドクロールが多すぎます	オンデマンドクロールが多すぎます (レガシエラーコード)。	過剰なライブクロール要求
500	サーバー内部エラー	予期しないサーバーエラー。	一時的なサーバーの問題
503	サービス利用不可	サービスは一時的に使用できません。	メンテナンスまたは一時的な停止
504	ゲートウェイのタイムアウト	リクエストがタイムアウトしました。	アップストリームサービスのタイムアウト
520	コンテンツ処理に失敗しました	ページが取得されましたが、使用可能なコンテンツを生成できませんでした。	ドキュメントの処理に失敗したかタイムアウトしたか、動的レンダリングがタイムアウトしました
523	クロールが取り消されました	サイトのクロールクォータが制限されているため、クロールでコンテンツが生成されませんでした。	ソースホストの制限付きクロールクォータ
524	クロールタイムアウト	クロールはタイムアウトしたため、コンテンツを生成しませんでした。	リモートホストがタイムアウトしました

継代要求エラー

これらのエラーは、通過要求に適用されます。 "passage" が既定の形式である場合にも適用されます。

状態	HTTP の状態	エラーコード
`query` が見つからない、空白、または 1000 文字を超える	400	`HandlerInvalidInput`
`text`、`html`、または完全なドキュメントアクセス要求がないアプリケーション`markdown`	403	`AuthContentFormatForbidden`

詳細なエラーコード

詳細なエラーコードは、[参照] で既定で有効になっています。コンテンツのフィルター処理、ドキュメントの不足、クロールの失敗など、ページが返されなかった具体的な理由を特定し、必要に応じて再試行ガイダンスを含めます。オプトインまたはサポート要求は必要ありません。

コードと推奨されるアクションの完全な一覧については、「 API 固有のエラーを参照する」を参照してください。

エラー処理のガイダンスの詳細については、「エラー処理」を参照してください。

Web Search | Videos Search | News Search | Images Search | MCPも参照してください。

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-11-01