> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a swarm

> Run one command across many machines.

Start a swarm that runs one command across many machines.

## Authentication

Send your scoped bearer token in the `Authorization: Bearer <BEAD_TOKEN>` header, or send your API key in `X-API-Key`.

## Parameters

**Idempotency-Key** `string`

Caller-generated durable retry key: lowercase ASCII letters, digits, and hyphens only. Reuse the same key and body after a connection failure. Minimum length: `1`. Maximum length: `240`.

## Request body

The JSON body is required.

**template** `string` *required*

Published template or ready snapshot ID; choose a template returned by the catalog.

**size** `string`

Machine size; omission uses the default size. Allowed values: `"xs"`, `"small"`, `"medium"`, `"large"`, `"xlarge"`.

**command** `string` *required*

Shell command run with /bin/sh -c in /root. Inputs arrive in BEAD\_SWARM\_INPUT; index and attempt arrive in BEAD\_SWARM\_INDEX and BEAD\_SWARM\_ATTEMPT. Limited to 16384 bytes with no NUL. Minimum length: `1`. Maximum length: `16384`.

**count** `integer`

Number of members with null input; supply count or inputs, never both. Minimum: `1`. Maximum: `256`.

**inputs** `any[]`

One JSON value per member, at most 16384 serialized bytes each. Supply inputs or count, never both.

**time\_limit\_seconds** `integer` (default: 300)

Execution time limit for each member in seconds. Minimum: `1`. Maximum: `3600`.

**concurrency** `integer` (default: 8)

Maximum attempts executing concurrently. Minimum: `1`. Maximum: `256`.

**retries** `integer` (default: 0)

Extra attempts allowed per member. Members × (retries + 1) must not exceed 256. Minimum: `0`. Maximum: `3`.

**output\_files** `string[]`

Output file globs, at most 16 strings of at most 1024 bytes each. Collection retains at most 16 files and 32 KiB total.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl --request POST \
  --url "https://api.bead.run/swarms" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "template": "python",
  "size": "small",
  "command": "python3 -c 'import os; print(os.environ[\"BEAD_SWARM_INPUT\"])'",
  "inputs": [
    {
      "seed": 1
    },
    {
      "seed": 2
    }
  ],
  "concurrency": 2,
  "time_limit_seconds": 300,
  "retries": 0
}
JSON
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
from beadrun import Swarm

swarm = Swarm.run(
    template="python", size="small",
    cmd='python3 -c \'import os; print(os.environ["BEAD_SWARM_INPUT"])\'',
    inputs=[{"seed": 1}, {"seed": 2}], concurrency=2, timeout=300,
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
import { Swarm } from "@beadrun/sdk";

const swarm = await Swarm.run({
  template: "python", size: "small",
  cmd: `python3 -c 'import os; print(os.environ["BEAD_SWARM_INPUT"])'`,
  inputs: [{ seed: 1 }, { seed: 2 }], concurrency: 2, timeout: 300,
});
```

## Response

### 202

Swarm state and member counts.

**id** `string` *required*

Swarm UUID.

**state** `string` *required*

Job state after scheduling and cleanup. Allowed values: `"queued"`, `"running"`, `"completed"`, `"failed"`, `"cancelled"`.

**counts** `object` *required*

Member counts grouped by current result.

**Properties**

**pending** `integer` *required*

Members waiting to start.

**running** `integer` *required*

Members executing or cleaning up.

**succeeded** `integer` *required*

Members with a successful attempt.

**failed** `integer` *required*

Members whose attempts failed.

**cancelled** `integer` *required*

Members cancelled before success.

**created\_at\_ms** `integer` *required*

Creation time in Unix milliseconds.

**completed\_at\_ms** `integer | null` *required*

Completion time in Unix milliseconds; null while active. May be `null`.

**results\_url** `string` *required*

Relative URL for the terminal JSONL results download.

**retention\_seconds** `integer` *required*

Seconds results remain available after completion. Allowed values: `86400`.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid request values, unsupported bounds, or malformed JSON. |
| 401 | Authentication credential is missing or rejected. |
| 402 | Insufficient prepaid credit (`insufficient_credit`) to fund the requested machine attempts. |
| 403 | The credential lacks the required scope. |
| 409 | Request key reused with a different body (`idempotency_request_mismatch`), or resource ownership/state conflicts. |
| 413 | Request body exceeds the route limit. |
| 429 | Request or resource admission limit exceeded (`admission_limit`; trial capacity can return `free_capacity_full`). Follow limit.next\_action and Retry-After when present. |
| 503 | Service or persistence is temporarily unavailable. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.