Informazioni di riferimento sulle API REST

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

Richiesta di esempio:

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

I passaggi sono il formato consigliato per il terraggio. Le applicazioni con accesso completo ai documenti possono invece richiedere l'intera pagina impostando contentFormat su text, htmlo markdown. Vedi Passaggi e formati di contenuto.

Parameters

Per le richieste di passaggio, impostare su contentFormat "passaggio" e inviare un oggetto nonblank query. Se si esce da contentFormat, "passaggio" è l'impostazione predefinita, a meno che l'applicazione non abbia accesso completo al documento, dove il valore predefinito è "html". Una richiesta di passaggio senza restituisce query HTTP 400 (HandlerInvalidInput).

Richieste di passaggio

Una richiesta di passaggio è soggetta alla normale convalida della richiesta, oltre a quanto segue:

• query deve contenere testo diverso da spazi vuoti e contenere al massimo 1000 caratteri. In caso contrario, la richiesta restituisce HTTP 400 (HandlerInvalidInput).
• liveCrawl deve essere "none" o "fallback".

Tramite MCP, questi errori restituiscono HTTP 200 con un errore dello strumento (result.isError: true) che contiene l'ID richiesta originale. Il passaggio viene restituito nel campo esistente content . La risposta ha la stessa forma di per altri formati di contenuto.

Contenuto passaggio

Un passaggio è un estratto incentrato sulle query della pagina richiesta. Anziché restituire la pagina dall'inizio, il servizio seleziona le parti della pagina più pertinenti e query le restituisce nel content campo.

• Selezione: la pagina è suddivisa in segmenti, classificati per pertinenza in query. I segmenti con classificazione più alta vengono selezionati fino a quando non viene raggiunto il maxLength budget.
• Ordinamento: i segmenti selezionati vengono restituiti nell'ordine di pagina originale, non nell'ordine di classificazione. I segmenti non adiacenti sono separati da ....
• Limiti di segmento: i segmenti sono definiti per lunghezza anziché per frase o paragrafo, in modo che un estratto possa iniziare o terminare la frase media. Visualizzare i passaggi come estratti e usare l'origine url per l'attribuzione.
• Formato: il contenuto del passaggio è testo normale. I riferimenti a markup, collegamenti ipertestuali e immagini non sono inclusi in content.
• Lunghezza:content non supera mai i maxLength caratteri. Il valore predefinito maxLength è 3000 senza accesso completo al documento e 10000 con accesso completo al documento. Le pagine brevi possono essere restituite completamente.
• Fallback: se la selezione della pertinenza non è temporaneamente disponibile per una richiesta, il servizio restituisce l'inizio della pagina come testo normale, troncato a maxLength.
• Restrizioni relative al contenuto: i criteri dell'editore e del sito, ad esempio direttive robot e regole paywall, vengono applicati prima della selezione. I passaggi vengono selezionati solo dal contenuto che può essere restituito per la pagina.
• Altro comportamento: La risoluzione degli URL, la ricerca per indicizzazione in tempo reale con "fallback", le risposte di ricerca per indicizzazione in sospeso (HTTP 202), i campi di risposta, titlead esempio , crawledAte isAdult, e le risposte di errore sono uguali per altri formati di contenuto.

Intestazioni della richiesta

Risposta

Esempio: richiesta e risposta di passaggio

La richiesta nell'esempio precedente restituisce una risposta simile alla seguente. Il servizio ha selezionato segmenti non adiacenti della pagina e li ha uniti a ....

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

Codici di errore

Errori delle richieste di passaggio

Questi errori si applicano alle richieste di passaggio. Si applicano anche quando "passaggio" è il formato predefinito.

Codici di errore granulari

I codici di errore granulari sono abilitati per impostazione predefinita per Sfoglia. Identificano il motivo specifico per cui non è stato possibile restituire una pagina, ad esempio il filtro del contenuto, un documento mancante o un errore di ricerca per indicizzazione e includere indicazioni sui tentativi, se applicabile. Non è richiesta alcuna richiesta di consenso esplicito o di supporto.

Per l'elenco completo dei codici e delle azioni consigliate, vedere Esplorare gli errori specifici dell'API.

Per indicazioni dettagliate sulla gestione degli errori, vedere Gestione degli errori.

Vedere anche:Ricerca video web Ricerca | | immaginiricerca | notizie Ricerca | MCP