API reference

Run Pathfinder from your code

Create a key under Dashboard → API keys, then send it in the Authorization header. Tasks run in the same queue and use the same steps as the dashboard.

Authorization: Bearer pf_your_key

Start a task

POST /v1/tasks

Field	Type	About
`task`	string	What to do, in plain words (5–4000 characters).
`max_steps`	number	Most steps allowed per browser, 1–60. Default 25.
`copies`	number	Optional. Run the same task in this many separate browsers at once (default 1, up to your plan's batch limit).
`tasks`	list	Optional, instead of `task`. A list of different tasks, one browser each.

When more than one browser starts, the reply includes a batch_id. Check all of them at once with GET /v1/batches/{batch_id}, or stop them with POST /v1/batches/{batch_id}/cancel.

curl -X POST http://localhost:8080/v1/tasks \
  -H "Authorization: Bearer pf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"task":"Open news.ycombinator.com and list the top 3 titles","max_steps":12}'

# 201 → {"task":{"id":42,"status":"queued", ...}}

Check a task

GET /v1/tasks/{id}

Poll every few seconds until status is done, failed or cancelled.

{
  "task": {"id":42, "status":"done", "success":true, "steps_used":6,
           "answer":"1. ...  2. ...  3. ...", "recording":"recording.gif"},
  "steps": [{"n":1, "goal":"Open Hacker News", "results":["opened https://news.ycombinator.com"], "image":"step_01.png"}, ...],
  "credits": 144
}

Other endpoints

Endpoint	What it does
`GET /v1/tasks`	Your 50 most recent tasks.
`POST /v1/tasks/{id}/cancel`	Stops a queued or running task. Steps already taken are charged.
`POST /v1/tasks/{id}/messages`	Send `{"text":"..."}` to a running task. The agent reads it before its next step and may reply (replies show in `messages` on the task).
`GET /files/{id}/step_01.png`	Screenshot of a step (send your key).
`GET /files/{id}/recording.gif`	Recording of the whole run.

Python example

import time, requests
H = {"Authorization": "Bearer pf_your_key"}
t = requests.post("http://localhost:8080/v1/tasks", headers=H,
                  json={"task": "Tell me today's featured article on wikipedia.org"}).json()["task"]
while t["status"] in ("queued", "running"):
    time.sleep(3)
    t = requests.get(f"http://localhost:8080/v1/tasks/{t['id']}", headers=H).json()["task"]
print(t["status"], t["answer"])

Errors

Code	Meaning
`401`	Missing or wrong key.
`402`	Out of steps. Add more in the dashboard.
`403`	Task type not allowed (spam, fake activity, CAPTCHA solving, bulk accounts).
`429`	Too many tasks running at once on your account.