Browse REST API reference

Endpoint: POST https://api.microsoft.ai/v3/browse

Sample Request:

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://news.microsoft.com/source/",
    "maxLength": 3000,
    "language": "en",
    "region": "US",
    "contentFormat": "html"
  }'

Parameters

Parameter Required Type Default Description
url Yes string - The URL of the web page to browse.
maxLength No integer 10000 The maximum number of characters in the content field in response. Maximum value is 500000 characters.
liveCrawl No string "none" Controls live crawling behavior. Values: "none" (only return indexed content), "fallback" (crawl if URL not found in index), "force" (request a fresh crawl even if indexed content exists). Note that for "none" value, if the URL is not found in index, API will return 404 error code (URL not found).
includeWebLinks No boolean false Include outbound hyperlinks from the page.
renderDynamicPages No boolean false Enable JavaScript rendering for dynamic content screenshot. Only works when liveCrawl is set to "fallback".
includeImageLinks No boolean false Include image URLs from the page.
language No string "en" The language code (2-letter ISO 639-1). See Supported Languages for the full list.
region No string "US" The region code (2-letter country/region code). See Supported Regions for the full list.
contentFormat No string "html" The format of the webpage content to return. Can be "text", "html", or "markdown".

Request Headers

Field Type Description
host string Host for Microsoft AI APIs: api.microsoft.ai.
x-apikey or Authorization string Your API key or Entra ID access token for authentication.
content-type string MIME type of the request body. Use application/json.

Response

Field Type Description
url string The URL of the web page.
title string The title of the web page.
content string The extracted content of the web page (aka grounding).
lastUpdatedAt string The last updated date of the webpage, follows ISO8601 format.
crawledAt string The last crawled date of the webpage, follows ISO8601 format.
liveCrawlSucceeded boolean (optional) Only present as false when a successful request with liveCrawl: "force" returns a stale page. Omitted for non-stale pages; never emitted as true. Omitted for "none", "fallback", an omitted/null mode, and retry (202) responses.
traceId string Trace ID for debugging.
retryAfter string Time to wait before retrying, formatted as a duration in seconds with the "s" suffix (e.g., "60s" means wait 60 seconds). Only present when on-demand crawl is in progress.
isAdult boolean Indicates if the webpage contains adult content.

Note

The title, content, isAdult, lastUpdatedAt, and crawledAt fields are only present in successful (200) responses. They are omitted from retry (202) responses.

For example, a successful request with "liveCrawl": "force" includes "liveCrawlSucceeded": false only when stale content is returned. A non-stale page omits this field rather than returning true. This field has the same meaning in the Browse MCP tool's structured response.

Error Codes

Status Code Error Category Description Common Causes
200 Success The request succeeded. -
202 Accepted Request accepted for processing (live crawl). On-demand crawling in progress
400 Bad Request Invalid request parameters. Missing required fields, invalid parameter values, malformed JSON
401 Unauthorized Authentication failed or missing. Invalid API key, missing x-apikey header
403 Forbidden Valid credentials but request cannot be fulfilled. API key lacks required permissions, URL blocked by policy, content filtered
404 Not Found Document not found. Invalid or inaccessible URL
410 Gone HTTPS required. Request made over HTTP instead of HTTPS
415 Unsupported Media Type Content type not supported. Missing or incorrect content-type header
429 Too Many Requests Rate limit exceeded. Too many requests in time window
430 Too Many On-Demand Crawls Too many on-demand crawls. Excessive live crawl requests
500 Internal Server Error Unexpected server error. Temporary server issue
503 Service Unavailable Service temporarily unavailable. Maintenance or temporary outage
504 Gateway Timeout Request timed out. Upstream service timeout

For detailed error handling guidance, see Error Handling.

See also: Web Search | Videos Search | News Search | Images Search | MCP

  • Last updated on