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.
How a swarm runs
- 1
Plan
The orchestrator splits the task into independent subtasks, one per agent, and estimates agents, time and cost. Status
planning. - 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
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
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
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
}'import os, requests
swarm = requests.post(
"https://swarmcomputers.com/v1/swarms",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={
"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,
},
).json()
print(swarm["id"], swarm["status"])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,largeormax. Sets how wide and how long the swarm may go. Defaultsmall. 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_approvaluntil you start it. - modelstring
- The model the agents run on. Defaults to
deepseek-v4.1-flash;deepseek-v4.1-flash-uncensoredis 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_scanruns the security preset againsttarget.- 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.
| size | Agents at once | Default budget | Rounds | Per agent, per subtask | Typical time |
|---|---|---|---|---|---|
small | Up to 5 | $10 | 2 | 20 min | 10–20 min |
medium | Up to 20 | $50 | 3 | 30 min | 20–40 min |
large | Up to 50 | $150 | 4 | 45 min | 30–60 min |
max | Up to 100 | Required | 8 | 60 min | hours |
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.
"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
{
"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
| status | Meaning |
|---|---|
planning | Splitting the task and estimating. Nothing is billed yet. |
awaiting_approval | Planned with plan_only. Waiting for /start. |
running | Agents are working. |
wrapping_up | Agents are writing up and the result is being merged. |
paused | Stopped with sandboxes kept. See pause_reason: budget, deadline or requested. |
completed | Done. result is set. partial: true if it was merged before all the work finished. |
failed | Could not be planned or run. status_note says why. |
cancelled | Stopped 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:
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
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"id: 4
event: swarm.planned
data: {"at":"2026-11-19T11:40:12Z","message":"8 agents, about 20–35 minutes, $12.80–$22.40. ...","swarm":{"status":"planning","round":0,"spent_usd":0,"budget_usd":25,"agents":{"total":0,"working":0,"done":0,"failed":0}}}
event: progress
data: {"swarm":{"status":"running","round":1,"spent_usd":1.2,"budget_usd":25,"agents":{"total":8,"working":8,"done":0,"failed":0}}}| Event | When |
|---|---|
swarm.created | The swarm exists and planning has begun. |
swarm.planned | The plan and estimate are ready. |
swarm.started | Round 1 begins. |
round.started | A review sent out another round. |
agent.started · agent.done · agent.failed | An agent began, finished its subtask, or failed. |
agent.browser · agent.mail · agent.note | An agent opened a browser, got an email, or wrote on the board. |
budget.warning | Spend passed 80% of the budget. |
swarm.wrapping_up | Agents are writing up; the result is being merged. |
swarm.paused · swarm.resumed | Paused (by you, the budget or the deadline), or resumed. |
swarm.completed · swarm.failed · swarm.cancelled | The swarm stopped. The bill is final. |
progress | Every few seconds while active, so spend stays current. |
end | Sent once nothing more will happen, then the stream closes. |
Results and files
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.
{
"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" }
]
}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.
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 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.warningevent. - 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
Stops every agent where it is. Sandboxes are stopped and kept.
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 -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}'Stops everything for good and settles the bill. Works in any state before the swarm ends.
List 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.