REST API başvurusuna göz atın

Bitiş noktası:POST https://api.microsoft.ai/v3/browse

Örnek İstek:

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

Pasajlar topraklama için önerilen biçimdir. Tam belge erişimine sahip uygulamalar bunun yerine , htmlveya markdownolarak ayarlayarak contentFormattextsayfanın tamamını isteyebilir. Bkz. Parçalar ve içerik biçimleri.

Parameters

Parametre Required Tür Default Description
url Yes string - Gözatmak için web sayfasının URL'si.
query İçin gerekli passage string - Sayfadan 1000 karaktere kadar olan bölümleri seçmek için kullanılan sorgu. İstek passage için boş olmayan bir sorgu gerekir. Diğer biçimler query için isteğe bağlıdır. 1000 karakterden uzun bir değer HTTP 400 döndürür. Bu sınır, 'inden maxLengthbağımsızdır.
maksimumUzunluk No integer 3000 (tam belge erişimine sahip 10000) içindeki contenten fazla karakter sayısı 1 ile 500000 arasıdır. Bu aralığın dışındaki bir değer HTTP 400 döndürür. Tam belge erişimi olmadan en content fazla 3000 karakter ve daha büyük değerler 3000 ile eşlenir.
liveCrawl No string "hiçbiri" Canlı gezinme davranışını denetler. Desteklenen değerler: "none" (canlı gezinme olmadan yalnızca dizine alınan içeriği döndür) ve "geri dönüş" (URL dizinde bulunamazsa canlı gezinme isteyin). "Hiçbiri" için, URL dizinde bulunmazsa, API 404 döndürür (URL bulunamadı).

Not: Canlı gezinme yayımcı kibarlığı kısıtlamalarına ve kullanılabilirliğine tabidir; "geri dönüş", gerçek bir gezinmeyi garanti etmez.
includeWebLinks No boolean yanlış Sayfadan giden köprüler ekleyin. Geçiş içeriği için yoksayıldı.
renderDynamicPages No boolean yanlış Dinamik içerik ekran görüntüsü için JavaScript işlemeyi etkinleştirme. Yalnızca liveCrawl "geri dönüş" olarak ayarlandığında çalışır.
includeImageLinks No boolean yanlış Sayfadan görüntü URL'lerini ekleyin. Geçiş içeriği için yoksayıldı.
language No string "en" Dil kodu (2 harfli ISO 639-1). Tam liste için bkz . Desteklenen Diller .
region No string "US" Bölge kodu (2 harfli ülke/bölge kodu). Tam liste için bkz . Desteklenen Bölgeler .
contentFormat No string "passage" ("html" ve tam belge erişimi) "passage", sayfanın en ilgili query bölümlerini döndürür (topraklama için önerilir). "text", "html" ve "markdown" tam belgeyi döndürür ve yalnızca tam belge erişimi olan uygulamalara uygulanır; olmadan HTTP 403 (AuthContentFormatForbidden) döndürür. Bkz. Parçalar ve içerik biçimleri.

Geçiş istekleri için "passage" olarak ayarlayın contentFormat ve boş queryolmayan bir gönderin. dışında bırakırsanız contentFormat, uygulamanız tam belge erişimine sahip olmadığı sürece varsayılan değer "passage" olur ve varsayılan değer "html" olur. Http 400 (HandlerInvalidInput) içermeyen bir query geçiş isteği.

Geçiş istekleri

Geçiş isteği normal istek doğrulamasına ve aşağıdakilere tabidir:

  • query boşluk dışında bir metin içermeli ve en fazla 1000 karakter uzunluğunda olmalıdır. Aksi takdirde istek HTTP 400 ()HandlerInvalidInput döndürür.
  • liveCrawl "none" veya "fallback" olmalıdır.

MCP üzerinden, bu hatalar özgün istek kimliğini taşıyan bir araç hatası (result.isError: true) ile HTTP 200 döndürür. Pasaj mevcut content alanda döndürülür; yanıt diğer içerik biçimleriyle aynı şekle sahiptir.

Geçiş içeriği

Bölüm, istenen sayfanın sorgu odaklı bir ayıklamasıdır. Hizmet, sayfayı baştan döndürmek yerine sayfanın en ilgili query bölümlerini seçer ve bunları alanda content döndürür.

  • Seçim: sayfa, ile ilgisine göre derecelendirilen bölümlere queryayrılır. Bütçeye ulaşılana kadar maxLength en yüksek dereceli segmentler seçilir.
  • Sıralama: Seçilen segmentler sıralama sırasına göre değil özgün sayfa sıralarında döndürülür. Bitişik olmayan kesimler ile ...ayrılır.
  • Segment sınırları: segmentler cümle veya paragraf yerine uzunlukla tanımlanır, bu nedenle alıntı cümlenin ortasından başlayabilir veya sonlandırabilir. Pasajları alıntı olarak görüntüleyin ve ilişkilendirme için kaynağı url kullanın.
  • Biçim: geçiş içeriği düz metindir. İşaretlemeyi, köprüleri ve görüntü başvurularını içinde yoktur content.
  • Uzunluk:content hiçbir zaman karakterleri aşmaz maxLength . Varsayılan değer maxLength , tam belge erişimi olmadan 3000 ve tam belge erişimine sahip 10000'dir. Kısa sayfalar tam olarak döndürülebilir.
  • Geri dönüş: bir istek için ilgi seçimi geçici olarak kullanılamıyorsa, hizmet sayfanın başlangıcını düz metin olarak döndürür ve olarak kesilir maxLength.
  • İçerik kısıtlamaları: Robot yönergeleri ve ödeme duvarı kuralları gibi yayımcı ve site ilkeleri seçimden önce uygulanır. Bölümler yalnızca sayfa için döndürülebilecek içerikten seçilir.
  • Diğer davranış: URL çözümlemesi, "geri dönüş" ile canlı gezinme, bekleyen gezinme (HTTP 202) yanıtları, , crawledAtve gibi titleyanıt alanları ve isAdulthata yanıtları diğer içerik biçimleriyle aynıdır.

