> ## 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
> The `POST /research` method creates an asynchronous research task which can perform a comprehensive web research.
Create a Linkup account for free to get your API key.
This is an **asynchronous** endpoint. It immediately returns the research task identifier,
before it is completed. Use
[`GET /v1/research/:id`](/pages/documentation/endpoints/research/get) to poll for
the result, or [`GET /v1/research`](/pages/documentation/endpoints/research/list)
to list all your research tasks.
For an explanation of `mode`, `reasoningDepth`, and the async lifecycle,
see the [Research overview](/pages/documentation/endpoints/research/overview).
## OpenAPI
````yaml https://api.linkup.so/v1/openapi.json POST /v1/research
openapi: 3.1.0
info:
title: Linkup API
description: >-
Search the web in real time to get trustworthy, source-backed answers. Find
the latest news and comprehensive results from the most relevant sources.
Use natural language queries to quickly gather facts, citations, and
context.
version: '1.0'
contact: {}
servers:
- url: https://api.linkup.so
security: []
tags: []
paths:
/v1/research:
post:
tags:
- Research
summary: /research
description: >-
The `POST /research` method creates an asynchronous research task which
can perform a comprehensive web research.
operationId: createResearch
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostResearchInput'
responses:
'200':
description: Research task created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PostResearchOutput_Output'
'400':
description: Bad Request - Invalid parameters
'401':
description: Unauthorized - Invalid or missing API key
'402':
description: >-
Payment Required - No API key provided. Returns x402 payment details
in the `payment-required` header for pay-per-request with USDC.
'429':
description: Too Many Requests - Rate limit exceeded or insufficient credits
security:
- bearer: []
components:
schemas:
PostResearchInput:
type: object
properties:
excludeDomains:
description: >-
The domains you want to exclude of the search. By default, don't
restrict the search.
example:
- wikipedia.org
type: array
items:
example: wikipedia.org
type: string
fromDate:
description: >-
The date from which the search results should be considered, in ISO
8601 format (YYYY-MM-DD). It must be before `toDate`, if provided,
and later than 1970-01-01.
example: '2025-01-01'
anyOf:
- type: string
- type: 'null'
includeDomains:
description: >-
The domains you want to search on. By default, don't restrict the
search. You can provide up to 100 domains.
example:
- microsoft.com
- agolution.com
maxItems: 100
type: array
items:
example: microsoft.com
type: string
q:
description: >-
The natural language question for which you want to retrieve
context.
example: What is Microsoft's 2024 revenue?
type: string
structuredOutputSchema:
default: null
format: json
description: >-
Required only when `outputType` is `structured`. Provide a JSON
schema (as a string) representing the desired response format. The
root must be of type `object`.
toDate:
description: >-
The date until which the search results should be considered, in ISO
8601 format (YYYY-MM-DD). It must be later than `fromDate`, if
provided, or than 1970-01-01.
example: '2025-01-01'
anyOf:
- type: string
- type: 'null'
mode:
default: auto
description: >-
Pin the research agent mode. Omit to let the agent auto-classify per
request based on the question.
enum:
- answer
- auto
- investigate
- research
type: string
outputType:
type: string
enum:
- sourcedAnswer
- structured
description: >-
The type of output you want to get. Use `structured` for a
custom-formatted response defined by `structuredOutputSchema`.
reasoningDepth:
default: L
description: >-
Pin the reasoning depth (S < M < L < XL). Defaults to L when
omitted. Higher depths trade latency for thoroughness.
enum:
- L
- M
- S
- XL
type: string
required:
- q
- outputType
id: PostResearchInput
example:
outputType: sourcedAnswer
q: >-
Research the current state of the semiconductor market, covering key
market dynamics, major industry players and their strategic
positioning, recent analyst sentiment, and the main bull and bear
cases for the sector. Ground the report in sourced, factual
information.
PostResearchOutput_Output:
$ref: '#/components/schemas/ResearchTaskOutput_Output'
id: PostResearchOutput_Output
ResearchTaskOutput_Output:
type: object
properties:
createdAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
description: The date and time when the task was created.
example: '2026-01-01T00:00:00.000Z'
error:
anyOf:
- type: string
- type: 'null'
description: The error message if the task failed.
id:
type: string
description: The unique identifier of the task.
example: 01234-abcd-56789
status:
type: string
enum:
- completed
- failed
- pending
- processing
description: The current status of the task.
example: completed
updatedAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
description: The date and time when the task status was last updated.
example: '2026-01-01T00:00:00.000Z'
input:
$ref: '#/components/schemas/ResearchTaskInput_Output'
output:
anyOf:
- anyOf:
- $ref: '#/components/schemas/ResearchSourcedAnswerOutput_Output'
- $ref: '#/components/schemas/StructuredOutput_Output'
- type: 'null'
type:
type: string
const: research
required:
- createdAt
- error
- id
- status
- updatedAt
- input
- output
- type
additionalProperties: false
id: ResearchTaskOutput_Output
ResearchTaskInput_Output:
type: object
properties:
excludeDomains:
description: >-
The domains you want to exclude of the search. By default, don't
restrict the search.
example:
- wikipedia.org
type: array
items:
example: wikipedia.org
type: string
fromDate:
description: >-
The date from which the search results should be considered, in ISO
8601 format (YYYY-MM-DD). It must be before `toDate`, if provided,
and later than 1970-01-01.
example: '2025-01-01'
type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
includeDomains:
description: >-
The domains you want to search on. By default, don't restrict the
search. You can provide up to 100 domains.
example:
- microsoft.com
- agolution.com
maxItems: 100
type: array
items:
example: microsoft.com
type: string
q:
description: >-
The natural language question for which you want to retrieve
context.
example: What is Microsoft's 2024 revenue?
type: string
structuredOutputSchema:
default: null
format: json
description: >-
Required only when `outputType` is `structured`. Provide a JSON
schema object representing the desired response format. The root
must be of type `object`.
type: object
propertyNames:
type: string
additionalProperties: {}
toDate:
description: >-
The date until which the search results should be considered, in ISO
8601 format (YYYY-MM-DD). It must be later than `fromDate`, if
provided, or than 1970-01-01.
example: '2025-01-01'
type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
mode:
default: auto
description: >-
Pin the research agent mode. Omit to let the agent auto-classify per
request based on the question.
enum:
- answer
- auto
- investigate
- research
type: string
outputType:
type: string
enum:
- sourcedAnswer
- structured
description: >-
The type of output you want to get. Use `structured` for a
custom-formatted response defined by `structuredOutputSchema`.
reasoningDepth:
default: L
description: >-
Pin the reasoning depth (S < M < L < XL). Defaults to L when
omitted. Higher depths trade latency for thoroughness.
enum:
- L
- M
- S
- XL
type: string
required:
- q
- toDate
- mode
- outputType
- reasoningDepth
additionalProperties: false
id: ResearchTaskInput_Output
ResearchSourcedAnswerOutput_Output:
$ref: '#/components/schemas/SourcedAnswerOutput_Output'
example:
answer: >-
**Date:** May 19, 2026
### 1. Executive Summary
The global semiconductor market has entered a period of unprecedented
expansion in 2026, driven by an artificial intelligence "super-cycle"
that is fundamentally restructuring industry supply and demand....
sources:
- favicon: ''
name: >-
Global Semiconductor Sales Increase 25% from Q4 2025 to Q1 2026 -
Semiconductor Industry Association
snippet: >-
Global semiconductor sales reached $298.5 billion during the first
quarter of 2026, representing a 25% increase compared to the
fourth quarter of 2025.
url: >-
https://www.semiconductors.org/global-semiconductor-sales-increase-25-from-q4-2025-to-q1-2026/
- favicon: ''
name: >-
Global Semiconductor Sales Increase 25% from Q4 2025 to Q1 2026 |
SemiWiki
snippet: >-
Global semiconductor sales in March 2026 were $99.5 billion, an
increase of 79.2% compared to March 2025 and 11.5% more than
February 2026.
url: >-
https://semiwiki.com/forum/threads/global-semiconductor-sales-increase-25-from-q4-2025-to-q1-2026.25061/
id: ResearchSourcedAnswerOutput_Output
StructuredOutput_Output:
type: object
propertyNames:
type: string
additionalProperties: {}
id: StructuredOutput_Output
SourcedAnswerOutput_Output:
type: object
properties:
answer:
type: string
description: The answer to your question.
example: >-
Microsoft's revenue for fiscal year 2024 was $245.1 billion,
reflecting a 16% increase from the previous year.
sources:
type: array
items:
$ref: '#/components/schemas/Source_Output'
description: List of sources used to answer the question.
example:
- name: Microsoft 2024 Annual Report
snippet: >-
Highlights from fiscal year 2024 compared with fiscal year 2023
included: Microsoft Cloud revenue increased 23% to $137.4
billion.
url: https://www.microsoft.com/investor/reports/ar24/index.html
required:
- answer
- sources
additionalProperties: false
id: SourcedAnswerOutput_Output
Source_Output:
type: object
properties:
name:
type: string
description: The title or name of the resource.
example: Microsoft 2024 Annual Report
url:
description: The URL of the resource.
example: https://www.microsoft.com/investor/reports/ar24/index.html
format: uri
type: string
favicon:
anyOf:
- type: string
const: ''
- type: string
format: uri
description: The favicon URL, if available.
example: https://www.microsoft.com/favicon.ico
format: uri
snippet:
type: string
description: Extracted text content associated with the source.
example: >-
Highlights from fiscal year 2024 compared with fiscal year 2023
included...
required:
- name
- url
- favicon
- snippet
additionalProperties: false
id: Source_Output
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````