> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yotel.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> List agents and retrieve real-time agent statistics.

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.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.yotel.in/api/v1/agents \
    -H "Authorization: Bearer yt_live_YOUR_KEY"
  ```

  ```python Python theme={null}
  agents = client.agents.list()
  for agent in agents:
      print(agent.display_name, agent.status)
  ```

  ```typescript TypeScript theme={null}
  const agents = await client.agents.list();
  agents.forEach((a) => console.log(a.display_name, a.status));
  ```
</CodeGroup>

**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

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.yotel.in/api/v1/agents/{agent_id} \
    -H "Authorization: Bearer yt_live_YOUR_KEY"
  ```

  ```python Python theme={null}
  agent = client.agents.get("agent_id")
  ```

  ```typescript TypeScript theme={null}
  const agent = await client.agents.get("agent_id");
  ```
</CodeGroup>

**Scope:** `agents:read`  |  **Status:** `200 OK`

***

## Get agent statistics

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

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.yotel.in/api/v1/agents/{agent_id}/stats?window_hours=48" \
    -H "Authorization: Bearer yt_live_YOUR_KEY"
  ```

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

  ```typescript TypeScript theme={null}
  const stats = await client.agents.stats("agent_id", { windowHours: 48 });
  console.log(`Connect rate: ${(stats.connect_rate * 100).toFixed(1)}%`);
  ```
</CodeGroup>

**Scope:** `agents:read`  |  **Status:** `200 OK`

### Query parameters

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

### Response

```json theme={null}
{
  "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 |