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

# Download swarm results

> Download a JSONL result per member after the swarm reaches a terminal state.

## 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/results" \
  --header "X-API-Key: $BEAD_API_KEY"
```

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

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

## Response

### 200

Terminal results as application/x-ndjson; each line is one selected member attempt.

**index** `integer` *required*

Zero-based member index.

**input** `any` *required*

JSON input assigned to this member.

**state** `string` *required*

Selected attempt state.

**attempt** `integer` *required*

Zero-based selected attempt number.

**sandbox\_id** `string` *required*

Machine used for this attempt.

**exit\_code** `integer | null` *required*

Process exit code; null means no confirmed command exit. May be `null`.

**stdout** `string` *required*

Captured standard output, bounded to 64 KiB.

**stderr** `string` *required*

Captured standard error, bounded to 64 KiB.

**stdout\_truncated** `boolean`

Whether standard output was incomplete.

**stderr\_truncated** `boolean`

Whether standard error was incomplete.

**boot\_ms** `integer | null` *required*

Time from activation to command start in milliseconds. May be `null`.

**queue\_ms** `integer | null` *required*

Time from job creation to activation in milliseconds. May be `null`.

**execution\_ms** `integer | null` *required*

Command execution time in milliseconds. May be `null`.

**duration\_ms** `integer | null` *required*

Time from job creation to attempt completion in milliseconds. May be `null`.

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

Command start time in Unix milliseconds. May be `null`.

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

Attempt completion time in Unix milliseconds. May be `null`.

**error** `string`

Failure message when execution or cleanup failed.

**files** `object`

Bounded artifact collection.

**Properties**

**entries** `object[]` *required*

At most 16 matching regular files and 32 KiB of file bytes.

**Properties**

**path** `string` *required*

Absolute machine path of the selected file.

**encoding** `string`

File bytes are base64 encoded. Allowed values: `"base64"`.

**data** `string`

Base64-encoded file bytes.

**truncated** `boolean`

Whether this file exceeded the remaining byte budget.

**error** `string`

Read failure such as unreadable; present instead of bytes.

**truncated** `boolean` *required*

Whether the file count, traversal, or byte limit stopped collection.

**create\_failure** `object`

Machine creation failure.

**Properties**

**status** `integer` *required*

HTTP status returned by the failed operation.

**response** `object` *required*

Request failure.

**Properties**

**code** `integer` *required*

HTTP status code.

**message** `string` *required*

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**attempt\_failure** `object`

Failure while preparing the attempt.

**Properties**

**status** `integer` *required*

HTTP status returned by the failed operation.

**response** `object` *required*

Request failure.

**Properties**

**code** `integer` *required*

HTTP status code.

**message** `string` *required*

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**execution\_failure** `object`

Command transport or execution failure.

**Properties**

**status** `integer` *required*

HTTP status returned by the failed operation.

**response** `object` *required*

Request failure.

**Properties**

**code** `integer` *required*

HTTP status code.

**message** `string` *required*

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**protocol** `string`

Failed transport protocol when wire evidence is available.

**truncated** `boolean`

Whether failure details exceeded the error byte limit.

**incomplete** `boolean`

Whether the failure response was interrupted.

**cleanup\_failure** `object`

Failure while deleting the machine.

**Properties**

**status** `integer` *required*

HTTP status returned by the failed operation.

**response** `object` *required*

Request failure.

**Properties**

**code** `integer` *required*

HTTP status code.

**message** `string` *required*

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**placement\_failure** `object`

Capacity limit encountered while waiting to start.

**Properties**

**status** `integer` *required*

HTTP status returned by the failed operation.

**response** `object` *required*

Request failure.

**Properties**

**code** `integer` *required*

HTTP status code.

**message** `string` *required*

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**files\_error** `object`

Artifact collection failure; command exit evidence is preserved.

**Properties**

**status** `integer`

HTTP status returned by collection.

**response** `object`

Request failure.

**Properties**

**code** `integer` *required*

HTTP status code.

**message** `string` *required*

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**protocol** `string`

Failed transport protocol when wire evidence is available.

**truncated** `boolean`

Whether failure details exceeded the error byte limit.

**incomplete** `boolean`

Whether the failure response was interrupted.

**stdout\_encoding** `string`

Encoding of captured standard output, such as utf-8 or base64.

**stderr\_encoding** `string`

Encoding of captured standard error, such as utf-8 or base64.

**files\_ms** `integer`

Artifact collection duration in milliseconds, when collected.

**terminal\_reason** `string`

Why an unstarted member terminated, such as job deadline exceeded.

**stdout\_bytes** `integer`

Observed standard output bytes before truncation.

**stderr\_bytes** `integer`

Observed standard error bytes before truncation.

**total\_bytes** `integer`

Combined observed output bytes.

**complete** `boolean`

Whether a terminal command frame confirmed the captured output.

**truncated** `boolean`

Whether the captured evidence is incomplete or byte-limited.

## 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. |
| 409 | The swarm is queued or running; poll status until cleanup reaches a terminal state. |
| 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.