Auto REST API reference (Beta)

Note

Auto is available in beta for external partners whose application profile is enabled for Auto. The API surface and contract might change.

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

All requests require an API key or Microsoft Entra ID access token. See Authentication for setup instructions.

Sample request

curl -X POST "https://api.microsoft.ai/v3/auto" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Microsoft AI announcements",
    "language": "en",
    "region": "US",
    "location": "lat:47.6062;long:-122.3321",
    "mode": "fast",
    "maxResponseLength": 30000,
    "responseFilter": ["web", "news"]
  }'

Parameters

Parameter Required Type Default Description
query Yes string - Search query, from 1 to 1,000 characters. Supports site: and -site: operators.
language No string en Two-letter ISO 639-1 interface language.
region No string US Two-letter market or country/region code.
mode No string fast fast prioritizes speed; advanced prioritizes comprehensiveness.
maxResponseLength No integer 30000 Maximum total response length. Values below 1500 are clamped to 1500; values above 500000 are clamped to 500000.
location No string - Geographic context in lat:<latitude>;long:<longitude> format, for example lat:47.6062;long:-122.3321.
responseFilter No array of strings - Eligible answer types: web, news, timezone, weather, images, videos.

Response

A successful evidence response returns 200 OK. Each result contains one typed evidence object and the citations that support it. Unsupported or malformed evidence is omitted together with its citations. If every supplied evidence result is omitted, results is empty.

AutoEvidenceResponse

Field Type Description
results array of AutoEvidenceResult Evidence items paired with citations scoped to that result.
traceId string Correlation ID for debugging and support.

AutoEvidenceResult

Field Type Description
evidence AutoEvidence Generated typed evidence.
citations array of AutoEvidenceCitation Citations supporting only this evidence result.

AutoEvidence

The evidence object's own type discriminator selects the schema of content.

type content
text String evidence returned for Web and News results.
media/image Image result object.
media/video Video result object.
structured/weather Weather object.
structured/timeZone Time-zone object.

News text evidence can also include a thumbnail with url, width, and height. Structured content follows the same public field visibility rules as its corresponding search answer.

AutoEvidenceCitation

Field Type Description
contentSource string Citation source.
title string Citation title.
url string Citation URL.
lastUpdatedAt string Last-updated timestamp.
crawledAt string Crawl timestamp.
language string Content language.
isAdult boolean Whether the citation contains adult content.

Example response

{
  "results": [
    {
      "evidence": {
        "type": "text",
        "content": "Microsoft announced a new set of AI capabilities."
      },
      "citations": [
        {
          "contentSource": "web",
          "url": "https://www.microsoft.com/en-us/ai",
          "title": "Microsoft AI",
          "language": "en",
          "isAdult": false
        }
      ]
    }
  ],
  "traceId": "00000000000000000000000000000000"
}

Error codes

Status code Description
200 The request succeeded, including a valid search with no results.
400 Invalid parameters or malformed JSON.
401 Missing or invalid authentication credentials.
403 The authenticated profile is not enabled for Auto.
429 Rate or quota limit exceeded.
500 Internal service failure.
503 A required service is unavailable.
504 The request timed out.

For the shared error schema and retry guidance, see Error handling.

Related content

  • Last updated on