Batches
Many tasks in one request: pilotfish runs them one after another and collects their results together.
Use a batch for the same kind of task over a list: each product's price, each company's careers page, each lead's website. For one task that spans several sites, send it as one task: pilotfish plans the parts itself.
curl -X POST https://pilotfish-be.gai.ventures/batches \
-H "Authorization: Bearer pf_YOUR_KEY" -H "content-type: application/json" \
-d '{"name":"Prices","tasks":["Price of the Logitech MX Keys on amazon.com",{"task":"Price of the Logitech MX Keys on bestbuy.com","region":"us"}],"defaults":{"maxSteps":40,"outputSchema":{"type":"object","properties":{"product":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}},"required":["product","price","currency"],"additionalProperties":false}},"webhookUrl":"https://example.com/hooks/pilotfish"}'const batch = await pf.batches.run({
name: "Prices",
tasks: ["Price of the Logitech MX Keys on amazon.com", { task: "Price of the Logitech MX Keys on bestbuy.com", region: "us" }],
defaults: { maxSteps: 40, outputSchema: {"type":"object","properties":{"product":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}},"required":["product","price","currency"],"additionalProperties":false} },
});
for (const item of batch.items ?? []) console.log(item.status, item.result?.data, item.costUsd);batch = pf.batches.run({
"name": "Prices",
"tasks": ["Price of the Logitech MX Keys on amazon.com", {"task": "Price of the Logitech MX Keys on bestbuy.com", "region": "us"}],
"defaults": {"maxSteps": 40},
})
for item in batch["items"]:
print(item["status"], (item["result"] or {}).get("result"), item["costUsd"])The request
tasks: 1 to 100, in the order to run them. Each is its words, or a whole task asPOST /jobstakes it (every field butfiles).defaults: settings every task gets unless it sets its own (startUrl,model,region,maxSteps,outputSchema,identity,webhookUrlfor each task's own events…).name, andwebhookUrlforbatch.finished.
A batch with any task the API would refuse (a bad field, an identity it can't use, a webhook address it can't reach) is refused whole, before anything runs, with the task's index in the message (tasks[3]: …).
How it runs
- One at a time. Tasks run one after another, under the same one-task-at-a-time rule as every task (per person, per API key, per identity). While your own other task runs, the batch waits for it. The batch survives restarts and deploys.
- Paid per task, as it runs. Each task is checked for credit when it starts and charged like any task. If one is refused for money (out of credits, an allowance used, the monthly limit), the batch stops: that task and the rest are
skipped, never run and never charged, andreasonsays why (no_credits: …). - A task that needs a person (a code, a sign-in, a yes) waits for them as any task does (its
answerUrl, or a task webhook), and the next one starts when it ends. A task that pauses (its spend check-in, a question left unanswered) counts as ended: carry it on later with a follow-up. - Cancel (
POST /batches/:id/cancel, orDELETE /batches/:id): the running task is cancelled and the rest are skipped. Nothing is deleted: every task stays in your history with its cost.
The batch
{
"id": "bat_8f2kQ1x",
"name": "Prices",
"status": "done",
"counts": {
"total": 2,
"pending": 0,
"running": 0,
"done": 2,
"failed": 0,
"cancelled": 0,
"skipped": 0
},
"costUsd": 0.0412,
"project": "default",
"createdAt": 1763539200000,
"updatedAt": 1763539412000,
"finishedAt": 1763539412000,
"url": "https://pilotfish-be.gai.ventures/batches/bat_8f2kQ1x",
"items": [
{
"index": 0,
"task": "Price of the Logitech MX Keys on amazon.com",
"status": "done",
"jobId": "job_Q2w9…",
"costUsd": 0.0198,
"result": {
"success": true,
"outcome": "done",
"result": "The Logitech MX Keys is $109.99 on amazon.com.",
"data": {
"product": "Logitech MX Keys",
"price": 109.99,
"currency": "USD"
}
},
"startedAt": 1763539201000,
"endedAt": 1763539305000,
"appUrl": "https://pilotfish.gai.ventures/tasks/job_Q2w9…"
}
]
}status:running,done(every task ended),cancelled, orstopped(withreason).- Each item's
status:pending(not started yet), its task's status once started (queued,running,needs_input,done,failed,cancelled),failedwitherrorwhen the task was refused at its start, orskipped. ItsjobIdis a task like any other:GET /jobs/:idfor its whole result, files and replay. GET /batcheslists your batches, newest first, without their items (limit,cursor,status; an admin'sall=1lists the organization's).
batch.finished
When every task has ended, or the batch was cancelled or stopped, webhookUrl gets batch.finished, signed like every webhook (Pilotfish-Signature, see the SDKs' verifyWebhook), with batchId and in data the status, reason, counts, costUsd, project and every item with its result.
From an AI agent
The managed MCP has the same as tools: run_batch (waits like browser_task, then returns each task's status and answer so far), get_batch and cancel_batch.