# Read a swarm

Settings, plan, conversation, children, questions waiting on the member, and recent activity. Pass nextMessageCursor as beforeId and beforeAt for older messages, or messageLimit=0 for a compact read without the conversation. Answer a pending question with answerThreadQuestion on its threadId. Requires a member's session or personal API key; service account keys receive 403 user_identity_required.

`GET /api/swarms/{id}`

Required permission: `thread:read`.

## Parameters

| Name | In | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes | — |

| `beforeId` | query | `string` | No | — |

| `beforeAt` | query | `string<date-time>` | No | — |

| `messageLimit` | query | `integer` | No | — |

## Example request

```bash
curl --request GET \
  --url https://api.hoplite.sh/api/swarms/id \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

## 200 response

Successful response

Content type: `application/json`. Response type: `object`.

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| `children` | `object[]` | Yes | — | — |
| `children.id` | `string` | Yes | — | — |
| `children.title` | `string` | Yes | — | — |
| `children.status` | `string` | Yes | — | — |
| `children.projectId` | `string \| null` | Yes | — | — |
| `children.projectName` | `string \| null` | Yes | — | — |
| `children.latestPullRequest` | `object \| null` | Yes | — | — |
| `children.latestPullRequest.Option 1` | `object` | No | — | — |
| `children.latestPullRequest.Option 1.number` | `integer` | Yes | max 9007199254740991 | — |
| `children.latestPullRequest.Option 1.url` | `string` | Yes | — | — |
| `children.latestPullRequest.Option 1.state` | `string` | Yes | — | — |
| `children.latestPullRequest.Option 2` | `null` | No | — | — |
| `children.archivedAt` | `string \| null` | Yes | — | — |
| `children.updatedAt` | `string` | Yes | — | — |
| `hasMoreChildren` | `boolean` | Yes | — | — |
| `nextChildCursor` | `object \| null` | Yes | — | — |
| `nextChildCursor.Option 1` | `object` | No | — | — |
| `nextChildCursor.Option 1.beforeId` | `string` | Yes | — | — |
| `nextChildCursor.Option 1.beforeAt` | `string` | Yes | — | — |
| `nextChildCursor.Option 2` | `null` | No | — | — |
| `swarm` | `object` | Yes | — | — |
| `swarm.avatarArtifactId` | `string \| null` | No | — | — |
| `swarm.avatarArtifactId.Option 1` | `string` | No | min length 1, max length 200 | — |
| `swarm.avatarArtifactId.Option 2` | `null` | No | — | — |
| `swarm.name` | `string` | Yes | min length 1, max length 120 | — |
| `swarm.emoji` | `string` | Yes | min length 1, max length 80 | — |
| `swarm.purpose` | `string` | Yes | max length 16000 | — |
| `swarm.model` | `string` | Yes | min length 1, max length 200 | — |
| `swarm.reasoning` | `string \| null` | No | — | — |
| `swarm.reasoning.Option 1` | `string` | No | off · none · minimal · low · medium · high · xhigh · max | — |
| `swarm.reasoning.Option 2` | `null` | No | — | — |
| `swarm.speed` | `string \| null` | No | — | — |
| `swarm.speed.Option 1` | `string` | No | standard · fast | — |
| `swarm.speed.Option 2` | `null` | No | — | — |
| `swarm.shared` | `boolean` | Yes | — | — |
| `swarm.maxActiveChildren` | `integer` | No | min 1, max 50 | — |
| `swarm.homeProjectId` | `string \| null` | No | — | — |
| `swarm.homeProjectId.Option 1` | `string` | No | min length 1, max length 200 | — |
| `swarm.homeProjectId.Option 2` | `null` | No | — | — |
| `swarm.doneCriteria` | `string[]` | No | max 10 items | — |
| `swarm.doneCriteria.[item]` | `string` | No | min length 1, max length 300 | — |
| `swarm.goalMode` | `boolean` | No | — | — |
| `swarm.id` | `string` | Yes | — | — |
| `swarm.threadId` | `string` | Yes | — | — |
| `swarm.ownerUserId` | `string` | Yes | — | — |
| `swarm.ownerName` | `string` | Yes | — | — |
| `swarm.archivedAt` | `string \| null` | Yes | — | — |
| `swarm.createdAt` | `string` | Yes | — | — |
| `swarm.updatedAt` | `string` | Yes | — | — |
| `swarm.status` | `string` | Yes | — | — |
| `swarm.version` | `number` | Yes | — | — |
| `swarm.runningChildCount` | `integer` | No | min 0, max 9007199254740991 | — |
| `swarm.needsInputChildCount` | `integer` | No | min 0, max 9007199254740991 | — |
| `plan` | `object` | Yes | — | — |
| `plan.version` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `plan.items` | `object[]` | Yes | max 100 items | — |
| `plan.items.id` | `string<uuid>` | Yes | pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$ | — |
| `plan.items.title` | `string` | Yes | min length 1, max length 240 | — |
| `plan.items.description` | `string` | Yes | max length 4000 | — |
| `plan.items.status` | `string` | Yes | pending · in_progress · blocked · completed · cancelled | — |
| `plan.items.objective` | `object` | No | — | — |
| `plan.items.objective.instructionMessageId` | `string<starts_with>` | Yes | max length 200, pattern ^swarm:.* | — |
| `plan.items.objective.mode` | `string` | Yes | continuous · bounded | — |
| `plan.items.objective.acceptanceCriteria` | `string` | Yes | min length 1, max length 2000 | — |
| `plan.items.objective.metric` | `object` | No | — | — |
| `plan.items.objective.metric.name` | `string` | Yes | min length 1, max length 200 | — |
| `plan.items.objective.metric.unit` | `string` | Yes | min length 1, max length 100 | — |
| `plan.items.objective.metric.comparison` | `string` | Yes | lt · lte · gt · gte · eq | — |
| `plan.items.objective.metric.target` | `number` | Yes | — | — |
| `plan.items.evaluatorThreadId` | `string` | No | min length 1, max length 200 | — |
| `plan.items.evaluation` | `object` | No | — | — |
| `plan.items.evaluation.runId` | `string` | Yes | min length 1, max length 200 | — |
| `plan.items.evaluation.messageId` | `string` | Yes | min length 1, max length 200 | — |
| `plan.items.stopInstructionMessageId` | `string<starts_with>` | No | max length 200, pattern ^swarm:.* | — |
| `plan.items.blocker` | `string` | No | min length 1, max length 2000 | — |
| `plan.items.checkpoint` | `object` | No | — | — |
| `plan.items.checkpoint.iteration` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `plan.items.checkpoint.acceptanceCriteria` | `string` | Yes | min length 1, max length 2000 | — |
| `plan.items.checkpoint.latestEvidence` | `string` | Yes | max length 2000 | — |
| `plan.items.checkpoint.bestResult` | `string` | Yes | max length 2000 | — |
| `plan.items.checkpoint.nextAction` | `string` | Yes | max length 2000 | — |
| `plan.items.checkpoint.attempts` | `object[]` | No | max 10 items | — |
| `plan.items.checkpoint.attempts.iteration` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `plan.items.checkpoint.attempts.candidate` | `string` | Yes | min length 1, max length 500 | — |
| `plan.items.checkpoint.attempts.hypothesis` | `string` | Yes | min length 1, max length 1000 | — |
| `plan.items.checkpoint.attempts.outcome` | `string` | Yes | improved · regressed · inconclusive | — |
| `plan.items.checkpoint.attempts.evidence` | `string` | Yes | min length 1, max length 2000 | — |
| `plan.items.checkpoint.attempts.lesson` | `string` | Yes | min length 1, max length 1000 | — |
| `plan.items.wakeReminderIds` | `string[]` | No | max 100 items | — |
| `plan.items.wakeReminderIds.[item]` | `string` | No | min length 1, max length 200 | — |
| `plan.items.queuedFollowUps` | `object[]` | No | max 100 items | — |
| `plan.items.queuedFollowUps.threadId` | `string` | Yes | min length 1, max length 200 | — |
| `plan.items.queuedFollowUps.messageId` | `string` | Yes | min length 1, max length 200 | — |
| `plan.items.childThreadIds` | `string[]` | Yes | max 100 items | — |
| `plan.items.childThreadIds.[item]` | `string` | No | min length 1, max length 200 | — |
| `messages` | `object[]` | Yes | — | — |
| `messages.id` | `string` | Yes | — | — |
| `messages.role` | `string` | Yes | user · assistant | — |
| `messages.content` | `string` | Yes | — | — |
| `messages.createdAt` | `string` | Yes | — | — |
| `messages.authorUserId` | `string \| null` | Yes | — | — |
| `messages.authorName` | `string \| null` | Yes | — | — |
| `messages.attachments` | `object[]` | Yes | — | — |
| `messages.attachments.artifactId` | `string` | Yes | min length 1 | — |
| `messages.attachments.contentType` | `string` | Yes | min length 1 | — |
| `messages.attachments.height` | `integer` | No | max 9007199254740991 | — |
| `messages.attachments.modelInput` | `object` | No | — | — |
| `messages.attachments.modelInput.videoFrames` | `object[]` | No | max 6 items | — |
| `messages.attachments.modelInput.videoFrames.timestampMs` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `messages.attachments.modelInput.visionMediaType` | `string` | No | image/jpeg · image/png | — |
| `messages.attachments.name` | `string` | No | — | — |
| `messages.attachments.routeId` | `string` | No | pattern ^[a-f0-9]{32}$ | — |
| `messages.attachments.width` | `integer` | No | max 9007199254740991 | — |
| `messages.notifyKind` | `string` | No | needs_you · milestone · answer | — |
| `hasMoreMessages` | `boolean` | Yes | — | — |
| `nextMessageCursor` | `object \| null` | Yes | — | — |
| `nextMessageCursor.Option 1` | `object` | No | — | — |
| `nextMessageCursor.Option 1.beforeId` | `string` | Yes | — | — |
| `nextMessageCursor.Option 1.beforeAt` | `string` | Yes | — | — |
| `nextMessageCursor.Option 2` | `null` | No | — | — |
| `activeRunId` | `string \| null` | Yes | — | — |
| `activeRunIsWake` | `boolean` | No | — | — |
| `queuedMessageCount` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `queuedMessages` | `object[]` | No | — | — |
| `queuedMessages.id` | `string` | Yes | — | — |
| `queuedMessages.content` | `string` | Yes | — | — |
| `queuedMessages.createdAt` | `string` | Yes | — | — |
| `queuedMessages.authorUserId` | `string` | Yes | — | — |
| `queuedMessages.authorName` | `string \| null` | Yes | — | — |
| `queuedMessages.queuedAfterRunId` | `string` | Yes | — | — |
| `queuedMessages.attachments` | `object[]` | No | — | — |
| `queuedMessages.attachments.artifactId` | `string` | Yes | min length 1 | — |
| `queuedMessages.attachments.contentType` | `string` | Yes | min length 1 | — |
| `queuedMessages.attachments.height` | `integer` | No | max 9007199254740991 | — |
| `queuedMessages.attachments.modelInput` | `object` | No | — | — |
| `queuedMessages.attachments.modelInput.videoFrames` | `object[]` | No | max 6 items | — |
| `queuedMessages.attachments.modelInput.videoFrames.timestampMs` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `queuedMessages.attachments.modelInput.visionMediaType` | `string` | No | image/jpeg · image/png | — |
| `queuedMessages.attachments.name` | `string` | No | — | — |
| `queuedMessages.attachments.routeId` | `string` | No | pattern ^[a-f0-9]{32}$ | — |
| `queuedMessages.attachments.width` | `integer` | No | max 9007199254740991 | — |
| `totalChildCount` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `latestChildUpdatedAt` | `string \| null` | Yes | — | — |
| `pendingQuestions` | `object[]` | Yes | — | — |
| `pendingQuestions.threadId` | `string` | Yes | — | — |
| `pendingQuestions.threadTitle` | `string` | Yes | — | — |
| `pendingQuestions.questionId` | `string` | Yes | — | — |
| `pendingQuestions.runId` | `string \| null` | Yes | — | — |
| `pendingQuestions.request` | `object` | Yes | — | — |
| `pendingQuestions.request.questions` | `object[]` | Yes | max 4 items, min 1 items | — |
| `pendingQuestions.request.questions.header` | `string` | Yes | min length 1, max length 12 | — |
| `pendingQuestions.request.questions.inputType` | `string` | No | text · textarea · number · date · email · url · boolean | — |
| `pendingQuestions.request.questions.multiSelect` | `boolean` | Yes | — | — |
| `pendingQuestions.request.questions.options` | `object[]` | Yes | max 4 items, min 0 items | — |
| `pendingQuestions.request.questions.options.description` | `string` | Yes | max length 2000 | — |
| `pendingQuestions.request.questions.options.label` | `string` | Yes | min length 1, max length 128 | — |
| `pendingQuestions.request.questions.options.preview` | `string` | No | max length 100000 | — |
| `pendingQuestions.request.questions.question` | `string` | Yes | min length 1, max length 10000 | — |
| `hasMorePendingQuestions` | `boolean` | Yes | — | — |
| `runningChildCount` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `needsInputChildCount` | `integer` | Yes | min 0, max 9007199254740991 | — |
| `activity` | `object[]` | Yes | — | — |
| `activity.id` | `string` | Yes | — | — |
| `activity.archivedChild` | `object` | No | — | — |
| `activity.archivedChild.id` | `string` | Yes | — | — |
| `activity.archivedChild.title` | `string` | Yes | — | — |
| `activity.runId` | `string \| null` | Yes | — | — |
| `activity.title` | `string` | Yes | — | — |
| `activity.status` | `string` | Yes | running · completed · failed | — |
| `activity.createdAt` | `string` | Yes | — | — |
| `activity.completedAt` | `string \| null` | Yes | — | — |
| `hasMoreActivity` | `boolean` | Yes | — | — |
| `latestRunFailure` | `object \| null` | Yes | — | — |
| `latestRunFailure.Option 1` | `object` | No | — | — |
| `latestRunFailure.Option 1.runId` | `string` | Yes | — | — |
| `latestRunFailure.Option 1.code` | `string` | Yes | — | — |
| `latestRunFailure.Option 1.message` | `string` | Yes | — | — |
| `latestRunFailure.Option 1.canRetry` | `boolean` | No | — | — |
| `latestRunFailure.Option 2` | `null` | No | — | — |
| `ok` | `boolean` | Yes | constant true | — |

```json

