> ## 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 overview > Research agent that navigates the web to produce sourced answers, from precise factual claims to multi-section reports. **Research** is Linkup's autonomous research agent that investigates the web to handle questions a single search query cannot resolve. Use cases include: * verified answers to precise questions, * focused investigations of a defined subject, and * broad multi-angle reports. The agent gathers evidence from multiple sources in parallel, iterates through investigation, and returns a sourced response with inline citations. **Research** is built around three modes, four reasoning depths, and two output types. Research results on the SealQA-0 benchmark Research ranks #1 on the SealQA-0 benchmark for sourced QA. ## Modes The `mode` parameter pins the type of investigation performed. | Mode | Description | Typical use | | --------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"answer"` | Returns a precise, evidence-backed answer to a question with a definitive solution. | Hard questions with a single correct answer that require verification across multiple sources. *Example: "Which 12 S\&P 500 companies gained more than 50% with market capitalization above \$5B in Q3 2025?"* | | `"investigate"` | Returns a focused report on a single defined subject, examining each angle and verifying claims. | In-depth reads on a defined entity. *Example: "Risk profile and regulatory history of company X."* | | `"research"` | Returns a structured report organized by theme, covering many topics or entities in parallel. | Open-ended questions requiring breadth across multiple subjects. *Example: "State of the European generative AI market in 2026."* | Set `mode` explicitly to pin latency, cost, and output shape. Omitting it lets the agent classify the question and pick — convenient but less predictable. If the `mode` parameter is not provided, the agent automatically classifies the question and selects one of the three modes for the request. ## Reasoning depth The `reasoningDepth` parameter 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 | Description | Order-of-magnitude latency | Cost | | ------ | ------------------------------------------------------------------------------------------------ | -------------------------- | --------------- | | `"S"` | Light coverage. Suitable for short multi-step investigations. | 2–5 minutes | \$0.25 per call | | `"M"` | Balanced cost-to-quality ratio. Suitable for routine use. | 3–7 minutes | \$0.50 per call | | `"L"` | Thorough investigation. Suitable for high-quality answers under bounded latency. | 5–10 minutes | \$1.50 per call | | `"XL"` | Exhaustive coverage. Suitable for deliverables where completeness takes precedence over latency. | 10–20 minutes | \$2.50 per call | Omitting the parameter defaults to `"L"`. ## Output types | Value | Description | | ----------------- | -------------------------------------------------------------------------- | | `"sourcedAnswer"` | Natural-language answer with inline citations. | | `"structured"` | JSON object conforming to the schema provided in `structuredOutputSchema`. | For `"structured"`, see the [structured output tutorial](/pages/documentation/tutorials/structured-output-guide). ## Async lifecycle `POST /v1/research` returns immediately with a job identifier and `status` set to `"pending"`. Subsequent calls to `GET /v1/research/:id` return the current state until `status` is `"completed"` or `"failed"`. Typical completion times range from a couple of minutes for shallow configurations to twenty minutes for exhaustive ones. `GET /v1/research` is also available to list all research tasks for the account. ```text theme={"system"} POST /research GET /research/:id GET /research/:id │ │ │ ▼ ▼ ▼ { id, status: { id, status: "processing" } { id, status: "completed", "pending" } (poll) output: { ... } } ``` Poll at 5–10 seconds for long-running tasks. Polling above 1 request per second will be rate-limited. ## Example Create a Linkup account for free to get your API key. ```python python theme={"system"} from linkup import LinkupClient import time client = LinkupClient(api_key="") task = client.research.create( q="Compare the 2024 cloud revenue growth of Microsoft, Amazon, and Google.", output_type="sourcedAnswer", mode="investigate", reasoning_depth="L", ) while True: result = client.research.get(task.id) if result.status in ("completed", "failed"): break time.sleep(2) print(result.output) ``` ```js js theme={"system"} import { LinkupClient } from 'linkup-sdk'; const client = new LinkupClient({ apiKey: '' }); const task = await client.research.create({ q: "Compare the 2024 cloud revenue growth of Microsoft, Amazon, and Google.", outputType: 'sourcedAnswer', mode: 'investigate', reasoningDepth: 'L', }); let result; do { await new Promise(r => setTimeout(r, 2000)); result = await client.research.get(task.id); } while (result.status !== 'completed' && result.status !== 'failed'); console.log(result.output); ``` ```shell curl theme={"system"} # 1. Submit curl -X POST "https://api.linkup.so/v1/research" \ -H "Authorization: Bearer $LINKUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "q": "Compare the 2024 cloud revenue growth of Microsoft, Amazon, and Google.", "outputType": "sourcedAnswer", "mode": "investigate", "reasoningDepth": "L" }' # → { "id": "task_..." } # 2. Poll curl "https://api.linkup.so/v1/research/task_..." \ -H "Authorization: Bearer $LINKUP_API_KEY" ``` `POST /v1/research` returns the task envelope immediately, with `status` set to `"pending"` and `output` set to `null`. `GET /v1/research/{id}` returns the same envelope; once `status` is `"completed"`, `output` is populated: ```json theme={"system"} { "id": "01234-abcd-56789", "type": "research", "status": "completed", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:08:42.000Z", "error": null, "input": { "q": "Compare the 2024 cloud revenue growth of Microsoft, Amazon, and Google.", "outputType": "sourcedAnswer", "mode": "investigate", "reasoningDepth": "L" }, "output": { "answer": "Microsoft Cloud revenue rose 23% to $137.4B in FY2024; AWS revenue rose 13% to $107.6B; Google Cloud rose 31% to $39.3B ...", "sources": [ { "name": "Microsoft 2024 Annual Report", "url": "https://www.microsoft.com/investor/reports/ar24/index.html", "snippet": "Microsoft Cloud revenue increased 23% to $137.4 billion." } // ... additional sources ] } } ``` When `outputType` is `"structured"`, `output` is the JSON object described by `structuredOutputSchema` instead of `{ answer, sources }`. ## Next Mode and depth selection, question structure, schema design. Tool definition and integration prompt. Full parameter spec and response schema.