Procurar referência da API REST

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:

  • query deve 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).
  • liveCrawl deve 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 o maxLength orç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 url para 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:content nunca excede caracteres maxLength . O padrão maxLength é 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, crawledAte isAdult, 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