Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Endpunkt:POST https://api.microsoft.ai/v3/browse
Beispielanforderung:
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"
}'
Passagen sind das empfohlene Format für die Erdung. Anwendungen mit Volldokumentzugriff können stattdessen die gesamte Seite anfordern, indem contentFormat sie auf text, , htmloder markdown. Siehe Abschnitte und Inhaltsformate.
Parameters
| Parameter | Required | Typ | Vorgabe | Description |
|---|---|---|---|---|
| url | Yes | string | - | Die URL der webseite, die durchsucht werden soll. |
| query | Erforderlich für passage |
string | - | Die Abfrage, die zum Auswählen von Passagen auf der Seite verwendet wird, bis zu 1000 Zeichen. Eine passage Anforderung erfordert eine Abfrage, die nicht leer ist. Bei anderen Formaten query ist dies optional. Ein Wert, der länger als 1000 Zeichen ist, gibt HTTP 400 zurück. Dieser Grenzwert ist unabhängig von maxLength. |
| Maximale Länge | No | integer | 3000 (10000 mit Volldokumentzugriff) | Die maximale Anzahl von Zeichen in content, von 1 bis 500000. Ein Wert außerhalb dieses Bereichs gibt HTTP 400 zurück. Ohne vollständigen Dokumentzugriff content sind höchstens 3000 Zeichen vorhanden, und größere Werte werden auf 3000 begrenzt. |
| liveCrawl | No | string | "none" | Steuert das Verhalten der Live-Durchforstung. Unterstützte Werte: "none" (nur indizierte Inhalte ohne Live-Durchforstung zurückgeben) und "Fallback" (Fordern Sie eine Live-Durchforstung an, wenn die URL nicht im Index gefunden wird). Wenn die URL für "none" nicht im Index gefunden wird, gibt die API 404 zurück (URL nicht gefunden). Hinweis: Die Live-Durchforstung unterliegt Publisher-Höflichkeitseinschränkungen und -verfügbarkeit; "Fallback" garantiert keine tatsächliche Durchforstung. |
| includeWebLinks | No | boolean | Falsch | Schließen Sie ausgehende Links von der Seite ein. Wird für Passageninhalte ignoriert. |
| renderDynamicPages | No | boolean | Falsch | Aktivieren sie das JavaScript-Rendering für den Screenshot dynamischer Inhalte. Funktioniert nur, wenn liveCrawl auf "Fallback" festgelegt ist. |
| includeImageLinks | No | boolean | Falsch | Schließen Sie Bild-URLs von der Seite ein. Wird für Passageninhalte ignoriert. |
| language | No | string | „de“ | Der Sprachcode (2 Buchstaben ISO 639-1). Die vollständige Liste finden Sie unter "Unterstützte Sprachen ". |
| region | No | string | "US" | Der Regionscode (2-Buchstaben-Länder-/Regionscode). Die vollständige Liste finden Sie unter "Unterstützte Regionen ". |
| contentFormat | No | string | "passage" ("html" mit Volldokumentzugriff) | "Passage" gibt die Teile der Seite zurück, die am relevantesten sind query (empfohlen für die Erdung). "text", "html" und "markdown" geben das vollständige Dokument zurück und gelten nur für Anwendungen mit vollständigem Dokumentzugriff; ohne sie geben HTTP 403 (AuthContentFormatForbidden) zurück. Siehe Abschnitte und Inhaltsformate. |
Legen Sie für Passagenanfragen auf "Passage" fest contentFormat und senden Sie eine nicht leere query. Wenn Sie auslassen contentFormat, ist "Passage" die Standardeinstellung, es sei denn, Ihre Anwendung verfügt über vollständigen Dokumentzugriff, wobei der Standardwert "html" ist. Eine Passage-Anforderung ohne query HTTP 400 (HandlerInvalidInput).
Passage-Anforderungen
Eine Passagenanforderung unterliegt der normalen Anforderungsüberprüfung sowie den folgenden:
-
querymuss anderen Text als Leerzeichen enthalten und höchstens 1000 Zeichen lang sein. Andernfalls gibt die Anforderung HTTP 400 (HandlerInvalidInput) zurück. -
liveCrawlmuss "none" oder "fallback" sein.
Über MCP geben diese Fehler HTTP 200 mit einem Toolfehler (result.isError: true) zurück, der die ursprüngliche Anforderungs-ID enthält. Die Passage wird im vorhandenen content Feld zurückgegeben; die Antwort hat das gleiche Shape wie bei anderen Inhaltsformaten.
Passageninhalt
Eine Passage ist ein abfrageorientiertes Extrahieren der angeforderten Seite. Anstatt die Seite von Anfang an zurückzugeben, wählt der Dienst die Teile der Seite aus, für die content sie am relevantesten sindquery, und gibt sie im Feld zurück.
-
Auswahl: Die Seite ist in Segmente unterteilt, die nach Relevanz
querybewertet werden. Die Segmente mit der höchsten Rangfolge werden bis zum Erreichen desmaxLengthBudgets ausgewählt. -
Sortierung: Ausgewählte Segmente werden in der ursprünglichen Seitenreihenfolge und nicht in der Rangfolge zurückgegeben. Nicht angrenzende Segmente werden durch
.... -
Segmentbegrenzungen: Segmente werden durch Länge und nicht durch Satz oder Absatz definiert, sodass ein Auszug den Mittleren Satz beginnen oder beenden kann. Zeigen Sie Passagen als Auszüge an, und verwenden Sie die Quelle
urlfür die Zuschreibung. -
Format: Passageninhalt ist Nur-Text. Markup-, Hyperlinks- und Bildverweise sind nicht enthalten
content. -
Länge:
contentÜberschreitet niemalsmaxLengthZeichen. Der StandardwertmaxLengthist 3000 ohne Volldokumentzugriff und 100000 mit Volldokumentzugriff. Kurze Seiten können vollständig zurückgegeben werden. -
Fallback: Wenn die Relevanzauswahl für eine Anforderung vorübergehend nicht verfügbar ist, gibt der Dienst den Anfang der Seite als Nur-Text zurück, der abgeschnitten wird
maxLength. - Inhaltsbeschränkungen: Herausgeber- und Websiterichtlinien wie Roboterdirektiven und Paywall-Regeln werden vor der Auswahl angewendet. Passagen werden nur aus Inhalten ausgewählt, die für die Seite zurückgegeben werden können.
-
Anderes Verhalten: URL-Auflösung, Livecrawling mit "Fallback", ausstehende Durchforstungsantworten (HTTP 202), Antwortfelder wie
title,crawledAtundisAdultFehlerantworten sind identisch mit anderen Inhaltsformaten.
Anforderungsheader
| Feld | Typ | Description |
|---|---|---|
| host | string | Host für Microsoft AI-APIs: api.microsoft.ai. |
| x-apikey oder Autorisierung | string | Ihr API-Schlüssel oder Entra ID Zugriffstoken für die Authentifizierung. |
| Inhaltstyp | string | MIME-Typ des Anforderungstexts. Verwenden Sie application/json. |
Antwort
| Feld | Typ | Description |
|---|---|---|
| url | string | Die URL der Webseite oder die URL, die wiederholt werden soll, wenn eine Durchforstung aussteht. |
| title | string | Der Titel der Webseite. |
| Inhalt | string | Der extrahierte Inhalt der Webseite (auch als Erdung bezeichnet). Für eine Passagenanfrage, die Passagen ausgewählt für query. |
| lastUpdatedAt | string | Das datum der letzten Aktualisierung der Webseite folgt ISO8601 Format. |
| crawledAt | string | Das letzte durchforstete Datum der Webseite folgt ISO8601 Format. |
| traceId | string | Ablaufverfolgungs-ID für das Debuggen. |
| retryAfter | string | Die früheste Wiederholungszeit als ISO 8601 UTC-Zeitstempel (z. B "2026-10-30T01:01:00Z". ). Vorhanden, wenn eine On-Demand-Durchforstung ausgeführt wird (202) und bei einigen Fehlern. |
| isAdult | boolean | Gibt an, ob die Webseite erwachsene Inhalte enthält. |
Note
Die titleFelder , content, , isAdultund crawledAtlastUpdatedAtFelder sind nur in erfolgreichen Antworten (200) vorhanden. Sie werden aus Wiederholungsantworten (202) weggelassen.
Beispiel: Passage-Anforderung und Antwort
Die Anforderung im obigen Beispiel gibt eine Antwort wie die folgende zurück. Der Dienst wählte nicht angrenzende Segmente der Seite aus und verknüpfte sie mit ....
{
"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"
}
Fehlercodes
| Statuscode | Fehlerkategorie | Description | Häufige Ursachen |
|---|---|---|---|
| 200 | Success | Die Anfrage war erfolgreich. | - |
| 202 | Akzeptiert | Anforderung für die Verarbeitung akzeptiert (Live-Durchforstung). | On-Demand-Durchforstung wird ausgeführt |
| 400 | Ungültige Anforderung | Ungültige Anforderungsparameter. | Fehlende Pflichtfelder, ungültige Parameterwerte, falsch formatierter JSON-Code, fehlender oder leerer query Wert für eine Passagenanforderung |
| 401 | Unauthorized | Fehler bei der Authentifizierung oder fehlender Authentifizierung. | Ungültiger API-Schlüssel, fehlender x-apikey-Header |
| 403 | Verboten | Gültige Anmeldeinformationen, anforderung kann jedoch nicht erfüllt werden. | API-Schlüssel verfügt nicht über erforderliche Berechtigungen, URL, die durch Richtlinien, gefilterte Inhalte, texthtmloder markdown angefordert ohne vollständigen Dokumentzugriff blockiert wurde. |
| 404 | Nicht gefunden | Das Dokument wurde nicht gefunden. | Ungültige oder nicht zugängliche URL |
| 410 | Nicht vorhanden (Gone) | HTTPS erforderlich. | Anforderung über HTTP anstelle von HTTPS |
| 415 | Nicht unterstützter Medientyp | Der Inhaltstyp wird nicht unterstützt. | Fehlender oder falscher Inhaltstypheader |
| 429 | Zu viele Anforderungen | Der Grenzwert für die Durchforstung bei Bedarf wurde überschritten. | Zu viele Anforderungen im Zeitfenster oder übermäßige Live-Durchforstungsanforderungen |
| 430 | Zu viele On-Demand-Durchforstungen | Zu viele On-Demand-Durchforstungen (Legacyfehlercodes). | Übermäßige Live-Durchforstungsanforderungen |
| 500 | Interner Serverfehler | Unerwarteter Serverfehler. | Temporäres Serverproblem |
| 503 | Dienst nicht verfügbar | Der Dienst ist vorübergehend nicht verfügbar. | Wartung oder vorübergehender Ausfall |
| 504 | Gateway-Zeitüberschreitung | Zeitüberschreitung bei der Anforderung. | Timeout des Upstream-Diensts |
| 520 | Fehler bei der Inhaltsverarbeitung | Die Seite wurde abgerufen, aber es konnten keine verwendbaren Inhalte erstellt werden. | Fehler bei der Dokumentverarbeitung oder timeout oder dynamisches Rendering |
| 523 | Durchforstung abgebrochen | Die Durchforstung hat aufgrund des eingeschränkten Websitedurchforstungskontingents keine Inhalte erzeugt. | Begrenztes Durchforstungskontingent für den Quellhost |
| 524 | Durchforstungstimeout | Die Durchforstung hat keinen Inhalt erzeugt, da es ein Timeout gab. | Timeout des Remotehosts |
Fehler bei Passage-Anforderung
Diese Fehler gelten für Passagenanforderungen. Sie gelten auch, wenn "Passage" das Standardformat ist.
| Bedingung | HTTP-Status | Fehlercode |
|---|---|---|
query fehlt, leer oder länger als 1000 Zeichen. |
400 | HandlerInvalidInput |
Eine Anwendung ohne vollständige Dokumentzugriffsanforderungen text, htmloder markdown |
403 | AuthContentFormatForbidden |
Granulare Fehlercodes
Granulare Fehlercodes sind standardmäßig für "Durchsuchen" aktiviert. Sie identifizieren den spezifischen Grund, warum eine Seite nicht zurückgegeben werden konnte, z. B. Inhaltsfilterung, fehlendes Dokument oder Durchforstungsfehler, und fügen ggf. Wiederholungsanleitungen ein. Es ist keine Opt-In- oder Supportanfrage erforderlich.
Die vollständige Liste der Codes und empfohlenen Aktionen finden Sie unter Durchsuchen API-spezifischer Fehler.
Ausführliche Anleitungen zur Fehlerbehandlung finden Sie unter "Fehlerbehandlung".
Siehe auch:Web search | Videos Search | News Search | Images Search | MCP