# Tasks

> How a Hapti task works from creation to result. Statuses, questions and approvals, structured output, budgets, languages, recipes and proof.

A task is one job done by an agent on a website. You give a starting address, a goal and the data it may use. The agent works in a real browser until the goal is reached, it needs something from a person, or it cannot go on.

## Create a task

:::tabs
```bash cURL
curl https://api.hapti.dev/v1/tasks \
  -H "Authorization: Bearer $HAPTI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: claim-AX-4471" \
  -d '{
    "url": "https://portal.example.com/claims",
    "goal": "Declare the water damage claim and give me the claim number.",
    "data": {"contract": "AX-4471", "date": "2026-11-20"},
    "user": "customer_42",
    "output": {"type": "object", "properties": {"claim_number": {"type": "string"}}, "required": ["claim_number"]}
  }'
```
```js JavaScript
const task = await hapti.tasks.create({
  url: 'https://portal.example.com/claims',
  goal: 'Declare the water damage claim and give me the claim number.',
  data: { contract: 'AX-4471', date: '2026-11-20' },
  user: 'customer_42',
  output: { type: 'object', properties: { claim_number: { type: 'string' } }, required: ['claim_number'] },
});
```
```python Python
task = hapti.tasks.create({
    "url": "https://portal.example.com/claims",
    "goal": "Declare the water damage claim and give me the claim number.",
    "data": {"contract": "AX-4471", "date": "2026-11-20"},
    "user": "customer_42",
    "output": {"type": "object", "properties": {"claim_number": {"type": "string"}}, "required": ["claim_number"]},
})
```
:::

The answer comes at once, before the agent starts:

```json
{
  "id": "tsk_9a96d9052acef545",
  "object": "task",
  "batch": null,
  "schedule": null,
  "mode": "test",
  "status": "queued",
  "paused": null,
  "level": "standard",
  "price_cents": 0,
  "starting_price_cents": 10,
  "billed": false,
  "user": "customer_42",
  "url": "https://portal.example.com/claims",
  "goal": "Declare the water damage claim and give me the claim number.",
  "input": {
    "data": {
      "contract": "AX-4471",
      "date": "2026-11-20"
    },
    "files": []
  },
  "pending": null,
  "learn": true,
  "used_recipe": null,
  "template": null,
  "created_by": {
    "type": "key",
    "id": "key_d160ed300d0cf627",
    "hint": "hp_test_7eF…ZD9D",
    "name": "default test key",
    "owner_email": null
  },
  "recipe_chosen": null,
  "recipe": null,
  "dispute": null,
  "result": null,
  "files": [],
  "usage": null,
  "created_at": "2026-11-22T18:40:56.170Z",
  "finished_at": null
}
```

Write the goal like you would brief a colleague: what to achieve, and what to report back. The goal can be in any language. The agent uses only what you put in `data` and never invents a missing value.

## Statuses

| Status | Meaning | Final | Billed |
| --- | --- | --- | --- |
| `queued` | Waiting for a browser | No | No |
| `running` | The agent is working | No | No |
| `waiting` | The agent needs an answer or an approval, see `pending` | No | No |
| `paused` | A live task waits for credit and starts by itself once credit is added | No | No |
| `succeeded` | The goal is reached | Yes | Yes, in live mode |
| `failed` | A technical failure on our side | Yes | No |
| `blocked` | The site refused, or does not offer what the goal needs | Yes | No |
| `needs_person` | Only the person can do the next step, for example in person or with a device they hold | Yes | No |
| `incomplete` | The agent ran out of steps, budget or time before the end | Yes | No |
| `cancelled` | You cancelled it | Yes | No |

`finished_at` is set only once the task is final and its result is saved, so a task with a final status and a `finished_at` is safe to read.

## Questions and approvals

When the agent needs something, the task goes to `waiting` and `pending` says what:

- **A question** (`pending.type` is `question`): a value such as a code received by text message, or a choice between options. Answer with [`POST /v1/tasks/{id}/answer`](/docs/api-tasks#answer-a-question) and the `key` of the question.
- **An approval** (`pending.type` is `approval`): only when you created the task with `"approval": "required"`. The agent stops before any step that commits the person, such as paying or sending. Answer with [`POST /v1/tasks/{id}/approve`](/docs/api-tasks#approve-or-refuse-a-step).

`pending.action_url` is a page where the person answers by themselves, once, without an account or a key. It is the simplest way to reach a customer in your app, by email or by text message.

By default the agent does not stop to ask permission: it does the final step that sends, confirms or pays. Use `"approval": "required"` when a person must confirm first, or give the person a [mandate](/docs/users#mandates) that says what the agent may do for them.

## Results

| Field | What it holds |
| --- | --- |
| `result.answer` | What the agent reports, in plain words |
| `result.data` | Structured data that follows your `output` schema |
| `files` | Files the site gave, such as invoices or certificates, see [Files](/docs/files) |
| `price_cents` | What was billed: 0 until a live task succeeds |
| `usage` | The number of actions the agent took |

### Structured output

Give a JSON Schema in `output` and `result.data` follows it. When the agent cannot fill the schema from what it saw, the task does not succeed and is not billed. Programs can trust `result.data` without parsing text.

### Languages

The agent writes its answer and its questions in the language of the goal. Set `answer_language` to choose another one, such as `pt-BR` or `wo`. The browser takes the language and time zone of the person when you give a `user`, or of `locale` and `country`. Nothing is forced to English or to any default country.

## Budget and limits

- `max_price_cents`: the agent stops before the price would go over it.
- `max_steps`: the most actions the agent may take, from 1 to 500.

A task that reaches its budget ends as `incomplete` and is not billed.

## Recipes

A task that succeeds becomes a recipe: the path the agent took. The next time the same task runs for your organisation, the agent replays the recipe first, which is faster and costs fewer actions, and falls back to looking at the screen when the site has changed. Set `"learn": false` to neither learn nor replay, or `recipe` to replay a given one. See [GET /v1/recipes](/docs/api-recipes).

## Proof

Every step of the agent and the screenshots it saw are kept for 90 days. Read them with [`GET /v1/tasks/{id}/proof`](/docs/api-tasks#get-the-proof), or delete them now with `DELETE`. If a billed task is wrong, [open a dispute](/docs/api-tasks#dispute-a-billed-task): the proof is checked and the price is refunded when the claim is right.

## Cancel and run again

[`POST /v1/tasks/{id}/cancel`](/docs/api-tasks#cancel-a-task) stops a task that is not over. A cancelled task is never billed, even if the agent was about to finish. [`POST /v1/tasks/{id}/retry`](/docs/api-tasks#run-a-task-again) creates a new task with the same input.

## Follow a task

Three ways, from the simplest to the most efficient:

1. **Ask for it** with [`GET /v1/tasks/{id}`](/docs/api-tasks#get-a-task). Fine for scripts.
2. **Stream it** with [`GET /v1/tasks/{id}/stream`](/docs/live): every step as it happens.
3. **Receive webhooks** on your server: see [Webhooks](/docs/webhooks). Best for production.
