API ReferenceResearch

Create a Research Object

Start a new research job using a query and optional file IDs.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
querystringRequired
Primary research question or instruction.
brainstorm_session_idstringOptionalformat: "uuid"

ID of a brainstorm session created via POST /research/brainstorm. When provided, the session’s Q&A context enhances the research.

answerslist of objectsOptional

Answers to brainstorm questions. Each answer references a question ID and the selected option index (0-based).

fileslist of stringsOptional
IDs of previously uploaded files to include.
collection_idslist of stringsOptional
IDs of collections to include files from. All files in the specified collections will be available for the research.
reasoning_loopsintegerOptional1-10Defaults to 1
Maximum number of iterative reasoning cycles the research process can perform. Each loop evaluates the gathered information and may trigger additional searches to fill knowledge gaps. Higher values allow for more thorough research but increase processing time.
source_timeoutintegerOptional3-180Defaults to 60
Maximum time in seconds to wait when fetching content from each source URL.
reasoning_modebooleanOptionalDefaults to false
When enabled, uses an advanced reasoning model for deeper analysis and synthesis of gathered information.
allow_early_exitbooleanOptionalDefaults to false
When enabled, the research process may complete before exhausting all reasoning loops if sufficient information has been gathered.
exclude_socialbooleanOptionalDefaults to false

When enabled, excludes results from social media platforms (e.g., Reddit, Twitter, Facebook) from the research sources.

excluded_domainslist of stringsOptional

List of domains to exclude from search results (e.g., “example.com”). Subdomains are also excluded.

autobooleanOptionalDefaults to false

When enabled, activates auto mode which analyzes the query to determine the optimal configuration. This overrides reasoning_loops, source_timeout, reasoning_mode, allow_early_exit, and exclude_social.

system_promptstringOptional
Custom system prompt to guide the research synthesis. Overrides the default prompt used for generating the final response.
modelstringOptional

Preferred AI model to use for research synthesis. Valid values are “gpt-5.2”, “gemini-3-pro”, “gemini-3-flash”, or “claude-opus-4.5”. When not specified, the system automatically selects an appropriate model.

Response

Research job accepted.
idstringformat: "uuid"
Research job identifier.
statusenum
Current status of the research job: - `queued`: Job accepted, waiting to start - `searching`: Gathering sources from the web - `researching`: Processing and analyzing sources - `analyzing`: Deep analysis of gathered information - `summarizing`: Generating final synthesis - `completed`: Research finished successfully - `failed`: Research encountered an error

Errors