Start a swarm

POST

swarms

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

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,
)

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,
});

{
  "id": "<string>",
  "state": "<string>",
  "counts": {
    "pending": 123,
    "running": 123,
    "succeeded": 123,
    "failed": 123,
    "cancelled": 123
  },
  "created_at_ms": 123,
  "completed_at_ms": {},
  "results_url": "<string>",
  "retention_seconds": 123
}

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

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.

string

required

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

string

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

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.

integer

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

any[]

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

integer

default:300

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

integer

default:8

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

integer

default:0

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

string[]

default:[]

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

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

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,
)

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.

string

required

Swarm UUID.

string

required

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

object

required

Member counts grouped by current result.

Show Properties

integer

required

Members waiting to start.

integer

required

Members executing or cleaning up.

integer

required

Members with a successful attempt.

integer

required

Members whose attempts failed.

integer

required

Members cancelled before success.

integer

required

Creation time in Unix milliseconds.

integer | null

required

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

string

required

Relative URL for the terminal JSONL results download.

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.

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

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,
)

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,
});

{
  "id": "<string>",
  "state": "<string>",
  "counts": {
    "pending": 123,
    "running": 123,
    "succeeded": 123,
    "failed": 123,
    "cancelled": 123
  },
  "created_at_ms": 123,
  "completed_at_ms": {},
  "results_url": "<string>",
  "retention_seconds": 123
}

Start here

Endpoints

Start a swarm

Authentication

Parameters

Request body

Response

202

Errors

​Authentication

​Parameters

​Request body

​Response

​202

​Errors

Authentication

Parameters

Request body

Response

202

Errors