İstek Üst Bilgileri

Field Tür Description
host string Microsoft AI API'leri için konak: api.microsoft.ai.
x-apikey veya Yetkilendirme string Kimlik doğrulaması için API anahtarınız veya Entra ID erişim belirteciniz.
içerik türü string İstek gövdesinin MIME türü. application/json adresini kullanın.

Response

Field Tür Description
url string Web sayfasının URL'si veya gezinme beklemede olduğunda yeniden denenecek URL.
title string Web sayfasının başlığı.
içerik string Web sayfasının ayıklanan içeriği (yani topraklama). Bir geçiş isteği için, için queryseçilen pasajlar.
lastUpdatedAt string Web sayfasının son güncelleştirme tarihi, ISO8601 biçimi izler.
crawledAt string Web sayfasının son gezinme tarihi, ISO8601 biçimi izler.
traceId string Hata ayıklama için izleme kimliği.
retryAfter string Iso 8601 UTC zaman damgası (örneğin, "2026-10-30T01:01:00Z") olarak yeniden denenecek en erken zaman. İsteğe bağlı gezinme devam ederken (202) ve bazı hatalarda bulunur.
isAdult boolean Web sayfasının yetişkinlere yönelik içerik içerip içermediğini gösterir.

Note

title, content, isAdult, , lastUpdatedAtve crawledAt alanları yalnızca başarılı (200) yanıtlarda bulunur. Bunlar yeniden deneme (202) yanıtlarından atlanır.

Örnek: geçiş isteği ve yanıt

Yukarıdaki örnekteki istek aşağıdakine benzer bir yanıt döndürür. Hizmet sayfanın bitişik olmayan kesimlerini seçti ve bunları ile birleştirdi ....

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

Hata Kodları

Durum Kodu Hata Kategorisi Description Olası Nedenler
200 Success İstek başarılı oldu. -
202 Kabul edildi İstek işlenmek üzere kabul edildi (canlı gezinme). İsteğe bağlı gezinme sürüyor
400 Hatalı İstek Geçersiz istek parametreleri. Eksik gerekli alanlar, geçersiz parametre değerleri, hatalı biçimlendirilmiş JSON, geçiş isteği için eksik veya boş query
401 Yetkisiz Kimlik doğrulaması başarısız oldu veya eksik. Geçersiz API anahtarı, eksik x-apikey üst bilgisi
403 Yasak Geçerli kimlik bilgileri ancak istek karşılanamıyor. API anahtarında gerekli izinler yok, ilke tarafından engellenen URL, filtrelenmiş içerik, text, htmlveya markdown tam belge erişimi olmadan istendi
404 Bulunamadı Belge bulunamadı. Geçersiz veya erişilemez URL
410 Gitti HTTPS gereklidir. İSTEK HTTPS yerine HTTP üzerinden yapıldı
415 Desteklenmeyen Medya Türü İçerik türü desteklenmiyor. Eksik veya yanlış içerik türü üst bilgisi
429 Çok Fazla İstek Var Hız sınırı veya isteğe bağlı gezinme sınırı aşıldı. Zaman penceresinde çok fazla istek veya aşırı canlı gezinme isteği
430 Çok Fazla İsteğe Bağlı Gezinme çok fazla isteğe bağlı gezinme (eski hata kodları). Aşırı canlı gezinme istekleri
500 İç Sunucu Hatası Beklenmeyen sunucu hatası. Geçici sunucu sorunu
503 Hizmet Kullanılamıyor Hizmet geçici olarak kullanılamıyor. Bakım veya geçici kesinti
504 Ağ Geçidi Zaman Aşımı İstek zaman aşımına uğradı. Yukarı akış hizmeti zaman aşımı
520 İçerik İşleme Başarısız Oldu Sayfa alındı, ancak kullanılabilir içerik üretilemedi. Belge işleme başarısız oldu veya zaman aşımına uğradı veya dinamik işleme zaman aşımına uğradı
523 Gezinme İptal Edildi Gezinme, sınırlı site gezinme kotası nedeniyle içerik üretmedi. Kaynak konak için sınırlı gezinme kotası
524 Gezinme Zaman Aşımı Gezinme zaman aşımına uğradığından içerik üretmedi. Uzak konak zaman aşımına uğradı

Geçiş isteği hataları

Bu hatalar geçiş istekleri için geçerlidir. Ayrıca, "passage" varsayılan biçim olduğunda da uygulanır.

Condition HTTP Durumu Hata Kodu
query eksik, boş veya 1000 karakterden uzun 400 HandlerInvalidInput
Tam belge erişim isteği textolmayan bir uygulama , htmlveya markdown 403 AuthContentFormatForbidden

Ayrıntılı hata kodları

Ayrıntılı hata kodları Gözat için varsayılan olarak etkindir. İçerik filtreleme, eksik belge veya gezinme hatası gibi belirli bir sayfanın döndürülememesinin nedenini belirler ve uygun olduğunda yeniden deneme yönergelerini içerir. Kabul veya Destek isteği gerekmez.

Kodların ve önerilen eylemlerin tam listesi için bkz. API'ye özgü hatalara göz atma.

Ayrıntılı hata işleme kılavuzu için bkz. Hata İşleme.


Ayrıca bkz:Web Arama | Videoları Arama | Haber Arama | Görüntüleri Arama | MCP