> ## Documentation Index
> Fetch the complete documentation index at: https://intunedhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Tasks

> An API for repeatable web tasks, described in natural language and executed with a mix of AI and generated code

## What are Web Tasks?

The **Web Tasks API** lets you describe a web task in plain English and have it executed for you. This can be:

* Scraping a directory.
* Filling a multi-page form.
* Downloading a batch of files.
* Pulling data out of a table.

You send a task description, an optional starting URL, any parameters it needs, and the shape of the output you want back. The API runs the task and returns the result.

Under the hood, the AI decides which parts of the task benefit from being code, writes that code on the fly, and reuses it on later runs. Across repeat calls with the same [`reuseKey`](#reuse-and-the-reusekey), executions get faster, cheaper, and more consistent, because each run executes saved code instead of re-exploring the site from scratch.

Web Tasks are **workspace-scoped**. Unlike [Projects](/main/00-getting-started/how-intuned-works), you don't create, deploy, or maintain anything. You call the API and get a result.

## When to use Web Tasks

Use Web Tasks when:

* The task **benefits from generated code**, such as crawling pages, extracting data across many entities, repeated multi-step actions.
* You'll **run the same task (or variations of it) more than once**. The payoff comes from reuse.
* You want the API to write and maintain the automation for you instead of owning the code yourself.

Use a [Project](/main/00-getting-started/how-intuned-works) instead when:

* You want to run the deterministic code without AI in the loop, or you want to control exactly when AI is involved.
* You want to write, debug, and own the automation code yourself, in the [online IDE](/main/02-features/online-ide) or [locally with the CLI](/main/02-features/local-development-cli).
* You need full visibility into the code and every execution, such as [browser traces, logs, and attempt timeline](/main/02-features/observability-monitoring-logs).
* You want advanced issue monitoring and auto-maintenance via [self-healing projects](/main/02-intuned-agent/self-healing-projects).
* You need platform features like [AuthSessions](/main/02-features/auth-sessions), [Jobs and scheduling](/main/02-features/jobs-batched-executions), or [Sinks](/client-apis/api-reference/sinks/overview).

## Core concepts

### Start and result

Web Tasks use a two-call lifecycle, same as other long-running Intuned APIs:

* [`POST /{workspaceId}/web-tasks/start`](/client-apis/api-reference/webtasks/web-task--start) - submit the task. Returns a `webTaskId` immediately.
* [`GET /{workspaceId}/web-tasks/{webTaskId}/result`](/client-apis/api-reference/webtasks/web-task--result) - poll for status and result.

### Request fields

| Field          | Required | Description                                                                                                                                             |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `task`         | Yes      | Natural-language instruction describing the task.                                                                                                       |
| `startUrl`     | No       | Optional hint telling the agent where to start in the browser. If omitted, the agent decides from the task description.                                 |
| `parameters`   | No       | Structured inputs that may change between runs (for example, `{ "batch": "S24" }`).                                                                     |
| `outputSchema` | No       | JSON Schema (draft 2020-12) for the desired result shape. If omitted, the system infers a format from the task.                                         |
| `reuseKey`     | No       | Label that ties this run to a reusable automation. See [Reuse and the reuseKey](#reuse-and-the-reusekey). If omitted, the server generates one for you. |
| `model`        | No       | Model the agent runs with: `haiku`, `sonnet`, or `opus`. Defaults to `haiku`. Heavier models help on harder tasks at higher cost.                       |

### Status model

A Web Task moves through these states:

* `pending`: created, not yet executing.
* `started`: executing.
* `completed`: finished. The response includes an `outcome` of `success` or `failed`.

Failed tasks are still `completed`, with a different outcome distinguishing them (reference the [Example response](#example-responses) below). Failed runs never update saved reusable code.

### Result delivery

The server decides how to return the result:

* **Inline**: small outputs (booleans, short text, small arrays, small objects) come back directly in the response under `result.data`.
* **File**: large outputs come back as a downloadable URL under `result.file`, often with a `preview` (row count and a small sample). File URLs are signed and expire after 7 days.

You don't choose the mode upfront.

### Cost

Final responses include cost when available:

* `cost.aiUsd`: AI/model cost in dollars.
* `cost.compute`: runtime compute usage in hours.

## Reuse and the `reuseKey`

`reuseKey` is the mechanism that makes Web Tasks get cheaper and faster over time.

**With a `reuseKey`**, the system loads any code saved under that key and tries to run it. If the existing code works, it returns the result. If not, the AI repairs or updates the code. On success, the improved code is saved back under the same key. On failure, the previous code is left untouched.

**Without a `reuseKey`**, the server still creates a reusable bundle for the run. It auto-generates a `wtr_`-prefixed key, saves code under it, and returns it on the result as `reuse.key`. Pass that key on later calls when you want to reuse the same automation.

Same `reuseKey` means **the same reusable automation**, regardless of URL or parameters. If you want different automations, use different keys (`yc_companies`, `wellfound_companies`, `shopify_products`).

For the full execution model and reuse rules, see [How Web Tasks work](./how-it-works).

## Example

The simplest path is the SDK `run()` helper, which submits the task and polls for the result for you. Default poll interval is 5 seconds; you can pass an optional timeout.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { IntunedClient } from "@intuned/client";

  const client = new IntunedClient({
    apiKey: "<YOUR_API_KEY>",
    workspaceId: "<YOUR_WORKSPACE_ID>",
  });

  const result = await client.webTasks.run(
    {
      task: "Scrape companies from the YC directory",
      startUrl: "https://www.ycombinator.com/companies",
      parameters: { batch: "S24" },
      reuseKey: "yc_companies",
    },
    { pollIntervalMs: 5000, timeoutMs: 10 * 60 * 1000 },
  );

  console.log(result.status, result.outcome);
  ```

  ```python Python theme={null}
  from intuned_client import IntunedClient
  from intuned_client.models import WebTasksStartRequestBody

  with IntunedClient(
      workspace_id="<YOUR_WORKSPACE_ID>",
      api_key="<YOUR_API_KEY>",
  ) as client:
      result = client.web_tasks.run(
          body=WebTasksStartRequestBody(
              task="Scrape companies from the YC directory",
              start_url="https://www.ycombinator.com/companies",
              parameters={"batch": "S24"},
              reuse_key="yc_companies",
          ),
          poll_interval_seconds=5.0,
          timeout_seconds=600,
      )
      print(result.status, result.outcome)
  ```
</CodeGroup>

If you can't use the SDK, call the endpoints directly:

```bash theme={null}
# Start a task
curl -X POST "https://api.intuned.io/{workspaceId}/web-tasks/start" \
  -H "x-api-key: $INTUNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Scrape companies from the YC directory",
    "startUrl": "https://www.ycombinator.com/companies",
    "parameters": { "batch": "S24" },
    "reuseKey": "yc_companies"
  }'

# Poll for the result
curl "https://api.intuned.io/{workspaceId}/web-tasks/{webTaskId}/result" \
  -H "x-api-key: $INTUNED_API_KEY"
```

### Example responses

<CodeGroup>
  ```json Successful inline response theme={null}
  {
    "webTaskId": "wt_123",
    "status": "completed",
    "outcome": "success",
    "result": {
      "type": "inline",
      "data": [
        {
          "name": "ExampleCo",
          "batch": "S24",
          "url": "https://www.ycombinator.com/companies/exampleco"
        }
      ]
    },
    "reuse": {
      "key": "yc_companies",
      "used": false,
      "created": true,
      "updated": true
    },
    "cost": {
      "aiUsd": 0.42,
      "compute": { "unit": "hours", "amount": 0.023 }
    }
  }
  ```

  ```json Successful file response theme={null}
  {
    "webTaskId": "wt_123",
    "status": "completed",
    "outcome": "success",
    "result": {
      "type": "file",
      "file": {
        "url": "https://files.intuned.io/results/wt_123.json?signature=abc&expires=1700000000",
        "contentType": "application/json",
        "sizeBytes": 204800,
        "expiresAt": "2026-06-01T22:13:20.000Z"
      }
    },
    "reuse": {
      "key": "yc_companies",
      "used": false,
      "created": true,
      "updated": true
    },
    "cost": {
      "aiUsd": 0.42,
      "compute": { "unit": "hours", "amount": 0.023 }
    }
  }
  ```

  ```json Failed response theme={null}
  {
    "webTaskId": "wt_123",
    "status": "completed",
    "outcome": "failed",
    "error": {
      "code": "rejected",
      "message": "Could not open the page at https://www.ycombinator.com/companies. The website may be down."
    },
    "reuse": {
      "key": "yc_companies",
      "used": false,
      "created": false,
      "updated": false
    },
    "cost": {
      "aiUsd": 0.1,
      "compute": { "unit": "hours", "amount": 0.003 }
    }
  }
  ```
</CodeGroup>

## Cost and billing

Web Tasks consume AI credits based on tokens used and Compute Hours based on the execution time of the tasks. Free plans include credits to get started. Track spend on the [Usage page](https://app.intuned.io/usage).

See [Plans and billing](/main/05-references/plans-and-billing) for plan limits and [Usage and billing](/main/02-features/usage-pricing-monitoring-alerting) for tracking spend. You can also [bring your own Anthropic API key (BYOK)](/main/02-features/usage-pricing-monitoring-alerting#bring-your-own-key-byok) instead of using AI credits.

## Limits

* Each workspace can run up to 10 different Web Tasks concurrently ([Contact support](/main/06-resources/help-and-support) if you need a higher limit).
* Same-`reuseKey` runs are serialized: runs that share a `reuseKey` execute one at a time so two runs don't update the same code concurrently. Runs with different keys can run in parallel.
* Failed runs return `outcome: "failed"` with an `error.code`. Possible codes: `workspace-rate-limited`, `unauthenticated`, `no-ai-credits-left`, `timeout`, `rejected`, `internal-error`.

## FAQ

<AccordionGroup>
  {" "}

  <Accordion title="Can Web Tasks bypass CAPTCHAs or bot detection?">
    Yes. Web Tasks support [stealth mode and CAPTCHA
    solving](/main/02-features/stealth-mode-captcha-solving-proxies) and proxies out of the box and will use them when needed.
  </Accordion>

  {" "}

  <Accordion title="Do Web Tasks work with authenticated websites?">
    No, not yet. Web Tasks currently only work with publicly accessible websites. Support for authenticated sessions is coming soon.
  </Accordion>

  {" "}

  <Accordion title="Can I use my existing Claude Code subscription?">
    No. Web Tasks uses their own AI credits system, separate from any Claude
    Code or Anthropic Console subscription. You can [bring your own Anthropic API
    key
    (BYOK)](/main/02-features/usage-pricing-monitoring-alerting#bring-your-own-key-byok)
    to use your own key instead of AI credits.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="How Web Tasks work" icon="book" href="./how-it-works">
    Execution model and reuse rules in detail
  </Card>

  <Card title="API reference" icon="server" href="/client-apis/api-reference/webtasks/web-task--start">
    Start and result endpoints
  </Card>

  <Card title="CLI reference" icon="terminal" href="/main/05-references/cli/platform#web-tasks-start">
    Run Web Tasks from the `intuned platform webtasks` commands
  </Card>
</CardGroup>