> ## 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 `GET /research` method, without research task identifier, lists all created research tasks for the authenticated organization, with pagination.
Create a Linkup account for free to get your API key.
This endpoint only retrieves data from existing research tasks. It does not create a new
research task. To create a new task, use
[`POST /research`](/pages/documentation/endpoints/research/post).
## OpenAPI
````yaml https://api.linkup.so/v1/openapi.json GET /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:
get:
tags:
- Research
summary: /research
description: >-
The `GET /research` method, without research task identifier, lists all
created research tasks for the authenticated organization, with
pagination.
operationId: listResearch
parameters:
- name: page
required: false
in: query
schema:
default: 1
minimum: 1
type: integer
- name: pageSize
required: false
in: query
schema:
default: 10
maximum: 100
minimum: 1
type: integer
- name: sortBy
required: false
in: query
schema:
enum:
- createdAt
- updatedAt
type: string
- name: sortDirection
required: false
in: query
schema:
default: asc
enum:
- asc
- desc
type: string
responses:
'200':
description: Paginated list of research tasks.
content:
application/json:
schema:
$ref: '#/components/schemas/ListResearchOutput'
'401':
description: Unauthorized - Invalid or missing API key
security:
- bearer: []
components:
schemas:
ListResearchOutput:
type: object
properties:
metadata:
type: object
properties:
page:
type: number
pageSize:
type: number
total:
type: number
totalPages:
type: number
required:
- page
- pageSize
- total
- totalPages
data:
type: array
items:
$ref: '#/components/schemas/ResearchTaskOutput'
required:
- metadata
- data
id: ListResearchOutput
ResearchTaskOutput:
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:
anyOf:
- anyOf:
- $ref: '#/components/schemas/ResearchSourcedAnswerOutput'
- $ref: '#/components/schemas/StructuredOutput'
- type: 'null'
type:
type: string
const: research
required:
- createdAt
- error
- id
- status
- updatedAt
- input
- output
- type
id: ResearchTaskOutput
ResearchTaskInput:
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: ResearchTaskInput
ResearchSourcedAnswerOutput:
$ref: '#/components/schemas/SourcedAnswerOutput'
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
StructuredOutput:
type: object
propertyNames:
type: string
additionalProperties: {}
id: StructuredOutput
SourcedAnswerOutput:
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'
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
id: SourcedAnswerOutput
Source:
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
id: Source
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````