---
title: "/research"
method: POST
path: "/v1/research"
tags: ["Research"]
---

# /research

`POST /v1/research`

The `POST /research` method creates an asynchronous research task which can perform a comprehensive web research.

## Request body

- PostResearchInput
  - `excludeDomains` string[] — The domains you want to exclude of the search. By default, don't restrict the search.
  - `fromDate` string, nullable — 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.
  - `includeDomains` string[] — The domains you want to search on. By default, don't restrict the search. You can provide up to 100 domains.
  - `q` string, required — The natural language question for which you want to retrieve context.
  - `structuredOutputSchema` unknown
  - `toDate` string, nullable — 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.
  - `mode` 'answer' | 'auto' | 'investigate' | 'research' — Pin the research agent mode. Omit to let the agent auto-classify per request based on the question.
  - `outputType` 'sourcedAnswer' | 'structured', required — The type of output you want to get. Use `structured` for a custom-formatted response defined by `structuredOutputSchema`.
  - `reasoningDepth` 'L' | 'M' | 'S' | 'XL' — Pin the reasoning depth (S < M < L < XL). Defaults to L when omitted. Higher depths trade latency for thoroughness.

## Response `200`

Research task created successfully.

- PostResearchOutputOutput
  - `createdAt` string, date-time, required — The date and time when the task was created.
  - `error` string, nullable, required — The error message if the task failed.
  - `id` string, required — The unique identifier of the task.
  - `status` 'completed' | 'failed' | 'pending' | 'processing', required — The current status of the task.
  - `updatedAt` string, date-time, required — The date and time when the task status was last updated.
  - `input` ResearchTaskInputOutput, required
    - `excludeDomains` string[] — The domains you want to exclude of the search. By default, don't restrict the search.
    - `fromDate` string, date — 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.
    - `includeDomains` string[] — The domains you want to search on. By default, don't restrict the search. You can provide up to 100 domains.
    - `q` string, required — The natural language question for which you want to retrieve context.
    - `structuredOutputSchema` object — Required only when `outputType` is `structured`. Provide a JSON schema object representing the desired response format. The root must be of type `object`.
    - `toDate` string, date, required — 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.
    - `mode` 'answer' | 'auto' | 'investigate' | 'research', required — Pin the research agent mode. Omit to let the agent auto-classify per request based on the question.
    - `outputType` 'sourcedAnswer' | 'structured', required — The type of output you want to get. Use `structured` for a custom-formatted response defined by `structuredOutputSchema`.
    - `reasoningDepth` 'L' | 'M' | 'S' | 'XL', required — Pin the reasoning depth (S < M < L < XL). Defaults to L when omitted. Higher depths trade latency for thoroughness.
  - `output` union, required
    - ResearchSourcedAnswerOutputOutput
      - `answer` string, required — The answer to your question.
      - `sources` SourceOutput[], required — List of sources used to answer the question.
        - `name` string, required — The title or name of the resource.
        - `url` string, uri, required — The URL of the resource.
        - `favicon` union, required — The favicon URL, if available.
          - '', uri
          - string, uri
        - `snippet` string, required — Extracted text content associated with the source.
    - StructuredOutputOutput
  - `type` 'research', required

## Other responses

- `400` — Bad Request - Invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `402` — Payment Required - No API key provided. Returns x402 payment details in the `payment-required` header for pay-per-request with USDC.
- `429` — Too Many Requests - Rate limit exceeded or insufficient credits

---

[API](https://skmtc.net/linkup/apis/linkup-api.md) · [All operations](https://skmtc.net/linkup/apis/linkup-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/linkup/linkup-api/versions/1e5050ee899a/schema)