---
sidebar_position: 7
title: Call History
description: View your call history — list and inspect calls you handled as an agent via the Firetell Agent API.
---

# Call History

View the history of calls you have handled as an agent. These endpoints are scoped — you can only see calls where you were the assigned agent.

:::info Data Scoping
Only calls where `agent_id` matches the authenticated agent are returned. Workspace-wide call history and call events/logs are available to admins via the Workspace API.
:::

## Endpoints

| Method | Endpoint                        | Description      |
| ------ | ------------------------------- | ---------------- |
| `GET`  | `/call-center/call-history`     | List my calls    |
| `GET`  | `/call-center/call-history/:id` | Get call details |

## Authentication

All endpoints require `Bearer` JWT with `agent-api` audience.

---

## List My Calls

```
GET /call-center/call-history
```

Retrieve a paginated list of calls handled by the authenticated agent, sorted by most recent first.

### Query Parameters

| Parameter    | Type   | Default | Description                 |
| ------------ | ------ | ------- | --------------------------- |
| `page`       | number | `1`     | Page number (min: 1)        |
| `limit`      | number | `20`    | Items per page (max: 100)   |
| `sort_order` | string | `desc`  | Sort order: `asc` or `desc` |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

```json
{
  "data": [
    {
      "id": "cl_a1b2c3d4e5f6g7h8i9j0k1",
      "workspace_id": "my_workspace",
      "direction": "inbound",
      "status": "completed",
      "type": "audio",
      "number": "84901234567",
      "client_number": "+84912345678",
      "from": {
        "name": null,
        "number": "+84912345678"
      },
      "to": {
        "name": "Sales Line",
        "number": "84901234567"
      },
      "agent_id": "ag_abc123",
      "source": "call_flow",
      "duration": 245,
      "call_flow_id": "cf_xyz789",
      "hangup_cause": "normal_clearing",
      "created_at": "2026-07-21T07:30:00.000Z",
      "answered_at": "2026-07-21T07:30:05.000Z",
      "ended_at": "2026-07-21T07:34:10.000Z"
    },
    {
      "id": "cl_n3w1d2e3f4g5h6i7j8k9l0",
      "workspace_id": "my_workspace",
      "direction": "outbound",
      "status": "completed",
      "type": "audio",
      "number": "84901234567",
      "client_number": "+84987654321",
      "from": {
        "name": "Agent John",
        "number": "84901234567"
      },
      "to": {
        "name": null,
        "number": "+84987654321"
      },
      "agent_id": "ag_abc123",
      "source": "agent_app",
      "duration": 120,
      "hangup_cause": "normal_clearing",
      "created_at": "2026-07-21T06:15:00.000Z",
      "answered_at": "2026-07-21T06:15:08.000Z",
      "ended_at": "2026-07-21T06:17:08.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "total_pages": 5
  }
}
```

### Call Object

| Field           | Type         | Description                                                     |
| --------------- | ------------ | --------------------------------------------------------------- |
| `id`            | string       | Call ID                                                         |
| `workspace_id`  | string       | Workspace identifier                                            |
| `direction`     | string       | `inbound`, `outbound`, or `internal`                            |
| `status`        | string       | `created`, `started`, `active`, `completed`, `failed`, `missed` |
| `type`          | string       | Call type: `audio`                                              |
| `number`        | string       | Workspace phone number used                                     |
| `client_number` | string       | External party phone number                                     |
| `from`          | object       | Caller info (`name`, `number`)                                  |
| `to`            | object       | Callee info (`name`, `number`)                                  |
| `agent_id`      | string       | Handling agent ID                                               |
| `source`        | string       | Call origin: `client-api`, `agent-api`, `server-api`            |
| `duration`      | number       | Call duration in seconds                                        |
| `call_flow_id`  | string\|null | Call flow ID if routed via a flow                               |
| `hangup_cause`  | string\|null | SIP hangup cause (e.g., `normal_clearing`)                      |
| `created_at`    | string       | ISO 8601 creation timestamp                                     |
| `answered_at`   | string\|null | ISO 8601 when call was answered                                 |
| `ended_at`      | string\|null | ISO 8601 when call ended                                        |

---

## Get Call Details

```
GET /call-center/call-history/:id
```

Retrieve detailed information about a specific call you handled.

### Path Parameters

| Parameter | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| `id`      | string | Call ID (e.g., `cl_a1b2c3...`) |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/cl_a1b2c3d4e5f6g7h8i9j0k1" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

Returns the full call object.

### Error Responses

| Status | Description                              |
| ------ | ---------------------------------------- |
| `404`  | Call not found or you do not have access |