Skip to main content
POST
/
v1
/
research
/research
curl --request POST \
  --url https://api.linkup.so/v1/research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "q": "What is Microsoft's 2024 revenue?",
  "outputType": "sourcedAnswer",
  "structuredOutputSchema": null,
  "includeSources": false,
  "includeImages": false,
  "fromDate": "2025-01-01",
  "toDate": "2025-01-01",
  "includeDomains": [
    "microsoft.com",
    "agolution.com"
  ],
  "excludeDomains": [
    "wikipedia.org"
  ],
  "includeInlineCitations": false,
  "maxResults": null
}
EOF
{
  "id": "01234-abcd-56789"
}

Get your API key

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 to poll for the result, or GET /v1/research to list all your research tasks.
If outputType is set to structured, you may provide a JSON structuredOutputSchema to dictate the response format.
JSON formats are tricky. Learn more about structured output in our guide.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
q
string
required

The natural language question for which you want to retrieve context.

Example:

"What is Microsoft's 2024 revenue?"

​
outputType
enum<string>
required

The type of output you want to get. Use structured for a custom-formatted response defined by structuredOutputSchema.

Available options:
sourcedAnswer,
structured
​
structuredOutputSchema
string<json>

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.

​
includeSources
boolean
default:false

Relevant only when outputType is structured. Defines whether the response should include sources. Please note that it modifies the schema of the response, see below

​
includeImages
boolean
default:false

Defines whether the API should include images in its results.

​
fromDate
string

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"

​
toDate
string

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"

​
includeDomains
string[]

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"]
​
excludeDomains
string[]

The domains you want to exclude of the search. By default, don't restrict the search.

Example:
["wikipedia.org"]
​
includeInlineCitations
boolean
default:false

Relevant only when outputType is sourcedAnswer. Defines whether the answer should include inline citations.

​
maxResults
number

The maximum number of results to return. The number of results will always be ≤ to maxResults.

Response

Research task created successfully.

​
id
string
required

The unique identifier of the created research task.

Example:

"01234-abcd-56789"