/v1/agents/list) allows you to retrieve all agent configurations you have previously created through the Swarms API. This endpoint provides a comprehensive view of your agent inventory, including their names, descriptions, system prompts, model configurations, and other settings.
Every agent_config you send to /v1/agent/completions is logged to your account. The list is built from those logs:
- Only configs that have an
agent_nameare listed, one entry per name, holding the most recent config sent under that name. - Configs sent with any API key on your account are included.
- Agents inside swarm, graph workflow and other multi-agent requests are not included, and neither are configs sent through
/v1/agent/batch/completions. /v1/chat/completionsrequests are logged the same way and appear under the nameopenai-compat-agent.- Each entry gets a
last_usedtimestamp, and entries are sorted bylast_used, most recent first.
- View all your agents: Retrieve the agent configurations used across your account
- Manage your agent library: Keep track of different agent configurations you’ve created for various use cases
- Reuse agent configurations: Access previously created agent settings to reuse them in new tasks or workflows
- Audit and organize: Review your agent inventory to understand what agents you have available and their configurations
Endpoint Information
- URL:
/v1/agents/list - Method:
GET - Authentication: Required (
x-api-keyheader) - Rate Limiting: Subject to tier-based rate limits
Response Format
The endpoint returns a JSON object containing:success: A boolean indicating whether the agent list was retrieved successfullycount: An integer representing the total number of unique agent configurations in your accountagents: An array of agent definition objects, each containing the complete configuration details of agents you’ve previously created, including:- Agent name and description
- System prompts
- Model configurations (model name, temperature, max_tokens, etc.)
- Tool configurations
- MCP integrations
- Other agent-specific settings
last_used: when a request last used that agent name
timestamp: An ISO 8601 UTC timestamp indicating when the list was generated
Use Cases
- Agent Discovery: Quickly see what agents you have available without needing to remember specific configuration details
- Configuration Reuse: Retrieve agent configurations to reuse in new API calls or workflows
- Inventory Management: Keep track of your agent library and identify agents that may need updates or cleanup
- Multi-Agent Workflows: List available agents to select and combine them in complex multi-agent architectures
- Development and Testing: Review agent configurations during development to ensure consistency across different environments
- Python
- JavaScript
- cURL
Responses include a
count of agents and an array of agent definitions you previously created.