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

Parametro Required Type Default Description
url Yes string - URL della pagina Web da esplorare.
query Obbligatorio per passage string - Query usata per selezionare i passaggi dalla pagina, fino a 1000 caratteri. Una passage richiesta richiede una query che non è vuota. Per altri formati, query è facoltativo. Un valore maggiore di 1000 caratteri restituisce HTTP 400. Questo limite è indipendente da maxLength.
lunghezza massima No integer 3000 (10000 con accesso completo al documento) Numero massimo di caratteri in content, da 1 a 500000. Un valore esterno a tale intervallo restituisce HTTP 400. Senza accesso completo ai documenti, content è al massimo 3000 caratteri e i valori più grandi sono limitati a 3000.
liveCrawl No string "nessuno" Controlla il comportamento di ricerca per indicizzazione in tempo reale. Valori supportati: "none" (restituisce solo contenuto indicizzato, senza ricerca per indicizzazione in tempo reale) e "fallback" (richiedere una ricerca per indicizzazione dinamica se l'URL non viene trovato nell'indice). Per "none", se l'URL non viene trovato nell'indice, l'API restituisce 404 (URL non trovato).

Nota: La ricerca per indicizzazione in tempo reale è soggetta a restrizioni e disponibilità dell'editore; "fallback" non garantisce una ricerca per indicizzazione effettiva.
includeWebLinks No boolean falso Includere collegamenti ipertestuali in uscita dalla pagina. Ignorato per il contenuto del passaggio.
renderDynamicPages No boolean falso Abilitare il rendering JavaScript per lo screenshot del contenuto dinamico. Funziona solo quando liveCrawl è impostato su "fallback".
includeImageLinks No boolean falso Includere gli URL delle immagini dalla pagina. Ignorato per il contenuto del passaggio.
language No string "en" Codice linguistico (ISO 639-1 di 2 lettere). Per l'elenco completo, vedere Lingue supportate .
region No string "US" Codice dell'area geografica (codice paese/area geografica di 2 lettere). Per l'elenco completo, vedere Aree supportate .
contentFormat No string "passaggio" ("html" con accesso completo al documento) "passaggio" restituisce le parti della pagina più rilevanti per query (consigliato per il terreno). "text", "html" e "markdown" restituiscono il documento completo e si applicano solo alle applicazioni con accesso completo al documento; senza di esso, restituiscono HTTP 403 (AuthContentFormatForbidden). Vedi Passaggi e formati di contenuto.

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

Field Type Description
host string Host per le API di intelligenza artificiale Microsoft: api.microsoft.ai.
x-apikey o autorizzazione string La chiave API o Entra ID token di accesso per l'autenticazione.
tipo di contenuto string Tipo MIME del corpo della richiesta. Utilizzare il application/json.

Risposta

Field Type Description
url string URL della pagina Web o URL da riprovare quando è in sospeso una ricerca per indicizzazione.
title string Titolo della pagina Web.
contenuto string Contenuto estratto della pagina Web (noto anche come terra). Per una richiesta di passaggio, i passaggi selezionati per query.
ultimoAggiornatoAt string La data dell'ultimo aggiornamento della pagina Web segue ISO8601 formato.
ricerca per indicizzazioneAt string L'ultima data sottoposta a ricerca per indicizzazione della pagina Web segue ISO8601 formato.
traceId string ID traccia per il debug.
retryAfter string Ora di ripetizione dei tentativi, come timestamp UTC ISO 8601 (ad esempio, "2026-10-30T01:01:00Z"). Presente quando è in corso una ricerca per indicizzazione su richiesta (202) e su alcuni errori.
isAdult boolean Indica se la pagina Web contiene contenuto per adulti.

Note

I titlecampi , isAdultcontent, lastUpdatedAt, e crawledAt sono presenti solo nelle risposte riuscite (200). Vengono omessi dalle risposte di ripetizione (202).

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

Codice di stato Categoria errore Description Cause comuni
200 Operazione completata La richiesta è stata accolta. -
202 Accettato Richiesta accettata per l'elaborazione (ricerca per indicizzazione in tempo reale). Ricerca per indicizzazione su richiesta in corso
400 Richiesta non valida Parametri di richiesta non validi. Campi obbligatori mancanti, valori di parametro non validi, JSON in formato non valido, mancante o vuoto query per una richiesta di passaggio
401 Unauthorized Autenticazione non riuscita o mancante. Chiave API non valida, intestazione x-apikey mancante
403 Non consentito Credenziali valide, ma la richiesta non può essere soddisfatta. La chiave API non dispone di autorizzazioni necessarie, URL bloccato dai criteri, contenuto filtrato, text, htmlo markdown richiesto senza accesso completo ai documenti
404 Non trovato Documento non trovato. URL non valido o inaccessibile
410 Sparito HTTPS obbligatorio. Richiesta effettuata tramite HTTP invece di HTTPS
415 Tipo di supporto non supportato Tipo di contenuto non supportato. Intestazione di tipo contenuto mancante o non corretta
429 Troppe richieste Limite di velocità o limite di ricerca per indicizzazione su richiesta superato. Troppe richieste nell'intervallo di tempo o richieste di ricerca per indicizzazione in tempo reale eccessive
430 Troppe ricerche per indicizzazione su richiesta Troppe ricerche per indicizzazione su richiesta (codici di errore legacy). Richieste di ricerca per indicizzazione in tempo reale eccessive
500 Errore interno del server Errore server imprevisto. Problema temporaneo del server
503 Servizio non disponibile Servizio temporaneamente non disponibile. Manutenzione o interruzione temporanea
504 Timeout gateway Tempo di attesa della richiesta scaduto. Timeout del servizio Upstream
520 Elaborazione del contenuto non riuscita La pagina è stata recuperata, ma non è possibile produrre contenuto utilizzabile. Elaborazione dei documenti non riuscita o timeout o timeout del rendering dinamico
523 Ricerca per indicizzazione annullata La ricerca per indicizzazione non ha prodotto contenuto a causa di una quota limitata di ricerca per indicizzazione del sito. Quota di ricerca per indicizzazione limitata per l'host di origine
524 Timeout ricerca per indicizzazione La ricerca per indicizzazione non ha prodotto contenuto perché è stato timeout. Timeout dell'host remoto

Errori delle richieste di passaggio

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

Condition Stato HTTP Codice di errore
query mancante, vuoto o più lungo di 1000 caratteri 400 HandlerInvalidInput
Un'applicazione senza richieste textdi accesso completo ai documenti , htmlo markdown 403 AuthContentFormatForbidden

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

  • Ultimo aggiornamento: