v1

latestOpenAPI 3.1.02026-07-26125062.1 KB

Research

/research

The POST /research method creates an asynchronous research task which can perform a comprehensive web research.

post/v1/research

Request body

excludeDomainsstring[]

The domains you want to exclude of the search. By default, don't restrict the search.

fromDatestring nullable

The date from which the search results should be considered, in ISO 8601 format (YYYY-MM-DD). It must be before toDate, if provided, and later than 1970-01-01.

includeDomainsstring[]

The domains you want to search on. By default, don't restrict the search. You can provide up to 100 domains.

qstring required

The natural language question for which you want to retrieve context.

{"stackTrail":"components:schemas:PostResearchInput:properties:structuredOutputSchema","oasType":"schema","type":"unknown","description":"Required only when `outputType` is `structured`. Provide a JSON schema (as a string) representing the desired response format. The root must be of type `object`."}

toDatestring nullable

The date until which the search results should be considered, in ISO 8601 format (YYYY-MM-DD). It must be later than fromDate, if provided, or than 1970-01-01.

mode'answer' | 'auto' | 'investigate' | 'research'

Pin the research agent mode. Omit to let the agent auto-classify per request based on the question.

outputType'sourcedAnswer' | 'structured' required

The type of output you want to get. Use structured for a custom-formatted response defined by structuredOutputSchema.

reasoningDepth'L' | 'M' | 'S' | 'XL'

Pin the reasoning depth (S < M < L < XL). Defaults to L when omitted. Higher depths trade latency for thoroughness.

Example request

{
  "outputType": "sourcedAnswer",
  "q": "Research the current state of the semiconductor market, covering key market dynamics, major industry players and their strategic positioning, recent analyst sentiment, and the main bull and bear cases for the sector. Ground the report in sourced, factual information."
}

Response

Research task created successfully.

createdAtstring date-time required

The date and time when the task was created.

errorstring nullable required

The error message if the task failed.

idstring required

The unique identifier of the task.

status'completed' | 'failed' | 'pending' | 'processing' required

The current status of the task.

updatedAtstring date-time required

The date and time when the task status was last updated.

type'research' required

Example response

{
  "createdAt": "2026-01-01T00:00:00.000Z",
  "id": "01234-abcd-56789",
  "status": "completed",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "input": {
    "excludeDomains": [
      "wikipedia.org"
    ],
    "fromDate": "2025-01-01",
    "includeDomains": [
      "microsoft.com",
      "agolution.com"
    ],
    "q": "What is Microsoft's 2024 revenue?",
    "toDate": "2025-01-01"
  },
  "output": {
    "answer": "Microsoft's revenue for fiscal year 2024 was $245.1 billion, reflecting a 16% increase from the previous year.",
    "sources": [
      {
        "name": "Microsoft 2024 Annual Report",
        "snippet": "Highlights from fiscal year 2024 compared with fiscal year 2023 included: Microsoft Cloud revenue increased 23% to $137.4 billion.",
        "url": "https://www.microsoft.com/investor/reports/ar24/index.html"
      }
    ]
  }
}