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

# Tasks

> Give a public website and a goal in plain words. A browser clicks through it and returns an answer or named fields, with no session of your own.

A task starts a browser on a public page, works toward your goal, and closes the browser for you. It answers at once with an `id`, and the task runs in the background.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/browser/task \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.python.org",
    "goal": "Open the Downloads page and find the latest Python release number and its release date.",
    "schema": {"type": "object", "properties": {"version": {"type": "string"}, "releaseDate": {"type": "string"}}},
    "maxSteps": 10,
    "maxCost": 0.05
  }'
```

The TypeScript SDK has `stophy.browser.task(...)` and `stophy.browser.task.status(...)` with the same fields. Starting a task is free. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Read the result

Send the `id` to `POST /v1/browser/task/status` until `status` is `done`. The call is free. While the task runs, `result` is `null`.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/browser/task/status \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<the id your task returned>"}'
```

```json theme={null}
{
  "success": true,
  "data": {
    "status": "done",
    "result": { "done": true, "fields": { "version": "3.15.2", "releaseDate": "Oct. 25, 2026" } },
    "costUsd": 0.014
  }
}
```

* `result.done` says whether the goal was met. When it is `false`, `reason` says why.
* `answer` is the result in words. `steps` lists what the task clicked. `url` and `title` are the page it ended on.
* With a `schema`, `fields` holds one value per property and `confidence` rates each from 0 to 1. A field no page stated is `null`.
* `costUsd` is what the task cost. `creditsUsed` is the older field for the same amount.

A task is kept for 24 hours after it starts.

## Request fields

| Field | Default | Meaning |
| - | - | - |
| `url` | none | The public page to start on. Required. |
| `goal` | none | What to get done, up to 1,000 characters. Required. |
| `values` | none | Values the steps need, such as `from London, to Istanbul, date 2026-12-01`, up to 1,000 characters. They are typed only on the start page's site. |
| `schema` | none | A JSON Schema object with `properties`. Each field is checked against the pages the task saw. |
| `maxSteps` | `50` | The most steps, 1 to 50 |
| `maxCost` | the full 10 minutes | The most the task may spend, in US dollars. The task stops when it is spent. Starting a task sets that amount aside, and what it does not use comes back. |

A task stops before anything that pays, books, sends, submits or deletes, and never signs in. It takes up to 50 steps and 10 minutes. For a login or a flow you control, open a [browser session](https://docs.stophy.dev/browser/overview) and use [Execute](https://docs.stophy.dev/browser/execute.md).

## Errors

* Too many tasks open: `429 rateLimited`. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md).
* A `maxCost` below one browser minute, or a `schema` that is not an object with `properties`: `400 invalidRequest`.
* An unknown id, or one older than 24 hours: `404 notFound`.
* A balance too low to cover `maxCost`: `402 insufficientCredits`, and the task does not start.


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