POST /web_search/research hands a question to a pipeline that searches, reads sources, and synthesizes a cited answer. Every parameter and schema is in the API Reference; this page covers behavior.
Synchronous or Background
Synchronous requests (the default) block until the answer is ready — tens of seconds in practice, up to 120 depending onresearch_effort. The response is just answer and citations.
Use "background": true when you don’t want to hold a connection open: the request returns a task_id immediately, and GET /web_search/research/{task_id} polls the result.
Task Lifecycle
Tasks movepending → running → completed or failed. Poll responses always include error — it stays null unless the task actually failed, so branch on status, not on the key’s presence. answer and citations join the payload on completion.
Task IDs are ephemeral: unknown, malformed, expired, and already-purged IDs all return the same 404 with { "error": { "message": "Task not found" } }. Treat a 404 as “start a new research request”, not as a retryable error.
Citation Markers
Answers cite inline with bracketed markers —SIP trunking uses the internet to transmit voice [[1, 2, 3]] — which are 1-based indexes into the citations array. Agents can use them to attribute each claim to its source; max_sources caps how many sources the pipeline draws from.