Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Ponto de extremidade:POST https://api.microsoft.ai/v3/browse
Solicitação 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"
}'
As passagens são o formato recomendado para aterramento. Aplicativos com acesso completo a documentos podem, em vez disso, solicitar a página inteira definindo contentFormat como text, htmlou markdown. Consulte Trechos e formatos de conteúdo.
Parameters
| Parâmetro | Required | Tipo | Default | Description |
|---|---|---|---|---|
| url | Yes | cadeia | - | A URL da página da Web a ser navegada. |
| consulta | Necessário para passage |
cadeia | - | A consulta usada para selecionar passagens da página, até 1000 caracteres. Uma passage solicitação requer uma consulta que não esteja em branco. Para outros formatos, query é opcional. Um valor maior que 1000 caracteres retorna HTTP 400. Esse limite é independente de maxLength. |
| comprimento máximo | No | inteiro | 3000 (10000 com acesso completo a documentos) | O número máximo de caracteres em content, de 1 a 500000. Um valor fora desse intervalo retorna HTTP 400. Sem acesso completo a documentos, content são no máximo 3.000 caracteres e valores maiores são limitados a 3000. |
| liveCrawl | No | cadeia | "nenhum" | Controla o comportamento de rastreamento dinâmico. Valores com suporte: "none" (retornar somente conteúdo indexado, sem rastreamento ao vivo) e "fallback" (solicite um rastreamento dinâmico se a URL não for encontrada no índice). Para "none", se a URL não for encontrada no índice, a API retornará 404 (URL não encontrada). Observação: O rastreamento ao vivo está sujeito a restrições de educação e disponibilidade do editor; "fallback" não garante um rastreamento real. |
| includeWebLinks | No | boolean | falso | Inclua hiperlinks de saída da página. Ignorado para conteúdo de passagem. |
| renderDynamicPages | No | boolean | falso | Habilite a renderização do JavaScript para captura de tela de conteúdo dinâmico. Só funciona quando liveCrawl é definido como "fallback". |
| includeImageLinks | No | boolean | falso | Inclua URLs de imagem da página. Ignorado para conteúdo de passagem. |
| linguagem | No | cadeia | "en" | O código de idioma (ISO 639-1 de 2 letras). Consulte idiomas com suporte para a lista completa. |
| região | No | cadeia | "US" | O código da região (código de país/região de 2 letras). Consulte regiões com suporte para obter a lista completa. |
| formato de conteúdo | No | cadeia | "passagem" ("html" com acesso completo ao documento) | "passagem" retorna as partes da página mais relevantes para query (recomendado para aterramento). "text", "html" e "markdown" retornam o documento completo e se aplicam somente a aplicativos com acesso completo a documentos; sem ele, eles retornam HTTP 403 (AuthContentFormatForbidden). Consulte Trechos e formatos de conteúdo. |
Para solicitações de passagem, defina contentFormat como "passagem" e envie um nãoblank query. Se você deixar de fora contentFormat, "passagem" será o padrão, a menos que seu aplicativo tenha acesso completo ao documento, em que o padrão é "html". Uma solicitação de passagem sem um query HTTP 400 retorna (HandlerInvalidInput).
Solicitações de passagem
Uma solicitação de passagem está sujeita à validação normal da solicitação, além do seguinte:
-
querydeve conter texto diferente do espaço em branco e ter no máximo 1.000 caracteres. Caso contrário, a solicitação retornará HTTP 400 (HandlerInvalidInput). -
liveCrawldeve ser "none" ou "fallback".
No MCP, essas falhas retornam HTTP 200 com um erro de ferramenta (result.isError: true) que carrega a ID da solicitação original. A passagem é retornada no campo existente content ; a resposta tem a mesma forma que para outros formatos de conteúdo.
Conteúdo da passagem
Uma passagem é uma extração focada em consulta da página solicitada. Em vez de retornar a página desde o início, o serviço seleciona as partes da página mais relevantes e query as retorna no content campo.
-
Seleção: a página é dividida em segmentos, que são classificados por relevância como
query. Os segmentos mais bem classificados são selecionados até que omaxLengthorçamento seja atingido. -
Ordenação: os segmentos selecionados são retornados em sua ordem de página original, não na ordem de classificação. Segmentos não adjacentes são separados por
.... -
Limites de segmento: os segmentos são definidos por comprimento e não por frase ou parágrafo, de modo que um trecho pode começar ou terminar a frase intermediária. Exiba passagens como trechos e use a origem
urlpara atribuição. -
Formato: o conteúdo da passagem é texto sem formatação. As referências de marcação, hiperlinks e imagem não estão incluídas em
content. -
Comprimento:
contentnunca excede caracteresmaxLength. O padrãomaxLengthé 3000 sem acesso completo a documentos e 10000 com acesso completo a documentos. Páginas curtas podem ser retornadas na íntegra. -
Fallback: se a seleção de relevância estiver temporariamente indisponível para uma solicitação, o serviço retornará o início da página como texto sem formatação, truncado para
maxLength. - Restrições de conteúdo: políticas de editor e site, como diretivas de robôs e regras de paywall, são aplicadas antes da seleção. As passagens são selecionadas somente no conteúdo que pode ser retornado para a página.
-
Outro comportamento: A resolução de URL, o rastreamento ao vivo com "fallback", respostas pendentes de rastreamento (HTTP 202), campos de resposta, como
title,crawledAteisAdult, e respostas de erro, são iguais aos de outros formatos de conteúdo.
Cabeçalhos da solicitação
| Field | Tipo | Description |
|---|---|---|
| hospedar | cadeia | Host para APIs de IA Microsoft: api.microsoft.ai. |
| x-apikey ou Autorização | cadeia | Sua chave de API ou Entra ID token de acesso para autenticação. |
| tipo de conteúdo | cadeia | Tipo MIME do corpo da solicitação. Use application/json. |
Resposta
| Field | Tipo | Description |
|---|---|---|
| url | cadeia | A URL da página da Web ou a URL a ser repetida quando um rastreamento estiver pendente. |
| title | cadeia | O título da página da Web. |
| conteúdo | cadeia | O conteúdo extraído da página da Web (também conhecido como aterramento). Para uma solicitação de passagem, as passagens selecionadas para query. |
| lastUpdatedAt | cadeia | A última data atualizada da página da Web segue ISO8601 formato. |
| crawledAt | cadeia | A última data rastreada da página da Web segue ISO8601 formato. |
| traceId | cadeia | ID de rastreamento para depuração. |
| retryAfter | cadeia | O primeiro tempo para tentar novamente, como um carimbo de data/hora UTC ISO 8601 (por exemplo, "2026-10-30T01:01:00Z"). Presente quando um rastreamento sob demanda está em andamento (202) e em alguns erros. |
| isAdult | boolean | Indica se a página da Web contém conteúdo adulto. |
Note
Os titlecampos, , contentisAdulte lastUpdatedAtcrawledAt , só estão presentes em respostas bem-sucedidas (200). Eles são omitidos de respostas de repetição (202).
Exemplo: solicitação e resposta de passagem
A solicitação no exemplo acima retorna uma resposta semelhante à seguinte. O serviço selecionou segmentos não adjacentes da página e ingressou neles com ....
{
"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 Status | Categoria do Erro | Description | Causas comuns |
|---|---|---|---|
| 200 | Êxito | O pedido foi bem-sucedido. | - |
| 202 | Aceitado | Solicitação aceita para processamento (rastreamento dinâmico). | Rastreamento sob demanda em andamento |
| 400 | Solicitação incorreta | Parâmetros de solicitação inválidos. | Campos necessários ausentes, valores de parâmetro inválidos, JSON malformado, ausente ou em branco query para uma solicitação de passagem |
| 401 | Unauthorized | Falha ou falha na autenticação. | Chave de API inválida, cabeçalho x-apikey ausente |
| 403 | Proibido | Credenciais válidas, mas a solicitação não pode ser atendida. | A chave de API não tem permissões necessárias, URL bloqueada por política, conteúdo filtrado texthtmlou markdown solicitado sem acesso completo ao documento |
| 404 | Não encontrado | Documento não encontrado. | URL inválida ou inacessível |
| 410 | Sumiu (Gone) | HTTPS necessário. | Solicitação feita por HTTP em vez de HTTPS |
| 415 | Tipo de mídia sem suporte | Não há suporte para o tipo de conteúdo. | Cabeçalho de tipo de conteúdo ausente ou incorreto |
| 429 | Número Excessivo de Solicitações | Limite de taxa ou limite de rastreamento sob demanda excedido. | Muitas solicitações na janela de tempo ou solicitações de rastreamento ao vivo excessivas |
| 430 | Muitos rastreamentos sob demanda | Muitos rastreamentos sob demanda (códigos de erro herdados). | Solicitações de rastreamento ao vivo excessivas |
| 500 | Erro interno do servidor | Erro de servidor inesperado. | Problema temporário do servidor |
| 503 | Serviço indisponível | Serviço temporariamente indisponível. | Manutenção ou interrupção temporária |
| 504 | Tempo de Espera do Gateway (Gateway Timeout) | A solicitação expirou. | Tempo limite do serviço upstream |
| 520 | Falha no processamento de conteúdo | A página foi recuperada, mas nenhum conteúdo utilizável pôde ser produzido. | O processamento de documentos falhou ou atingiu o tempo limite ou a renderização dinâmica atingiu o tempo limite |
| 523 | Rastreamento Cancelado | O rastreamento não produziu conteúdo devido à cota de rastreamento de site limitada. | Cota de rastreamento limitada para o host de origem |
| 524 | Tempo limite de rastreamento | O rastreamento não produziu conteúdo porque atingiu o tempo limite. | O host remoto atingiu o tempo limite |
Erros de solicitação de passagem
Esses erros se aplicam a solicitações de passagem. Eles também se aplicam quando "passagem" é o formato padrão.
| Condition | Status HTTP | Código do erro |
|---|---|---|
query está ausente, em branco ou com mais de 1000 caracteres |
400 | HandlerInvalidInput |
Um aplicativo sem solicitações completas textde acesso a documentos, htmlou markdown |
403 | AuthContentFormatForbidden |
Códigos de erro granulares
Códigos de erro granulares são habilitados por padrão para Procurar. Eles identificam o motivo específico pelo qual uma página não pôde ser retornada, como filtragem de conteúdo, um documento ausente ou uma falha de rastreamento, e incluem diretrizes de repetição quando aplicável. Nenhuma solicitação de aceitação ou suporte é necessária.
Para obter a lista completa de códigos e ações recomendadas, consulte Procurar erros específicos da API.
Para obter diretrizes detalhadas de tratamento de erros, consulte Tratamento de Erros.
Consulte também:Pesquisa deVídeosde Pesquisa na Web | Pesquisa | | deImagens de | Pesquisade Imagens MCP