> ## 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.

# Tasks overview

> Asynchronous batch wrapper around /search, /fetch, and /research.

**Tasks** is Linkup's asynchronous batch wrapper around [**Search**](https://docs.linkup.so/pages/documentation/endpoints/search/overview.md), [**Fetch**](https://docs.linkup.so/pages/documentation/endpoints/fetch/overview.md), and [**Research**](https://docs.linkup.so/pages/documentation/endpoints/research/overview.md). A single submission to `/tasks` accepts up to 100 tasks, in any mix of the three endpoints, with the same parameters and pricing as direct calls. There is no batching surcharge.

> [!TIP]
>
> No batching surcharge means **Tasks** is useful even for 2–3 calls when
> one polling loop is simpler than several synchronous ones.

**Tasks** is appropriate for bulk and scheduled workloads. Guidance on when
to reach for **Tasks** versus the synchronous endpoints lives on the
[Tasks best practices](https://docs.linkup.so/pages/documentation/endpoints/tasks/best-practices.md#when-to-use-tasks)
page.

## How it works

1. `POST /tasks` with an array of `{ type, input }` objects. Returns task identifiers immediately.
2. Poll `GET /tasks/{id}` for a specific task, or `GET /tasks` to list all tasks for the account.
3. While running, `status` is `"pending"` or `"processing"`. On completion, read the `output` field. On failure, inspect `error`.

> [!WARNING]
>
> Maximum 100 tasks per submission. Larger workloads must be split across
> multiple submissions.

## Parameters per task type

Each task carries the same parameters as the corresponding synchronous endpoint:

| `type` | `input` parameters | Reference |
| - | - | - |
| `"search"` | Same as `/search`: `q`, `depth`, `outputType`, `includeDomains`, ... | [POST /search](https://docs.linkup.so/pages/documentation/endpoints/search/reference.md) |
| `"fetch"` | Same as `/fetch`: `url`, `mode`, `renderJs`, `includeRawHtml`, `extractImages`, `schema`, `instructions` | [POST /fetch](https://docs.linkup.so/pages/documentation/endpoints/fetch/reference.md) |
| `"research"` | Same as `/research`: `q`, `outputType`, `mode`, `reasoningDepth`, ... | [POST /research](https://docs.linkup.so/pages/documentation/endpoints/research/post.md) |

> [!NOTE]
>
> Tasks in a single submission can mix `"search"`, `"fetch"`, and `"research"`
> freely — each carries its own parameters and is billed at its own rate.

## Pricing

Each task is billed exactly as a direct synchronous call to the same
endpoint. No batching surcharge, no batching discount.

| Task type | Cost |
| - | - |
| `"search"` (`"flash"` (alpha)/`"fast"`/`"standard"`, `"searchResults"`) | \$0.005 |
| `"search"` (`"flash"` (alpha)/`"fast"`/`"standard"`, `"sourcedAnswer"`/`"structured"`) | \$0.006 |
| `"search"` (`"deep"`, `"searchResults"`) | \$0.05 |
| `"search"` (`"deep"`, `"sourcedAnswer"`/`"structured"`) | \$0.055 |
| `"fetch"` (`mode` = `"standard"`, no JS) | \$0.001 |
| `"fetch"` (`mode` = `"standard"`, with JS) | \$0.005 |
| `"fetch"` (`mode` = `"pro"`, no JS) | \$0.005 |
| `"fetch"` (`mode` = `"pro"`, with JS) | \$0.01 |
| `"fetch"` with `schema` | Add \$0.001 to the matching row above |
| `"research"` (`"S"`) | \$0.25 |
| `"research"` (`"M"`) | \$0.50 |
| `"research"` (`"L"`) | \$1.50 |
| `"research"` (`"XL"`) | \$2.50 |

## Example

> [card] [Get your API key](https://app.linkup.so)
>
> Create a Linkup account for free to get your API key.

```python python theme={"system"}
from linkup import LinkupClient

client = LinkupClient(api_key="<YOUR_LINKUP_API_KEY>")

tasks = client.tasks.create([
    {
        "type": "search",
        "input": {
            "q": "What is Microsoft's 2024 revenue?",
            "depth": "deep",
            "outputType": "sourcedAnswer",
            "includeDomains": ["microsoft.com", "agolution.com"],
            "excludeDomains": ["wikipedia.org"],
        },
    },
    {
        "type": "fetch",
        "input": {
            "url": "https://docs.linkup.so",
            "mode": "standard",
            "renderJs": False,
        },
    },
    {
        "type": "research",
        "input": {
            "q": "Compare 2024 cloud revenue growth of Microsoft, Amazon, and Google.",
            "outputType": "sourcedAnswer",
            "mode": "investigate",
            "reasoningDepth": "L",
        },
    },
])

for t in tasks:
    print(t.id, t.type, t.status)
```

```js js theme={"system"}
import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({ apiKey: '<YOUR_LINKUP_API_KEY>' });

const tasks = await client.tasks.create([
  {
    type: 'search',
    input: {
      q: "What is Microsoft's 2024 revenue?",
      depth: 'deep',
      outputType: 'sourcedAnswer',
      includeDomains: ['microsoft.com', 'agolution.com'],
      excludeDomains: ['wikipedia.org'],
    },
  },
  {
    type: 'fetch',
    input: {
      url: 'https://docs.linkup.so',
      mode: 'standard',
      renderJs: false,
    },
  },
  {
    type: 'research',
    input: {
      q: 'Compare 2024 cloud revenue growth of Microsoft, Amazon, and Google.',
      outputType: 'sourcedAnswer',
      mode: 'investigate',
      reasoningDepth: 'L',
    },
  },
]);

for (const t of tasks) {
  console.log(t.id, t.type, t.status);
}
```

```shell curl theme={"system"}
curl --request POST \
  --url https://api.linkup.so/v1/tasks \
  --header "Authorization: Bearer $LINKUP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "type": "search",
    "input": {
      "q": "What is Microsoft'\''s 2024 revenue?",
      "depth": "deep",
      "outputType": "sourcedAnswer",
      "includeDomains": ["microsoft.com", "agolution.com"],
      "excludeDomains": ["wikipedia.org"]
    }
  },
  {
    "type": "fetch",
    "input": {
      "url": "https://docs.linkup.so",
      "mode": "standard",
      "renderJs": false
    }
  },
  {
    "type": "research",
    "input": {
      "q": "Compare 2024 cloud revenue growth of Microsoft, Amazon, and Google.",
      "outputType": "sourcedAnswer",
      "mode": "investigate",
      "reasoningDepth": "L"
    }
  }
]'
```

`POST /v1/tasks` returns an array of task envelopes immediately, with
`status` of `"pending"` and `output` of `null`. Poll `GET /v1/tasks/{id}` (or
`GET /v1/tasks` for bulk listing) to retrieve completed results:

```json theme={"system"}
[
  {
    "id": "01234-abcd-56789",
    "type": "search",
    "status": "pending",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "error": null,
    "input": { "q": "What is Microsoft's 2024 revenue?", "depth": "deep", "outputType": "sourcedAnswer" },
    "output": null
  },
  {
    "id": "01234-abcd-56790",
    "type": "fetch",
    "status": "pending",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "error": null,
    "input": { "url": "https://docs.linkup.so", "mode": "standard", "renderJs": false },
    "output": null
  }
  // ... one envelope per submitted task
]
```

Once `status` is `"completed"`, `output` is populated with the same shape as
the corresponding synchronous endpoint's response. On `"failed"`, `error`
carries a string explanation.

## Next

> [card] [Best practices](https://docs.linkup.so/pages/documentation/endpoints/tasks/best-practices.md)
>
> Batch sizing, polling strategy, error handling.

> [card] [For AI agents](https://docs.linkup.so/pages/documentation/endpoints/tasks/for-agents.md)
>
> Tool definition and integration prompt.

> [card] [API reference](https://docs.linkup.so/pages/documentation/endpoints/tasks/post.md)
>
> Full parameter spec and response schema.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.