REST-API-Referenz durchsuchen

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:

  • query muss anderen Text als Leerzeichen enthalten und höchstens 1000 Zeichen lang sein. Andernfalls gibt die Anforderung HTTP 400 (HandlerInvalidInput) zurück.
  • liveCrawl muss "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 des maxLength Budgets 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 url für die Zuschreibung.
  • Format: Passageninhalt ist Nur-Text. Markup-, Hyperlinks- und Bildverweise sind nicht enthalten content.
  • Länge:content Überschreitet niemals maxLength Zeichen. Der Standardwert maxLength ist 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, crawledAtund isAdultFehlerantworten 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