APIs

Swarm API

Send a task the way you would prompt a model. An orchestrator plans the work, starts a team of agents, each in its own sandbox, reviews what they bring back and merges it into one result. You set the size and the budget; it never spends more.

POST/v1/swarmsCreate a swarm
GET/v1/swarmsList your swarms
GET/v1/swarms/{id}Status, plan, agents and spend
GET/v1/swarms/{id}/eventsLive events (SSE)
POST/v1/swarms/{id}/startStart a planned swarm
GET/v1/swarms/{id}/resultMerged result and agent reports
GET/v1/swarms/{id}/filesThe run folder
GET/v1/swarms/{id}/boardRead the shared board
POST/v1/swarms/{id}/boardSend every agent a note
POST/v1/swarms/{id}/resumeResume, optionally with more budget
POST/v1/swarms/{id}/cancelCancel and settle the bill

How a swarm runs

  1. 1

    Plan

    The orchestrator splits the task into independent subtasks, one per agent, and estimates agents, time and cost. Status planning.

  2. 2

    Work in rounds

    Agents work in parallel, each with its own sandbox. After a round the orchestrator reviews their reports and may send out another round. Status running.

  3. 3

    Merge

    When the work is done, or the budget or deadline is close, agents write up and the reports are merged into one result. Status wrapping_up.

  4. 4

    Done

    Status completed. The result, every agent's report and their files stay in the run folder. Unused budget goes back to your credits.

Create a swarm

POST/v1/swarms
curl https://swarmcomputers.com/v1/swarms \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Profile these 40 suppliers: pricing, certifications and a contact for each. One row per supplier, with sources.",
    "size": "medium",
    "budget_usd": 25,
    "deadline_minutes": 60
  }'

Body

taskstringrequired
What you want done, in plain language, up to 8,000 characters. Say what the result should look like (a table, a ranked list, a report). Optional only for the security preset.
goalstring
What done means, as something that can be counted or measured, up to 500 characters: "All 40 suppliers have a price and a contact", "The import runs 10x faster". See Goals.
sizestring
small, medium, large or max. Sets how wide and how long the swarm may go. Default small. See Sizes.
budget_usdnumber
The most this swarm may cost, from $1 to $100,000. Defaults to the size's budget. Required for max.
deadline_minutesinteger
Wrap up by this many minutes after work starts, 5 to 2,880. Agents get time to write up before it.
plan_onlyboolean
Plan and estimate, then wait in awaiting_approval until you start it.
modelstring
The model the agents run on. Defaults to deepseek-v4.1-flash; deepseek-v4.1-flash-uncensored is also available.
allow_domainsstring[]
Up to 20 of your verified domains the agents may reach. Without it, agents work offline.
webboolean
Let agents browse the open web. Enabled per account after review; until then the request is refused.
presetstring
security_scan runs the security preset against target.
targetstring
For security_scan: one of your verified domains.

The swarm is created at once and returned with status planning. Its whole budget is held from your credits; if your balance can't cover it you get 402 and nothing is created.

Sizes

A size is a ceiling, not a price. The planner uses as few agents as the task needs.

sizeAgents at onceDefault budgetRoundsPer agent, per subtaskTypical time
smallUp to 5$10220 min10–20 min
mediumUp to 20$50330 min20–40 min
largeUp to 50$150445 min30–60 min
maxUp to 100Required860 minhours

Goals

A task says what to do. A goal says when it is done, and a swarm works best when that is something that can be counted or measured: "all 40 suppliers have a price and a contact", "the import runs 10x faster", "every broken link on the site is listed with the page it is on".

With a goal, each round is scored against it from what the agents measured and reported. If the goal isn't met and there is budget and a round left, the next round goes after what is missing. When it is met, the swarm stops and returns the unused budget. The scores are on the swarm as progress, and each one is sent as a goal.progress event.

progress
"goal": "All 40 suppliers have a price and a contact.",
"progress": [
  { "round": 1, "percent": 55, "met": false, "note": "22 of 40 suppliers have both.", "spent_usd": 6.1, "at": "2026-11-21T10:42:00Z" },
  { "round": 2, "percent": 100, "met": true, "note": "All 40 have both, each with a source.", "spent_usd": 11.4, "at": "2026-11-21T10:58:00Z" }
]

The score is a reviewer's reading of the agents' reports, so ask for evidence in the task ("with a source link for each") when it matters. A goal is optional.

Get a swarm

GET/v1/swarms/{id}
Response
{
  "id": "swm_V1yQf3kK2bD9",
  "object": "swarm",
  "status": "running",
  "status_note": null,
  "task": "Profile these 40 suppliers: ...",
  "size": "medium",
  "model": "deepseek-v4.1-flash",
  "network": { "mode": "offline" },
  "budget_usd": 25,
  "spent_usd": 6.4,
  "rate_usd_per_agent_minute": 0.1,
  "round": 1,
  "estimate": { "agents": 8, "minutes": [20, 35], "cost_usd": [12.8, 22.4] },
  "plan": {
    "summary": "Eight agents, five suppliers each, then a review round.",
    "subtasks": [{ "title": "Suppliers 1-5", "minutes": 20 }]
  },
  "agents": [
    {
      "id": "agt_3f9a1c22b0e4",
      "round": 1,
      "title": "Suppliers 1-5",
      "status": "working",
      "activity": "Reading the pricing page",
      "inbox": null,
      "minutes_allowed": 20,
      "seconds_worked": 412,
      "steps": 31,
      "tokens": { "input": 182340, "output": 9120 },
      "error": null
    }
  ],
  "deadline_at": "2026-11-19T12:40:00.000Z",
  "pause_reason": null,
  "resume_until": null,
  "partial": false,
  "result": null
}

