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

# Browser tasks

> Use a free-form goal for exploratory cloud browser work.

A browser task is the smallest way to ask Infragrid to explore a site and return a result. Use it when the route through the site is not known in advance.

## Start a task

<CodeGroup>
  ```typescript TypeScript theme={null}
  const created = await client.runs.create({
    task: "Find the pricing page and summarize the plans.",
    metadata: { customerId: "cust_123" },
    idempotencyKey: "pricing-summary-cust-123-v1"
  })

  const finished = await client.runs.wait(created.id)
  console.log(finished.result?.summary)
  ```

  ```python Python theme={null}
  created = client.runs.create(
      task="Find the pricing page and summarize the plans.",
      metadata={"customerId": "cust_123"},
      idempotency_key="pricing-summary-cust-123-v1",
  )
  finished = client.runs.wait(created["id"])
  print(finished["result"]["summary"])
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.infragrid.ai/v1/runs \
    --header "Authorization: Bearer $INFRAGRID_API_KEY" \
    --header "Content-Type: application/json" \
    --header "X-Idempotency-Key: pricing-summary-cust-123-v1" \
    --data '{"task":"Find the pricing page and summarize the plans.","metadata":{"customerId":"cust_123"}}'
  ```
</CodeGroup>

## Lifecycle

`queued` → `running` → `completed`, `failed`, or `cancelled`

The create call returns as soon as the run is durably accepted. Poll `GET /v1/runs/{run_id}`, use an SDK `wait` helper, or recover the same run later by ID.

## Task-writing guidance

* State the desired outcome and important constraints.
* Name the target site or starting URL when known.
* Ask for a bounded, inspectable result.
* Keep credentials out of the task string and metadata.
* Use an [ordered workflow](/guides/ordered-workflows) when exact sequencing matters.

## Metadata

Metadata is application-defined JSON returned with the run. Use it for safe correlation values such as a customer ID, job name, or environment. The serialized object is limited to 16 KB.

<Warning>
  Metadata and the resolved task are stored with the cloud run. Do not place passwords, session cookies, API keys, or extracted secrets in either field.
</Warning>

## Cancel a run

Cancellation is idempotent. A run that is already terminal returns its terminal state.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const cancelled = await client.runs.cancel(created.id)
  ```

  ```python Python theme={null}
  cancelled = client.runs.cancel(created["id"])
  ```
</CodeGroup>


## Related topics

- [Infragrid overview](/overview.md)
- [Create a run](/reference/runs/create.md)
- [MCP server](/tools/mcp.md)
- [Cancel a run](/reference/runs/cancel.md)
- [Get a run](/reference/runs/get.md)