DocsAPI

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.

Requestbash
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"}'

The request

  • tasks: 1 to 100, in the order to run them. Each is its words, or a whole task as POST /jobs takes it (every field but files).
  • defaults: settings every task gets unless it sets its own (startUrl, model, region, maxSteps, outputSchema, identity, webhookUrl for each task's own events…).
  • name, and webhookUrl for batch.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, and reason says 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, or DELETE /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

GET /batches/:idjson
{
  "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, or stopped (with reason).
  • Each item's status: pending (not started yet), its task's status once started (queued, running, needs_input, done, failed, cancelled), failed with error when the task was refused at its start, or skipped. Its jobId is a task like any other: GET /jobs/:id for its whole result, files and replay.
  • GET /batches lists your batches, newest first, without their items (limit, cursor, status; an admin's all=1 lists 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.