Skip to main content
GET
/
agents
List Agents
curl --request GET \
  --url https://api.example.com/agents
{
  "success": true,
  "data": [
    {
      "data[].agentId": "<string>",
      "data[].name": "<string>",
      "data[].status": "<string>",
      "data[].bio": "<string>",
      "data[].enabled": true,
      "data[].createdAt": 123,
      "data[].updatedAt": 123
    }
  ]
}

Endpoint

GET /agents
Retrieves a list of all agents configured in your elizaOS deployment, including their status, configuration, and metadata.

Request

Query Parameters

status
string
Filter agents by status: active or inactive
offset
number
default:"0"
Number of agents to skip for pagination
limit
number
default:"50"
Maximum number of agents to return

Headers

Authorization
string
Bearer token for authentication (if required)

Response

success
boolean
required
Indicates if the request was successful
data
array
required
Array of agent objects
data[].agentId
string
required
Unique identifier for the agent (UUID)
data[].name
string
required
Name of the agent’s character
data[].status
string
required
Current status: active or inactive
data[].bio
string
Short biography or description of the agent
data[].enabled
boolean
Whether the agent is enabled
data[].createdAt
number
Unix timestamp when the agent was created
data[].updatedAt
number
Unix timestamp when the agent was last updated

Examples

Basic Request

curl -X GET http://localhost:3000/agents \
  -H "Content-Type: application/json"

With Authentication

curl -X GET http://localhost:3000/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Filter by Status

curl -X GET "http://localhost:3000/agents?status=active" \
  -H "Content-Type: application/json"

With Pagination

curl -X GET "http://localhost:3000/agents?offset=0&limit=10" \
  -H "Content-Type: application/json"

Response Example

{
  "success": true,
  "data": [
    {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice",
      "status": "active",
      "bio": "A helpful AI assistant specializing in customer support",
      "enabled": true,
      "createdAt": 1709510400000,
      "updatedAt": 1709596800000
    },
    {
      "agentId": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Bob",
      "status": "inactive",
      "bio": "A technical expert focused on software development",
      "enabled": false,
      "createdAt": 1709424000000,
      "updatedAt": 1709510400000
    }
  ]
}

Code Examples

JavaScript/Node.js

const response = await fetch('http://localhost:3000/agents', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const { success, data } = await response.json();

if (success) {
  console.log(`Found ${data.length} agents`);
  data.forEach(agent => {
    console.log(`- ${agent.name} (${agent.status})`);
  });
}

Python

import requests

response = requests.get('http://localhost:3000/agents')
data = response.json()

if data['success']:
    print(f"Found {len(data['data'])} agents")
    for agent in data['data']:
        print(f"- {agent['name']} ({agent['status']})")

TypeScript

interface Agent {
  agentId: string;
  name: string;
  status: 'active' | 'inactive';
  bio?: string;
  enabled?: boolean;
  createdAt?: number;
  updatedAt?: number;
}

interface ListAgentsResponse {
  success: boolean;
  data: Agent[];
}

const response = await fetch('http://localhost:3000/agents');
const { success, data }: ListAgentsResponse = await response.json();

if (success) {
  console.log(`Found ${data.length} agents`);
}

Error Responses

503 Service Unavailable

{
  "success": false,
  "error": "Agent service not available"
}

500 Internal Server Error

{
  "success": false,
  "error": "Failed to retrieve agents"
}

Next Steps

Create Agent

Create a new agent

Get Agent

Get details about a specific agent

Start Agent

Start an agent’s runtime

Build docs developers (and LLMs) love