Skip to main content
Agent tasks are predefined browser operations that run in an existing session. List the task catalogue, then submit a task name and its parameters. Responses include ok, data, steps, and error. Tasks leave the session open. Delete it when no further operations are needed.

GET /v1/agent/tasks

The response includes tasks and task_schemas. Each schema describes a task’s parameters with name, type, required, and default when defined. Use these schemas to validate parameters before starting a task. List the task names you can pass to POST /v1/agent. Auth: Bearer API key. No body, no parameters.
Free, no session needed. Errors: 401 only.

POST /v1/agent

Run one task in a session’s browser and return its result, or start it in the background and return a job id. Auth: Bearer API key. The session must belong to the same key. Request: Every string in params that looks like a URL, at any depth, is checked before the task starts: a host that resolves to a private, loopback or cloud-metadata address is refused with 400. Where the task runs: when params.url is given the task navigates to it first. Without a URL the task acts on the page the session is already showing, which is the page a POST /v1/session/{id}/navigate left open. Tasks that have no url parameter at all (click_by_text, dismiss_popups, follow_link_by_text, handle_new_tab, navigate_spa, upload_file, captcha_gated_flow, and multi_step_checkout without cart_url) need a page to be open and answer ok: false with error: "no_page: navigate the session to a page first" when the session shows a blank tab. evaluate_js runs wherever the tab is, including a blank one. Response: evaluate_js with a URL:
wait_and_extract with a field map (first_words trimmed):
async_mode, then the job poll. The script ran without a url on a session that had no page open, so the value is the blank tab’s address:
GET /v1/job/sess_3d245e9c250d4713b0f633ab34f018f0.035cc5179b874715a04e64db260a33c3:
The job envelope is session_id, job_id, kind (agent here, template for a template job), status (pending, done, error, cancelled) and result, which is the task result once the job is done. The job keeps the session from idling out while it runs. Errors: A task that fails inside the browser is not an HTTP error: the answer is 200 with ok: false and error set. Notes:
  • Deadline: 300 s per run. A task that does not finish answers ok: false, error: "task_timeout: did not finish in 300 s".
  • Serialisation: a second drive waits up to about 3 seconds, then returns 409 session_busy. A main CDP, native Playwright, or VNC client causes 409 session_driven_by_client. CDP observers can remain connected. Coordinate their commands with the task, or use separate sessions for independent work.
  • Billing: one action credit per successful run (ok: true); a failed run is not charged. In async mode the charge happens when the job completes.
  • Secrets: a login run, or any task whose parameters carry a vault:// reference, never places the secret in steps, data or meta.
  • Tabs a task opens for itself are closed when it ends. The page your session was showing before the call stays as the task left it.

Task catalogue

Required parameters are marked “required”; everything else is optional with the default shown. url always means “navigate there first”.

Vault references in task parameters

login accepts vault://<kind>/<name> in username, password and totp (for example vault://password/github-com). The reference is resolved to the stored secret at the moment of the fill and discarded afterwards; nothing of it reaches steps, data or meta. The referenced credential’s declared host pins where it may be typed: a login page on another origin is refused unless you name that origin in allow_hosts. Credentials are created from the dashboard or through a connect link (see Credentials below), and listed with GET /v1/credentials, which returns the path you put after vault://.