> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Research

> Research behavior the spec can't show: sync vs background, the task lifecycle, and citation markers.

`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 on `research_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 move `pending` → `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.