Skip to main content
A browser task does a few steps a person would click through on a public site, such as a search with filters or a form to fill, and returns what it found. You send a start page and a goal. You do not open or close a session.

Start a task

Get an API key in the Quickstart. Send url, goal and, if you want fields back, a schema. POST /v1/browser/task answers at once with an id, and the task runs in the background.

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.
This real task finished in 9 seconds.
result.done says whether the goal was met. answer is the result in words, and 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 says how sure the task is of each, from 0 to 1. A field that no page stated comes back null. When the goal was not met, done is false and reason says why. costUsd on data is what the task cost. creditsUsed is the older field for the same amount, in steps of $0.002. A task is kept for 24 hours after it starts.

Options

What a task will not do

A task stops before anything that pays, books, sends, submits or deletes. It never signs in to a site. It takes up to 50 steps and 10 minutes. For logged-in work, or a flow you want to control, open a browser session and use Execute.

Price

$0.84 per hour of browser time the task runs, billed by the minute, one minute at least, up to `maxCost`. Each minute is $0.014. The task above ran 9 seconds and cost $0.014, one minute. A task that ends before its first step costs nothing. Starting a task sets aside the most it can cost, and what it does not use comes back when it ends. Send maxCost to set that amount: 0.05 allows 3 minutes. Without it, the task may spend up to 10 minutes, $0.14. See Pricing.

Limits and errors

  • You can have 2 tasks open at once. A third returns 429 rateLimited: You have 2 browser tasks open, the most at once. Start another when one ends, which is within 15 minutes.
  • A maxCost below one minute returns 400 invalidRequest: maxCost must cover at least one browser minute, which is $0.014 ($0.84 per hour).
  • A schema that is not an object with properties returns 400 invalidRequest: schema: Send a JSON Schema object with properties, or one whose $ref points at such an object.
  • A task id that is unknown, or older than 24 hours, returns 404 notFound: Stophy has no browser task with that id. Check the id. A browser task is kept for 24 hours after it starts.
  • A balance too low to cover maxCost returns 402 insufficientCredits and the task does not start.