List Agents

Retrieves a paginated list of agents with optional filtering and sorting.

Endpoint

GET https://api.ayra.ai/v1/agents

Authentication

Requires API key with agents:read permission.

Query Parameters

All parameters are optional.

Pagination:

Filtering:

Sorting:

Request Examples

Basic List Request:

curl https://api.ayra.ai/v1/agents \
  -H "Authorization: Bearer sk_live_abc123xyz789"

Filtered and Sorted:

curl "https://api.ayra.ai/v1/agents?status=active&voice_platform=vapi&sort_by=name&sort_order=asc" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

Search by Name:

curl "https://api.ayra.ai/v1/agents?search=support" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

Paginated Request:

curl "https://api.ayra.ai/v1/agents?page=2&per_page=50" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

JavaScript Example:

async function listAgents(options = {}) {
  const params = new URLSearchParams({
    page: options.page || 1,
    per_page: options.per_page || 25,
    ...(options.status && { status: options.status }),
    ...(options.voice_platform && { voice_platform: options.voice_platform }),
    ...(options.search && { search: options.search }),
    ...(options.sort_by && { sort_by: options.sort_by }),
    ...(options.sort_order && { sort_order: options.sort_order })
  });

  try {
    const response = await axios.get(
      `https://api.ayra.ai/v1/agents?${params}`,
      {
        headers: {
          'Authorization': 'Bearer sk_live_abc123xyz789'
        }
      }
    );
    
    console.log(`Found ${response.data.meta.total} agents`);
    return response.data;
  } catch (error) {
    console.error('Error listing agents:', error.response.data);
    throw error;
  }
}

// Example: List active agents sorted by name
listAgents({
  status: 'active',
  sort_by: 'name',
  sort_order: 'asc'
});

Python Example:

def list_agents(page=1, per_page=25, **filters):
    url = 'https://api.ayra.ai/v1/agents'
    headers = {
        'Authorization': 'Bearer sk_live_abc123xyz789'
    }
    
    params = {
        'page': page,
        'per_page': per_page,
        **filters
    }
    
    response = requests.get(url, headers=headers, params=params)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Found {data['meta']['total']} agents")
        return data
    else:
        print('Error:', response.json())
        raise Exception(f'Failed to list agents: {response.status_code}')

# Example: List all active Vapi agents
list_agents(status='active', voice_platform='vapi', sort_by='name')

Response

Success Response (200 OK):

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Customer Support Agent",
      "phone_number": "+15551234567",
      "voice_platform": "vapi",
      "language": "en",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T14:22:00Z"
    },
    {
      "id": "agent_def456",
      "name": "Sales Assistant",
      "phone_number": "+15559876543",
      "voice_platform": "retell",
      "language": "en",
      "status": "active",
      "created_at": "2025-01-14T09:15:00Z",
      "updated_at": "2025-01-14T09:15:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "per_page": 25,
    "total_pages": 2,
    "request_id": "req_list_agents_123",
    "timestamp": "2025-01-15T15:00:00Z"
  },
  "links": {
    "first": "https://api.ayra.ai/v1/agents?page=1",
    "prev": null,
    "next": "https://api.ayra.ai/v1/agents?page=2",
    "last": "https://api.ayra.ai/v1/agents?page=2"
  }
}

Pagination Example:

async function getAllAgents() {
  let allAgents = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await listAgents({ page, per_page: 100 });
    allAgents = allAgents.concat(response.data);
    
    hasMore = page < response.meta.total_pages;
    page++;
  }
  
  console.log(`Retrieved all ${allAgents.length} agents`);
  return allAgents;
}

Notes

• • The list endpoint returns summary information. Use the Get Agent endpoint for complete configuration details.
• • Results are cached briefly (30 seconds) for performance. Very recent changes might not appear immediately.
• • Maximum per_page is 100. Requests exceeding this limit are automatically capped.
• • Empty search queries return all agents (subject to other filters).