Skip to main content
GET
/
api
/
v1
/
agents

​
Get Agents

Retrieve a list of AI agents that the user has access to.

​
Endpoint

GET /api/v1/agents

​
Authentication

This endpoint requires an API key with the can_read_agents permission.

​
Response

{
  "agents": [
    {
      "id": 123,
      "assistant_id": "assistant_abc123",
      "name": "Customer Support",
      "role": "inbound agent",
      "phone_number": "+15551234567",
      "minutes_used": 345.5,
      "total_calls": 78,
      "model": "claude-3-opus-20240229",
      "voice_id": "ember",
      "can_make_calls": true,
      "team_id": 456
    },
    {
      "id": 789,
      "assistant_id": "assistant_def456",
      "name": "Sales Representative",
      "role": "outbound agent",
      "phone_number": "+15557654321",
      "minutes_used": 512.25,
      "total_calls": 132,
      "model": "claude-3-sonnet-20240229",
      "voice_id": "alloy",
      "can_make_calls": true,
      "team_id": 456
    }
    // Additional agent objects...
  ]
}

​
Error Codes

Status CodeError CodeDescription
401authentication_requiredNo API key was provided
401invalid_keyThe API key is invalid or inactive
403permission_deniedThe API key doesn’t have the required permission
500server_errorAn unexpected server error occurred

​
Example Request

curl -X GET 'https://api.klen.ai/api/v1/agents' \
  -H 'Authorization: Bearer klen_abcdef123456789'

​
Example Response

{
  "agents": [
    {
      "id": 123,
      "assistant_id": "assistant_abc123",
      "name": "Customer Support",
      "role": "inbound agent",
      "phone_number": "+15551234567",
      "minutes_used": 345.5,
      "total_calls": 78,
      "model": "claude-3-opus-20240229",
      "voice_id": "ember",
      "can_make_calls": true,
      "team_id": 456
    },
    {
      "id": 789,
      "assistant_id": "assistant_def456",
      "name": "Sales Representative",
      "role": "outbound agent",
      "phone_number": "+15557654321",
      "minutes_used": 512.25,
      "total_calls": 132,
      "model": "claude-3-sonnet-20240229",
      "voice_id": "alloy",
      "can_make_calls": true,
      "team_id": 456
    }
  ]
}

​
Response Properties

PropertyTypeDescription
idintegerThe database ID of the agent
assistant_idstringThe klen assistant ID
namestringThe name of the agent
rolestringThe role of the agent (inbound agent, outbound agent)
phone_numberstringThe phone number assigned to the agent (if any)
minutes_usednumberTotal minutes the agent has been used for calls
total_callsintegerTotal number of calls the agent has handled
modelstringThe AI model used by the agent
voice_idstringThe voice ID used by the agent
can_make_callsbooleanWhether the agent can make calls (has an assigned phone number)
team_idintegerThe ID of the team the agent belongs to (if any)

​
Access Control

This endpoint returns all agents that the authenticated user has access to. This includes:
  1. Agents created by the user
  2. Agents belonging to teams that the user has access to
If the user is a partner or client, they will only see agents associated with their account or accessible based on the partnership relationship.