---
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`                                                                 |
| `direction`  | string | `all`   | Filter by call direction: `inbound`, `outbound`, `internal`, `all`                           |
| `status`     | string | `all`   | Filter by call status: `answered`, `completed`, `failed`, `no_answer`, etc.                 |
| `sentiment`  | string | `all`   | Filter by AI sentiment analysis: `positive`, `neutral`, `negative`, `all`                   |
| `search`     | string | —       | Search by phone number or party name                                                        |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history?page=1&limit=10&sentiment=positive" \
  -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,
      "billsec": 240,
      "call_flow_id": "cf_xyz789",
      "hangup_cause": "normal_clearing",
      "recording": "ready",
      "transcription": "completed",
      "sentiment": "positive",
      "summary": "Customer reached out to inquire about smart call center solutions.",
      "action_items": ["Send Enterprise plan quotation", "Schedule system demo"],
      "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 |