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
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"]}
}'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'] },
});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:
{
"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.typeisquestion): a value such as a code received by text message, or a choice between options. Answer withPOST /v1/tasks/{id}/answerand thekeyof the question. - An approval (
pending.typeisapproval): 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 withPOST /v1/tasks/{id}/approve.
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 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 |
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.
Proof
Every step of the agent and the screenshots it saw are kept for 90 days. Read them with GET /v1/tasks/{id}/proof, or delete them now with DELETE. If a billed task is wrong, open a dispute: the proof is checked and the price is refunded when the claim is right.
Cancel and run again
POST /v1/tasks/{id}/cancel 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 creates a new task with the same input.
Follow a task
Three ways, from the simplest to the most efficient:
- Ask for it with
GET /v1/tasks/{id}. Fine for scripts. - Stream it with
GET /v1/tasks/{id}/stream: every step as it happens. - Receive webhooks on your server: see Webhooks. Best for production.