Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Ponto final:POST https://api.microsoft.ai/v3/browse
Pedido de Exemplo:
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"
}'
Passagens são o formato recomendado para o enraizamento. Aplicações com acesso total a documentos podem, em vez disso, solicitar a página inteira definindo contentFormat para text, html, ou markdown.
Ver Passagens e formatos de conteúdo.
Parameters
| Parameter | Required | Tipo | Default | Description |
|---|---|---|---|---|
| url | Yes | cadeia (de caracteres) | - | O URL da página web para navegar. |
| consulta | Obrigatório para passage |
cadeia (de caracteres) | - | A consulta era usada para selecionar passagens da página, até 1000 caracteres. Um passage pedido requer uma consulta que não esteja em branco. Para outros formatos, query é opcional. Um valor superior a 1000 caracteres devolve HTTP 400. Este limite é independente de maxLength. |
| comprimento máximo | No | número inteiro | 3000 (10000 com acesso completo ao documento) | O número máximo de caracteres em content, de 1 a 500000. Um valor fora desse intervalo devolve HTTP 400. Sem acesso total ao documento, content é no máximo 3000 caracteres, e valores maiores são limitados a 3000. |
| liveCrawl | No | cadeia (de caracteres) | "nenhum" | Controla o comportamento de rastejar ao vivo. Valores suportados: "nenhum" (apenas devolve conteúdo indexado, sem rastreamento ao vivo) e "fallback" (solicita um rastreamento ao vivo se o URL não estiver no índice). Para "nenhum", se o URL não for encontrado no índice, a API devolve 404 (URL não encontrado). Nota: O rastreamento ao vivo está sujeito a restrições de cortesia e disponibilidade do editor; o "plano B" não garante um rastreamento real. |
| incluiWebLinks | No | boolean | falso | Inclua hiperligações de saída da página. Ignorado para conteúdo de passagem. |
| renderDynamicPages | No | boolean | falso | Ativar a renderização em JavaScript para captura de ecrã de conteúdo dinâmico. Só funciona quando o liveCrawl está definido para "fallback". |
| incluiImagenLinks | No | boolean | falso | Inclua URLs de imagens da página. Ignorado para conteúdo de passagem. |
| linguagem | No | cadeia (de caracteres) | "en" | O código da língua (ISO 639-1 de 2 letras). Consulte Linguagens Suportadas para a lista completa. |
| região | No | cadeia (de caracteres) | "US" | O código regional (código país/região de 2 letras). Consulte Regiões Suportadas para a lista completa. |
| contentFormat | No | cadeia (de caracteres) | "passage" ("html" com acesso completo ao documento) | "passage" devolve as partes da página mais relevantes para query (recomendada para fundamentação). "text", "html" e "markdown" devolvem o documento completo e aplicam-se apenas a aplicações com acesso total ao documento; sem ele, devolvem HTTP 403 (AuthContentFormatForbidden).
Ver Passagens e formatos de conteúdo. |
Para pedidos de passagem, defina contentFormat para "passage" e envie um .query Se deixares de fora contentFormat, "passage" é o padrão, a menos que a tua aplicação tenha acesso total aos documentos, onde o padrão é "html". Um pedido de passagem sem um query retorna HTTP 400 (HandlerInvalidInput).
Pedidos de passagem
Um pedido de passagem está sujeito à validação normal do pedido, mais o seguinte:
-
querydeve conter texto que não seja espaço em branco e ter no máximo 1000 caracteres. Caso contrário, o pedido devolve HTTP 400 (HandlerInvalidInput). -
liveCrawlDeve ser "nenhum" ou "plano B".
No MCP, estas falhas devolvem HTTP 200 com um erro de ferramenta (result.isError: true) que transporta o ID original do pedido. A passagem é devolvida no campo existente content ; a resposta tem a mesma forma que para outros formatos de conteúdo.
Conteúdo da passagem
Uma passagem é um excerto focado na consulta da página solicitada. Em vez de devolver a página desde o início, o serviço seleciona as partes da página mais relevantes e query devolve-as no content campo.
-
Seleção: a página está dividida em segmentos, que são classificados pela relevância para
query. Os segmentos mais bem classificados são selecionados até que omaxLengthorçamento seja atingido. -
Ordenação: segmentos selecionados são devolvidos na ordem original das páginas, não na ordem de classificação. Segmentos não adjacentes são separados por
.... -
Limites de segmentos: os segmentos são definidos pelo comprimento em vez de por frase ou parágrafo, pelo que um excerto pode começar ou terminar a meio da frase. Mostre passagens como excertos e use a fonte
urlpara atribuição. -
Formato: o conteúdo da passagem é texto simples. Marcação, hiperligações e referências de imagem não estão incluídas em
content. -
Duração:
contentnunca ultrapassamaxLengthas personagens. O padrãomaxLengthé 3000 sem acesso total a documentos e 10000 sem acesso total a documentos. As páginas curtas podem ser devolvidas na íntegra. -
Plano B : se a seleção de relevância estiver temporariamente indisponível para um pedido, o serviço devolve o início da página como texto simples, truncado para
maxLength. - Restrições de conteúdo: políticas do editor e do site, como diretivas de robôs e regras de paywall, são aplicadas antes da seleção. As passagens são selecionadas apenas do conteúdo que pode ser devolvido para a página.
-
Outros comportamentos: Resolução de URL, rastreamento ao vivo com "fallback", respostas de rastreamento pendente (HTTP 202), campos de resposta como
title,crawledAt, eisAdult, e respostas de erro são as mesmas que para outros formatos de conteúdo.
Cabeçalhos dos Pedidos
| Field | Tipo | Description |
|---|---|---|
| alojar | cadeia (de caracteres) | Alojamento para APIs de IA da Microsoft: api.microsoft.ai. |
| x-apikey ou Autorização | cadeia (de caracteres) | A sua chave API ou token de acesso do Entra ID para autenticação. |
| tipo de conteúdo | cadeia (de caracteres) | Tipo MIME do corpo do pedido. Utilize application/json. |
Resposta
| Field | Tipo | Description |
|---|---|---|
| url | cadeia (de caracteres) | O URL da página web, ou o URL para tentar novamente quando uma pesquisa está pendente. |
| title | cadeia (de caracteres) | O título da página web. |
| conteúdo | cadeia (de caracteres) | O conteúdo extraído da página web (também conhecido como grounding). Para um pedido de passagem, as passagens selecionaram para query. |
| lastUpdatedAt | cadeia (de caracteres) | A data de última atualização da página segue ISO8601 formato. |
| rastejou | cadeia (de caracteres) | A última data rastreada da página web segue ISO8601 formato. |
| traceId | cadeia (de caracteres) | ID de rastreio para depuração. |
| retryAfter | cadeia (de caracteres) | O tempo mais cedo para tentar novamente, como um carimbo de data ISO 8601 UTC (por exemplo, "2026-10-30T01:01:00Z"). Presente quando está em curso um rastreamento on-demand (202), e em alguns erros. |
| éAdulto | boolean | Indica se a página contém conteúdo para adultos. |
Note
Os titlecampos , content, isAdult, lastUpdatedAt, e crawledAt só estão presentes em respostas bem-sucedidas (200). São omitidas nas respostas de retry (202).
Exemplo: pedido e resposta à passagem
O pedido no exemplo acima devolve uma resposta semelhante à seguinte. O serviço selecionou segmentos não adjacentes da página e juntou-os 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"
}
Códigos de erro
| Código de estado | Categoria de Erro | Description | Causas Comuns |
|---|---|---|---|
| 200 | Sucesso | O pedido foi bem-sucedido. | - |
| 202 | Aceito | Pedido aceite para processamento (live crawl). | Rastreamento on-demand em curso |
| 400 | Pedido Incorreto | Parâmetros de pedido inválidos. | Campos obrigatórios em falta, valores de parâmetros inválidos, JSON malformado, falta ou em branco query para um pedido de passagem |
| 401 | Não autorizado | Autenticação falhada ou em falta. | Chave API inválida, falta do cabeçalho x-apikey |
| 403 | Proibido | Credenciais válidas, mas o pedido não pode ser cumprido. | A chave API não tem permissões necessárias, URL bloqueada por política, conteúdo filtrado, text, html, ou markdown solicitado sem acesso total ao documento |
| 404 | Não encontrado | Documento não encontrado. | URL inválida ou inacessível |
| 410 | Desapareceu | HTTPS necessário. | Pedido feito por HTTP em vez de HTTPS |
| 415 | Tipo de Media Não Suportado | Tipo de conteúdo não suportado. | Cabeçalho de tipo de conteúdo em falta ou incorreto |
| 429 | Demasiados Pedidos | Limite de taxa ou limite de rastreamento a pedido ultrapassado. | Demasiados pedidos na janela temporal, ou pedidos excessivos de crawl ao vivo |
| 430 | Demasiadas Explorações On-Demand | Demasiadas explorações sob demanda (códigos de erro legados). | Pedidos excessivos de rastreamento ao vivo |
| 500 | Erro interno do servidor | Erro inesperado do servidor. | Problema temporário com o servidor |
| 503 | Serviço Indisponível | Serviço temporariamente indisponível. | Manutenção ou interrupção temporária |
| 504 | Tempo limite do gateway | O tempo limite da solicitação expirou. | Tempo de extinção do serviço a montante |
| 520 | Processamento de Conteúdo Falhou | A página foi recuperada, mas não foi possível produzir conteúdo utilizável. | O processamento de documentos falhou ou expirou, ou a renderização dinâmica expirou |
| 523 | Crawl Cancelado | O rastreamento não produziu conteúdo devido à quota limitada de rastreamento do site. | Quota limitada de rastreamento para o host de origem |
| 524 | Tempo de Descanso de Rastejar | O crawl não produzia conteúdo porque expirava o tempo. | O host remoto expirou o tempo |
Erros nos pedidos de passagem
Estes erros aplicam-se a pedidos de passagem. Também se aplicam quando "passage" é o formato padrão.
| Condition | Estado HTTP | Código de Erro |
|---|---|---|
query está em falta, em branco ou tem mais de 1000 caracteres |
400 | HandlerInvalidInput |
Uma aplicação sem acesso completo a documentos solicita text, html, ou markdown |
403 | AuthContentFormatForbidden |
Códigos de erro granulares
Códigos de erro granulares estão ativados por defeito para navegar. Identificam a razão específica pela qual uma página não pôde ser devolvida, como filtragem de conteúdo, um documento em falta ou uma falha de rastreamento, e incluem orientações para retentar quando aplicável. Não é necessário optar por aceitar ou pedir de Suporte.
Para a lista completa de códigos e ações recomendadas, consulte Explorar erros específicos da API.
Para orientações detalhadas sobre o tratamento de erros, consulte Gestão de Erros.
Ver também:Pesquisa | na Web Vídeos Pesquisa | Notícias Pesquisa | Imagens Pesquisa MCP |