> ## 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.

# Get swarm progress

> Read swarm state, member counts, and the results download URL.

## Authentication

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

## Parameters

**id** `string` *required*

UUID of the swarm job. Format: `uuid`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl --request GET \
  --url "https://api.bead.run/swarms/$SWARM_ID" \
  --header "X-API-Key: $BEAD_API_KEY"
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
# swarm is returned by Swarm.run.
print(swarm.status())
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
// swarm is returned by Swarm.run.
console.log(await swarm.status());
```

## Response

### 200

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 resource UUID or request parameters. |
| 401 | Authentication credential is missing or rejected. |
| 403 | The credential lacks the required scope. |
| 404 | The requested resource does not exist or is outside your organization. |
| 429 | Request or resource admission limit exceeded (`admission_limit`). 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.