---
title: "Get a single agent"
method: GET
path: "/api/agents/{id}"
tags: ["Agents"]
---

# Get a single agent

`GET /api/agents/{id}`

## Path parameters

- `id` string, required

## Query parameters

- `include` 'tasks'

## Response `200`

Agent with capacity info

- object
  - `id` string, required
  - `name` string, required
  - `isLead` boolean
  - `status` 'idle' | 'busy' | 'offline' | 'waiting_for_credentials', required
  - `description` string
  - `role` string
  - `capabilities` string[]
  - `claudeMd` string
  - `soulMd` string
  - `identityMd` string
  - `setupScript` string
  - `toolsMd` string
  - `heartbeatMd` string
  - `maxTasks` integer
  - `emptyPollCount` integer
  - `lastActivityAt` string, date-time
  - `provider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode'
  - `harnessProvider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'null', nullable
  - `credentialMissing` string[], nullable
  - `credStatus` AgentCredStatus
    - `ready` boolean, required
    - `missing` string[]
    - `satisfiedBy` 'env' | 'file' | 'side-effect-pending' | 'sdk-delegated' | 'null', nullable
    - `hint` string, nullable
    - `liveTest` AgentCredStatusLiveTest, nullable
      - `ok` boolean, required
      - `error` string, nullable
      - `latency_ms` number, required
      - `testedAt` number, required
    - `latestModel` AgentLatestModel, nullable
      - `model` string, required
      - `source` 'task' | 'agent_config' | 'adapter_default' | 'custom', required
      - `taskId` string, nullable
      - `harnessProvider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'null', nullable
      - `reportedAt` number, required
      - `reasoningEffort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `reportedAt` number, required
    - `reportKind` 'boot' | 'post_task'
    - `bedrock` AgentBedrockStatus, nullable
      - `region` string, required
      - `probedAt` number, required
      - `ready` boolean, required
      - `models` object[]
        - `id` string, required
        - `name` string, required
      - `error` string
  - `avatar` object
    - `type` 'lucide', required
    - `icon` string, required
    - `color` string
  - `createdAt` string, date-time, required
  - `lastUpdatedAt` string, date-time, required
  - `tasks` AgentTask[]
    - `id` string, uuid, required
    - `key` string, required — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.
    - `agentId` string, nullable, required
    - `creatorAgentId` string
    - `task` string, required
    - `title` string
    - `status` 'backlog' | 'unassigned' | 'offered' | 'reviewing' | 'pending' | 'in_progress' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'superseded', required
    - `source` 'mcp' | 'slack' | 'api' | 'ui' | 'github' | 'gitlab' | 'agentmail' | 'system' | 'schedule' | 'workflow' | 'linear' | 'jira'
    - `taskType` string
    - `tags` string[]
    - `priority` integer
    - `dependsOn` string[]
    - `offeredTo` string
    - `offeredAt` string, date-time
    - `acceptedAt` string, date-time
    - `rejectionReason` string
    - `createdAt` string, date-time, required
    - `lastUpdatedAt` string, date-time, required
    - `finishedAt` string, date-time
    - `notifiedAt` string, date-time
    - `failureReason` string
    - `output` string
    - `progress` string
    - `slackChannelId` string
    - `slackThreadTs` string
    - `slackTriggerMessageTs` string
    - `slackUserId` string
    - `slackReplySent` boolean
    - `slackProgressMessageTs` string
    - `slackTreeRootMessageTs` string
    - `vcsProvider` 'github' | 'gitlab'
    - `vcsRepo` string
    - `vcsEventType` string
    - `vcsNumber` integer
    - `vcsCommentId` integer
    - `vcsAuthor` string
    - `vcsUrl` string
    - `vcsInstallationId` integer
    - `vcsNodeId` string
    - `agentmailInboxId` string
    - `agentmailMessageId` string
    - `agentmailThreadId` string
    - `mentionMessageId` string
    - `mentionChannelId` string
    - `dir` string
    - `parentTaskId` string
    - `claudeSessionId` string
    - `model` string
    - `modelTier` 'smol' | 'regular' | 'smart' | 'ultra'
    - `effort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `scheduleId` string
    - `workflowRunId` string, uuid, nullable
    - `workflowRunStepId` string, uuid, nullable
    - `contextKey` string
    - `outputSchema` object
    - `followUpConfig` FollowUpConfig
      - `disabled` boolean
      - `onCompleted` string
      - `onFailed` string
    - `wasPaused` boolean
    - `compactionCount` integer
    - `peakContextPercent` number
    - `peakContextTokens` integer
    - `contextWindowSize` integer
    - `credentialKeySuffix` string
    - `credentialKeyType` string
    - `requestedByUserId` string
    - `swarmVersion` string
    - `provider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode'
    - `providerMeta` object
    - `harnessVariant` string
    - `harnessVariantMeta` object
    - `totalCostUsd` number
    - `routingAffinity` RoutingAffinity
      - `sourceAgentId` string
      - `role` string
      - `harnessProvider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode'
      - `capabilities` string[]
  - `capacity` object, required
    - `current` integer, required
    - `max` integer, required
    - `available` integer, required

## Other responses

- `404` — Agent not found

---

[API](https://skmtc.net/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.net/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/versions/0375890be8c4/schema)