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

# Research Endpoint

> _Released: May 2026 (beta)_

We're introducing the new [**Research**](/pages/documentation/endpoints/research/overview) endpoint (`/research`), an autonomous research agent that investigates the web to handle questions a single search query cannot resolve. The agent plans its retrieval, gathers evidence from multiple sources in parallel, iterates through investigation, and returns a sourced response with inline citations.

Three modes, four reasoning depths, two output types. Asynchronous lifecycle.

### How to use

1. Send a `POST /research` request with a natural-language question and the parameters that pin the investigation. The endpoint immediately returns a task identifier and `status` of `"pending"`.
2. Poll `GET /research/{id}` to retrieve a specific task, or `GET /research` to list all your research tasks.
3. While running, `status` is `"pending"` or `"processing"`. Once the task is `"completed"`, read the result in `output`. If `"failed"`, inspect `error`.

**Example Request**

```shell curl theme={"system"}
curl --request POST \
  --url https://api.linkup.so/v1/research \
  --header 'Authorization: Bearer {{LINKUP_API_KEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "q": "Compare the 2024 cloud revenue growth of Microsoft, Amazon, and Google.",
  "mode": "investigate",
  "reasoningDepth": "L",
  "outputType": "sourcedAnswer"
}'
```

### Modes

| Mode            | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| `"answer"`      | A precise, evidence-backed answer to a question with a definitive solution. Lowest latency of the three. |
| `"investigate"` | A focused report on a single defined subject, examining each angle and verifying claims.                 |
| `"research"`    | A structured report organized by theme, covering many topics or entities in parallel. Highest latency.   |

If `mode` is not provided, the agent automatically classifies the question and selects one of the three modes for the request.

### Reasoning depth

`reasoningDepth` controls thoroughness. Higher depths have more compute budget: they consult more sources, perform more iterations and cross-checking, produce longer outputs, and take longer to run.

| Depth  | Order-of-magnitude latency |
| ------ | -------------------------- |
| `"S"`  | 2–5 minutes                |
| `"M"`  | 3–7 minutes                |
| `"L"`  | 5–10 minutes               |
| `"XL"` | 10–20 minutes              |

Omitting the parameter defaults to `"L"`.

### Output types

| `outputType`      | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `"sourcedAnswer"` | Natural-language answer with inline citations.            |
| `"structured"`    | JSON matching a caller-provided `structuredOutputSchema`. |

### Billing

The **Research** endpoint is billed per call at a flat rate per `reasoningDepth`, regardless of `mode`. See [pricing](/pages/documentation/platform/pricing#research-endpoint).

Read the full reference: [`POST /research`](/pages/documentation/endpoints/research/post) · [`GET /research`](/pages/documentation/endpoints/research/list) · [`GET /research/:id`](/pages/documentation/endpoints/research/get). For operational guidance, see [research best practices](/pages/documentation/endpoints/research/best-practices).