Guides

Batches and live progress

Run one tool on many files with per-file results, and follow a task live with Server-Sent Events.

Batches#

POST/tasks/batch

One tool, up to 20 files, one task per file. A file that is refused — wrong type, too large, daily limit reached — gets an error in its place and does not stop the others: 201 when every file was accepted, 207 when some were refused. Each task counts like one POST /tasks.

Shell
curl https://macaaw.com/public/v1/tasks/batch \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -F 'data={"tool": "compress-pdf"}' \
  -F 'files[]=@a.pdf' -F 'files[]=@b.pdf' -F 'files[]=@notes.txt'
207 Multi-Status
{
  "id": "5f0e…",
  "tool": "compress-pdf",
  "results": [
    {
      "index": 0,
      "task": {
        "id": "…",
        "status": "task.queued"
      },
      "error": null
    },
    {
      "index": 1,
      "task": {
        "id": "…",
        "status": "task.queued"
      },
      "error": null
    },
    {
      "index": 2,
      "task": null,
      "error": {
        "code": "VALIDATION",
        "detail": "Check the details and try again."
      }
    }
  ],
  "summary": {
    "accepted": 2,
    "rejected": 1
  }
}

GET /task-batches/{id} answers the same shape with each task's current state.

Live progress (Server-Sent Events)#

GET/tasks/{id}/events

A text/event-stream with the same Authorization: API-Key … header as every other call. You get a status event with the task (as GET /tasks/{id}) at once and whenever it changes, then end when it has finished. A comment arrives every 15 seconds; the stream closes after 600 seconds — reconnect to go on (the whole state is sent each time, so nothing is lost).

Node.js (fetch streaming)
const res = await fetch(`https://macaaw.com/public/v1/tasks/${taskId}/events`, { headers: { Authorization: `API-Key ${process.env.MACAAW_API_KEY}` } });
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(value); // event: status / data: {...}
}
Browsers' EventSource cannot send the Authorization header, and your key must never reach a browser: read the stream on your server.
Batches and live progress · Macaaw API