News Search REST API reference

Endpoint: POST https://api.microsoft.ai/v3/search/news

Sample Request:

curl -X POST "https://api.microsoft.ai/v3/search/news" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest VC funding in tech",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

Parameter Required Type Default Description
query Yes string - A search query for the news results. Maximum length is 1000 characters.
maxResults No integer 10 Max number of results to return. Default is 10. Maximum value is 20.
language No string "en" A 2-letter ISO 639-1 language code for interface language in the search results. See Supported Languages for the full list.
region No string "US" A 2-letter country/region code for where the results should come from (e.g. "US", "JP", "GB", etc.). See Supported Regions for the full list.
location No string - Location information in format "lat:<float>;long:<float>", e.g. "lat:40.753250;long:-74.003807".
contentFormat No string "passage" ("text" with full document access) passage returns the parts of each result most relevant to the query (recommended for grounding). text, html and markdown return the full document and apply only to applications with full document access; see Passages and content formats. Set it on every request.
maxLength No integer 3000 (10000 with full document access) Maximum characters in content per result, 1 to 500000. Without full document access, content is at most 3000 characters. See Defaults and limits. Set it on every request.

Content formats

Set contentFormat = passage to get the parts of each result most relevant to the query, up to maxLength characters (3000 is a good starting point). It's the recommended format for grounding; see What is passage, and why use it? in the FAQ. Applications with full document access can also request the full document as text, html or markdown; for other applications, those formats return HTTP 403. See Passages and content formats.

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

News Response

Field Type Description
newsResults array of newsResult List of news article results.
instrumentationClickBase string Base URL for click ping requests. Append an instrumentationSuffix value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and instrumentationClickBase will not be included in the response. See the Instrumentation guide for setup instructions.
instrumentationCitationBase string Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag.
traceId string Trace ID for debugging.

newsResult

Field Type Description
title string The title of the news.
url string The source URL of the news article. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl.
domain string The destination host for the result. Returned only for China users with URL redirection enabled.
content string The detailed webpage content (aka grounding) of the news result.
thumbnail thumbnail object The thumbnail of the news article.
lastUpdatedAt string The last updated date of the news, in UTC ISO8601 format.
crawledAt string The last crawled date of the news, follows ISO8601 format.
language string The language of the news article, uses ISO 639-1 language code.
source string Publisher name, such as "USA TODAY | MSN", "CNN", etc.
isAdult boolean Indicates if the content is adult.
clickUrl string Redirect URL that proxies the click through Bing. Only present when click redirect is enabled.
instrumentationSuffix string Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the clickUrl redirect. Present when instrumentation ping is enabled.

Note

lastUpdatedAt field is optional – that is, you may see empty value for this field.

thumbnail

Field Type Description
url string The URL of the thumbnail.
width integer Width of the thumbnail, in pixels.
height integer Height of the thumbnail, in pixels.

Note

thumbnail is also an optional response object – it may not be available for certain news results.

Error Codes

Status Code Error Category Description Common Causes
200 Success The request succeeded. -
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 insufficient permissions. API key lacks required permissions
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
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 | Browse | Images Search | MCP

  • Last updated on