Skip to content
Ishvana Ishvana Docs

Get Swarm

GET
/api/agents/swarm/{swarm_id}

Get detailed information about a specific swarm

Retrieves comprehensive details about a swarm by ID, checking both active swarms and historical swarm data. Returns full swarm details including current status, execution progress, agent count, and task information.

@param swarm_id: Unique swarm identifier @param swarm_engine: Injected swarm execution engine @returns SwarmResponse with complete swarm details including status and progress @raises HTTPException: If swarm not found (404) or retrieval fails (500)

Search Order:

  1. Check active swarms dictionary first
  2. Fall back to swarm history if not active
  3. Return 404 if not found in either location

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
swarm_id
required
Swarm Id
string

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

SwarmResponse

Response model for swarm operations.

Represents the current state and metadata of a multi-agent swarm, including execution status, progress tracking, and swarm composition details. Used for swarm creation responses, status queries, and monitoring updates.

Fields:

  • swarm_id: Unique swarm identifier
  • status: Current swarm status (pending, active, completed, failed, cancelled)
  • swarm_type: Type of swarm
  • created_at: Creation timestamp
  • task_description: Task description
  • agent_count: Number of agents in swarm
  • progress: Task completion progress (0.0-1.0)

Status Values:

  • pending: Swarm created but not yet started
  • active: Swarm currently executing
  • completed: Swarm finished successfully
  • failed: Swarm failed with error
  • cancelled: Swarm cancelled by user or system

Progress Range: 0.0 (0%) to 1.0 (100%), calculated based on completed sub-tasks

Usage: Returned from swarm creation, status queries, and list operations.

JSON Example:

{
  "swarmId": "swarm_abc123",
  "status": "active",
  "swarmType": "code_analysis",
  "createdAt": "2024-12-20T10:30:00Z",
  "taskDescription": "Analyze Python codebase for type safety issues",
  "agentCount": 5,
  "progress": 0.65
}

Integration:

  • SwarmExecutionEngine: Updates status and progress during execution
  • Monitoring Dashboard: Displays swarm state in real-time
  • Analytics System: Tracks swarm performance and completion rates
object
swarmId
required
Swarmid

Unique swarm identifier

string
status
required
Status

Current swarm status

string
swarmType
required
Swarmtype

Type of swarm

string
createdAt
required
Createdat

Creation timestamp

string
taskDescription
required
Taskdescription

Task description

string
agentCount
required
Agentcount

Number of agents in swarm

integer
progress
required
Progress

Task completion progress (0.0-1.0)

number

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object