Statuses

statusMeaning
planningSplitting the task and estimating. Nothing is billed yet.
awaiting_approvalPlanned with plan_only. Waiting for /start.
runningAgents are working.
wrapping_upAgents are writing up and the result is being merged.
pausedStopped with sandboxes kept. See pause_reason: budget, deadline or requested.
completedDone. result is set. partial: true if it was merged before all the work finished.
failedCould not be planned or run. status_note says why.
cancelledStopped by you. The bill is final.

Agents move through queued, starting, working, finishing and end as done, failed or stopped. Starting a sandbox is not billed.

Plan first

Send "plan_only": true to see the plan and estimate before any agent starts. The swarm waits in awaiting_approval. Start it as is, or with a different budget:

POST/v1/swarms/{id}/start
curl
curl -X POST https://swarmcomputers.com/v1/swarms/$SWARM_ID/start \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"budget_usd": 40}'

estimate.cost_usd is a low and high figure; estimate.minutes is wall-clock time. Planning itself is free.

Events

GET/v1/swarms/{id}/events

Server-sent events from the start of the swarm until it stops. Every event carries a short summary of the swarm (status, round, spend, agent counts). Reconnect with Last-Event-ID (or ?after=) to pick up where you left off.

curl -N https://swarmcomputers.com/v1/swarms/$SWARM_ID/events \
  -H "Authorization: Bearer $API_KEY"
EventWhen
swarm.createdThe swarm exists and planning has begun.
swarm.plannedThe plan and estimate are ready.
swarm.startedRound 1 begins.
round.startedA review sent out another round.
agent.started · agent.done · agent.failedAn agent began, finished its subtask, or failed.
agent.browser · agent.mail · agent.noteAn agent opened a browser, got an email, or wrote on the board.
budget.warningSpend passed 80% of the budget.
swarm.wrapping_upAgents are writing up; the result is being merged.
swarm.paused · swarm.resumedPaused (by you, the budget or the deadline), or resumed.
swarm.completed · swarm.failed · swarm.cancelledThe swarm stopped. The bill is final.
progressEvery few seconds while active, so spend stays current.
endSent once nothing more will happen, then the stream closes.

Results and files

GET/v1/swarms/{id}/result

The merged result in Markdown, each agent's own report, and the list of files in the run folder. Add ?format=markdown to get only the merged result as text/markdown.

Response
{
  "id": "swm_V1yQf3kK2bD9",
  "status": "completed",
  "partial": false,
  "result": "# Supplier profiles\n\n| Supplier | Pricing | ...",
  "spent_usd": 18.9,
  "agents": [
    { "id": "agt_3f9a1c22b0e4", "title": "Suppliers 1-5", "status": "done", "result": "..." }
  ],
  "files": [
    { "path": "result.md", "bytes": 18234, "at": "2026-11-19T12:21:04Z" },
    { "path": "agents/agt_3f9a1c22b0e4/result.md", "bytes": 4120, "at": "2026-11-19T12:14:50Z" }
  ]
}
GET/v1/swarms/{id}/files/{path}

Every swarm has a shared run folder. Agents save their work there; the merged result is result.md and each agent's report is agents/<id>/result.md. GET /files lists the folder and GET /files/<path> returns one file as text.

GET/v1/swarms/{id}/archive

The whole run folder as one ZIP. Agents' other files sit beside their reports, at agents/<id>/<path>. Text files up to 200 KB are kept; caches and build leftovers such as __pycache__ and node_modules are left out, and the run's activity names any file that was not kept.

The board

Agents in a swarm share a board of short notes, so one agent's discovery reaches the others while they work. You can read it, and post to it: your note reaches every agent the next time it checks.

curl
curl https://swarmcomputers.com/v1/swarms/$SWARM_ID/board \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Skip suppliers outside the EU."}'

Budget and billing

  • One all-inclusive price per agent-minute: $0.10 (provisional) on the standard models. It covers the model, the sandbox, the browser, the inbox and storage.
  • Only time agents spend working is billed. Planning and starting sandboxes are free.
  • The whole budget is held from your credits when the swarm is created. When it ends, you pay what it used and the rest is returned.
  • At 80% of the budget you get a budget.warning event.
  • The last 12% of the budget is kept for writing up and merging. When spend reaches it, agents wrap up and the swarm pauses with a partial result, with a note on roughly how much more would let it finish.
  • The bill never goes above budget_usd.

Pause, resume and cancel

POST/v1/swarms/{id}/pause

Stops every agent where it is. Sandboxes are stopped and kept.

POST/v1/swarms/{id}/resume

Picks up where the agents stopped. A swarm that paused at its budget needs more: send add_budget_usd. You can also set a new deadline_minutes, or null to remove it. A paused swarm can be resumed for 7 days (resume_until); after that its sandboxes are deleted and it completes with the partial result.

curl
curl -X POST https://swarmcomputers.com/v1/swarms/$SWARM_ID/resume \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add_budget_usd": 10}'
POST/v1/swarms/{id}/cancel

Stops everything for good and settles the bill. Works in any state before the swarm ends.

List swarms

GET/v1/swarms

Your 100 most recent swarms, newest first, as {"object": "list", "data": [...]}. Items are the same shape as Get a swarm without result.

What agents can reach

  • Offline (default): agents can compute, write and call the model, and nothing else.
  • Your domains: with allow_domains, agents can reach only domains you have verified.
  • Open web: with "web": true, once enabled for your account. Each agent gets a real browser, and an email inbox where available.