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

# Start research task

`POST /web_search/research`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/web_search/research`
- Auth: HTTP bearer

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
  - `query` string, required: The research question or topic.
  - `research_effort` 'lite' | 'standard' | 'deep': Research depth level. `lite` is fastest, `deep` is most thorough.
  - `max_sources` integer: Maximum number of sources to use.
  - `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.

## 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.
        - `url` string, uri, required: Source URL.
        - `title` string, required: Title of the source page.
        - `snippet` string: Relevant excerpt from the source (if available).
    - ResearchResponseAsync: Asynchronous research response (when `background` is true).
      - `task_id` string, required: Unique identifier for the research task. Use this to poll the status.
      - `status` 'pending' | 'running' | 'completed' | 'failed', required: Current status of the research task.

## 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.

## Changes

- **2026-10-15** `a72569d69430`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/web_search/research/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)