---
title: "Start research task"
method: POST
path: "/web_search/research"
tags: ["Research"]
---

# Start research task

`POST /web_search/research`

Starts a deep research task that runs multiple searches, reads sources, and synthesizes an answer with citations.

## Synchronous mode (default)

When `background` is `false` or omitted, the request blocks until the research completes and returns the answer with citations. This can take up to 120 seconds depending on `research_effort`.

## Asynchronous mode

When `background` is `true`, the request returns immediately with a `task_id` and `status: pending`. Poll `GET /web_search/research/{task_id}` to check when the research completes and retrieve the answer.

## Request body

- ResearchRequest
  - `background` boolean — When `true`, the research runs asynchronously. The response returns a `task_id` immediately instead of waiting for the result. Poll `GET /web_search/research/{task_id}` to check status.
  - `max_sources` integer — Maximum number of sources to use.
  - `query` string, required — The research question or topic.
  - `research_effort` 'lite' | 'standard' | 'deep' — Research depth level. `lite` is fastest, `deep` is most thorough.

## Response `200`

Research response. Shape depends on `background`:

- **Synchronous** (`background` false/unset): returns `answer` + `citations`.
- **Asynchronous** (`background` true): returns `task_id` + `status`.

- object
  - `data` union
    - ResearchResponseSync — Synchronous research response (when `background` is false or unset).
      - `answer` string, required — The synthesized research answer.
      - `citations` ResearchCitation[] — Sources cited in the answer.
        - `snippet` string — Relevant excerpt from the source (if available).
        - `title` string, required — Title of the source page.
        - `url` string, uri, required — Source URL.
    - ResearchResponseAsync — Asynchronous research response (when `background` is true).
      - `status` 'pending' | 'running' | 'completed' | 'failed', required — Current status of the research task.
      - `task_id` string, required — Unique identifier for the research task. Use this to poll the status.

## Other responses

- `400` — Invalid request — validation error or invalid parameters.
- `401` — Unauthorized — missing or invalid API key. The API Gateway returns this response before the request reaches the backend service. The error format follows the standard Telnyx JSON:API error envelope with `errors[]`, not the backend-level `WebSearchError` shape.
- `500` — Internal server error.
- `502` — The upstream search provider returned an error.
- `504` — The upstream search provider timed out.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/ec31f78cf002/schema)