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#
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.
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'{
"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)#
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).
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: {...}
}EventSource cannot send the Authorization header, and your key must never reach a browser: read the stream on your server.