API ReferenceAgent

Create an Agent Research Object

Start a new research job using a token-aware request/response shape for agents. Set stream=true to reuse the research SSE event stream.

Authentication

AuthorizationBearer

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

Query parameters

streambooleanOptionalDefaults to false
When true, responds with an SSE stream of research events.

Request

This endpoint expects an object.
querystringRequired
Primary research question.
fileslist of stringsOptional
IDs of previously uploaded files to include.
reasoning_modebooleanOptionalDefaults to false
When enabled, uses an advanced reasoning model for deeper analysis.
exclude_socialbooleanOptionalDefaults to false
When enabled, excludes social media sources.
excluded_domainslist of stringsOptional
List of domains to exclude from search results.

Response

Research created or event stream started.
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

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
500
Internal Server Error