Agents

Agents are the human telecallers logged into the Yotel softphone. These read-only endpoints let you monitor agent status and performance from your own dashboards.

List agents

Returns all agents for the tenant. No pagination — agent counts are typically under 200 per deployment.

curl https://api.yotel.in/api/v1/agents \
  -H "Authorization: Bearer yt_live_YOUR_KEY"

agents = client.agents.list()
for agent in agents:
    print(agent.display_name, agent.status)

const agents = await client.agents.list();
agents.forEach((a) => console.log(a.display_name, a.status));

Scope: agents:read | Status: 200 OK

Response fields

Field	Type	Description
`id`	string	Agent UUID
`user_id`	string	Supabase user ID
`extension`	string	SIP extension number
`display_name`	string \| null	Agent display name
`status`	string	Current state: `"available"`, `"on_call"`, `"wrap_up"`, `"paused"`, `"offline"`
`current_call_uuid`	string \| null	Active call UUID (null if idle)
`last_status_at`	string \| null	ISO 8601 timestamp of last status change

Get an agent

curl https://api.yotel.in/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer yt_live_YOUR_KEY"

agent = client.agents.get("agent_id")

const agent = await client.agents.get("agent_id");

Scope: agents:read | Status: 200 OK

Get agent statistics

Returns rolling statistics for an agent over a configurable time window.

curl "https://api.yotel.in/api/v1/agents/{agent_id}/stats?window_hours=48" \
  -H "Authorization: Bearer yt_live_YOUR_KEY"

stats = client.agents.stats("agent_id", window_hours=48)
print(f"Connect rate: {stats.connect_rate:.1%}")

const stats = await client.agents.stats("agent_id", { windowHours: 48 });
console.log(`Connect rate: ${(stats.connect_rate * 100).toFixed(1)}%`);

Scope: agents:read | Status: 200 OK

Query parameters

Parameter	Type	Default	Description
`window_hours`	integer	`24`	Rolling window size in hours (1–720)

Response

{
  "agent_id": "agent_abc",
  "window_hours": 48,
  "calls_total": 312,
  "calls_connected": 187,
  "calls_failed": 43,
  "avg_talk_time_s": 127.4,
  "connect_rate": 0.599
}

Field	Type	Description
`agent_id`	string	Agent UUID
`window_hours`	integer	Requested window size
`calls_total`	integer	Total calls attempted
`calls_connected`	integer	Calls that were answered and bridged
`calls_failed`	integer	Calls that failed (busy, no answer, error)
`avg_talk_time_s`	number	Average talk duration in seconds (1 decimal)
`connect_rate`	number	`calls_connected / calls_total` (0.0 if no calls)

Errors

Status	Condition
`400`	`window_hours` out of range (must be 1–720)
`404`	Agent not found or belongs to another tenant

Overview

Campaigns

Leads

Calls & Recordings

Voice Agents

AI Sessions

Webhook Management

API Keys

Agents

List agents

Response fields

Get an agent

Get agent statistics

Query parameters

Response

Errors

​List agents

​Response fields

​Get an agent

​Get agent statistics

​Query parameters

​Response

​Errors

List agents

Response fields

Get an agent

Get agent statistics

Query parameters

Response

Errors