```

## Response headers

| Header | Type | Statuses | Description |

| --- | --- | --- | --- |

| `RateLimit` | `string` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Current ingress policy, remaining requests, and seconds until reset, for example `"ingress";r=599;t=60`. |

| `RateLimit-Policy` | `string` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Ingress quota and window, for example `"ingress";q=600;qu="requests";w=60`. |

| `X-RateLimit-Limit` | `integer` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Maximum requests allowed in the current rolling window. |

| `X-RateLimit-Remaining` | `integer` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Requests remaining in the current rolling window. |

| `X-RateLimit-Reset` | `integer` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Unix timestamp when the current rolling window resets. |

| `x-request-id` | `string` | `200`, `400`, `401`, `402`, `403`, `404`, `409`, `410`, `429`, `500`, `501`, `503` | Request correlation ID. |

| `Retry-After` | `integer` | `429`, `503` | Seconds until another request should be attempted. |

| `X-Retry-After` | `integer` | `429`, `503` | Legacy retry delay in seconds. |

## Status codes

- `200` — Successful response

- `400` — Invalid request. Validation responses include field paths.

- `401` — The API key is missing, invalid, or lacks the operation's permission.

- `402` — The organization does not have access to the requested product capability.

- `403` — The key's current user no longer has the required organization membership or role.

- `404` — The resource is not available in the authenticated scope.

- `409` — The request conflicts with a retry receipt or current resource state.

- `410` — The event cursor has expired; capture a fresh head and resource snapshot.

- `429` — The API-key rate limit has been exceeded.

- `500` — The API encountered an unexpected failure.

- `501` — The deployment has not configured the requested capability.

- `503` — A required API dependency, including the rate limiter, is unavailable.