---
sidebar_position: 7
title: Call History, Recordings & Transcription
description: View agent and team call history, stream or download call recordings, and retrieve AI transcriptions via the Firetell Agent API.
---

# Call History, Recordings & Transcription

Retrieve the history of calls handled by the authenticated agent, play back or download call recordings, and inspect speaker-diarized AI transcriptions, summaries, sentiment, and action items.

:::info[Data Scoping]
Standard `/call-center/call-history` endpoints return calls accessible to the authenticated agent (where the agent was a participant). Team leaders and supervisors can also query team-wide call history via `/call-center/teams/:team_id/call-history`.
:::

## Endpoints

| Method | Endpoint                                                   | Description                                                            |
| ------ | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `GET`  | `/call-center/call-history`                                | List calls accessible by the current agent                             |
| `GET`  | `/call-center/call-history/:id`                            | Get details of an accessible call                                      |
| `GET`  | `/call-center/call-history/:id/recordings`                 | Get all recordings for an accessible call                              |
| `GET`  | `/call-center/call-history/:id/recordings/stream`          | Stream primary recording audio (`302` redirect or stream metadata JSON) |
| `GET`  | `/call-center/call-history/:id/recordings/:index/stream`   | Stream a specific recording by index (`302` redirect or JSON)          |
| `GET`  | `/call-center/call-history/:id/recordings/:index/download` | Download a specific recording by index (`302` redirect or JSON)        |
| `GET`  | `/call-center/call-history/:id/transcription`              | Get AI transcription, speaker dialogues, summary & sentiment           |
| `GET`  | `/call-center/teams/:team_id/call-history`                 | List calls handled by team agents *(Team Leader / Supervisor)*         |
| `GET`  | `/call-center/teams/:team_id/call-history/:id`             | Get details of a team call *(Team Leader / Supervisor)*                |

## Authentication

All endpoints require a `Bearer` JWT with the `agent-api` audience:

```http
Authorization: Bearer YOUR_AGENT_JWT
```

---

## 1. List My Calls

```http
GET /api/v1/call-center/call-history
```

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

### Query Parameters

| Parameter    | Type   | Default | Description                                                                                                          |
| ------------ | ------ | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `direction`  | string | `all`   | Filter by call direction: `inbound`, `outbound`, `internal`, or `all`                                                |
| `status`     | string | —       | Filter by call status: `answered`, `active`, `completed`, `failed`, `busy`, `no_answer`, `created`, `queued`         |
| `sentiment`  | string | `all`   | Filter by AI sentiment analysis: `positive`, `neutral`, `negative`, or `all`                                         |
| `page`       | number | `1`     | Page number (`minimum: 1`)                                                                                           |
| `limit`      | number | `20`    | Items per page (`minimum: 1`, `maximum: 100`)                                                                        |
| `search`     | string | —       | Search by phone number or party name (`maxLength: 50`)                                                               |
| `sort_field` | string | —       | Field to sort by (`maxLength: 25`, e.g., `created_at`, `start_time`, `duration`)                                     |
| `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=20&direction=inbound&sentiment=positive" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

```json
{
  "data": [
    {
      "id": "call_01h900000000000000000001",
      "workspace_id": "ws_123456789",
      "number": "18005550199",
      "client_number": "14155552671",
      "from": {
        "type": "agent",
        "name": "Support Agent 1",
        "number": "agent1001",
        "avatar": null
      },
      "to": {
        "type": "client",
        "name": "14155552671",
        "number": "14155552671",
        "avatar": null
      },
      "source": "client-api",
      "type": "audio",
      "direction": "outbound",
      "status": "completed",
      "start_time": "2026-08-13T04:32:42.551Z",
      "answer_time": "2026-08-13T04:32:46.191Z",
      "end_time": "2026-08-13T04:32:48.931Z",
      "duration": 6,
      "billsec": 2,
      "hangup_cause": "NORMAL_CLEARING",
      "recording": "ready",
      "transcription": "completed",
      "sentiment": "positive",
      "summary": "Client asked about service pricing and installation options.",
      "action_items": [
        "Send quote to client email",
        "Schedule follow-up call"
      ],
      "created_at": "2026-08-13T04:32:42.600Z",
      "updated_at": "2026-08-13T04:32:48.983Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}
```

### Call Object Schema

| Field           | Type           | Description                                                                                          |
| --------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| `id`            | string         | Unique Call ID (e.g., `call_01h900000000000000000001`)                                               |
| `workspace_id`  | string         | Workspace identifier                                                                                 |
| `number`        | string         | Workspace phone number (DID) or extension used                                                       |
| `client_number` | string         | External party phone number                                                                          |
| `from`          | object         | Caller party metadata (`type`, `name`, `number`, `avatar`)                                           |
| `to`            | object         | Callee party metadata (`type`, `name`, `number`, `avatar`)                                           |
| `source`        | string         | Call origin (`client-api`, `agent-api`, `server-api`, `call_flow`)                                   |
| `type`          | string         | Media type (`audio` or `video`)                                                                      |
| `direction`     | string         | Call direction: `inbound`, `outbound`, or `internal`                                                 |
| `status`        | string         | Call status (`answered`, `active`, `completed`, `failed`, `busy`, `no_answer`, `created`, `queued`)  |
| `start_time`    | string         | ISO 8601 timestamp when call signaling started                                                       |
| `answer_time`   | string\|null   | ISO 8601 timestamp when the call was answered                                                        |
| `end_time`      | string\|null   | ISO 8601 timestamp when the call ended                                                               |
| `duration`      | number         | Total call duration in seconds                                                                       |
| `billsec`       | number         | Billable talk time in seconds (after answer)                                                         |
| `hangup_cause`  | string\|null   | SIP hangup cause (e.g., `NORMAL_CLEARING`)                                                           |
| `recording`     | string\|null   | Recording state (e.g., `ready`, `processing`, `none`)                                                |
| `transcription` | string\|null   | AI transcription state (e.g., `completed`, `processing`, `none`)                                     |
| `sentiment`     | string\|null   | AI sentiment classification (`positive`, `neutral`, `negative`)                                      |
| `summary`       | string\|null   | AI-generated executive summary of the conversation                                                   |
| `action_items`  | string[]\|null | Extracted follow-up tasks and action items                                                           |
| `created_at`    | string         | ISO 8601 record creation timestamp                                                                   |
| `updated_at`    | string         | ISO 8601 record last-updated timestamp                                                               |

---

## 2. Get Call Details

```http
GET /api/v1/call-center/call-history/:id
```

Retrieve full details for a single call accessible by the authenticated agent.

### Path Parameters

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

### Request

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

### Response `200 OK`

Returns a single [Call Object](#call-object-schema).

---

## 3. Get Call Recordings

```http
GET /api/v1/call-center/call-history/:id/recordings
```

List all audio recordings associated with an accessible call, including pre-signed `stream_url` and `download_url` links.

### Path Parameters

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

### Request

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

### Response `200 OK`

```json
{
  "call_id": "call_01h900000000000000000001",
  "recordings": [
    {
      "index": 0,
      "id": "rec_01h900000000000000000001",
      "start_time": "2026-08-17T11:01:11.035Z",
      "end_time": "2026-08-17T11:01:27.163Z",
      "duration": 16,
      "format": "wav",
      "size_bytes": 256000,
      "file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
      "stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?X-Amz-Signature=...",
      "download_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment..."
    }
  ]
}
```

---

## 4. Stream Primary Call Recording

```http
GET /api/v1/call-center/call-history/:id/recordings/stream
```

Stream the primary recording (index `0`) of an accessible call. When `redirect=false`, returns JSON metadata containing the signed `stream_url`; otherwise responds with an HTTP `302` redirect directly to the audio stream.

### Parameters

| Parameter  | In    | Type   | Required | Description                                                                                      |
| ---------- | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `id`       | path  | string | Yes      | Call ID                                                                                          |
| `redirect` | query | string | Yes      | Set to `"false"` to receive JSON metadata, or `"true"` to receive a `302` redirect to the audio |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/recordings/stream?redirect=false" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK` (`redirect=false`)

```json
{
  "call_id": "call_01h900000000000000000001",
  "recording_id": "rec_01h900000000000000000001",
  "recording_index": 0,
  "file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
  "format": "wav",
  "stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?X-Amz-Signature=...",
  "size_bytes": 256000,
  "start_time": "2026-08-17T11:01:11.035Z",
  "end_time": "2026-08-17T11:01:27.163Z"
}
```

---

## 5. Stream Call Recording by Index

```http
GET /api/v1/call-center/call-history/:id/recordings/:index/stream
```

Stream a specific recording segment by its zero-based `index`. Supports both `302` redirect and JSON metadata response via the `redirect` query parameter.

### Parameters

| Parameter  | In    | Type   | Required | Description                                                                                      |
| ---------- | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `id`       | path  | string | Yes      | Call ID                                                                                          |
| `index`    | path  | string | Yes      | Zero-based recording index (e.g., `0`)                                                           |
| `redirect` | query | string | Yes      | Set to `"false"` to receive JSON metadata, or `"true"` to receive a `302` redirect to the audio |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/recordings/0/stream?redirect=false" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK` (`redirect=false`)

```json
{
  "call_id": "call_01h900000000000000000001",
  "recording_id": "rec_01h900000000000000000001",
  "recording_index": 0,
  "file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
  "format": "wav",
  "stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?X-Amz-Signature=...",
  "download_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment...",
  "size_bytes": 256000,
  "start_time": "2026-08-17T11:01:11.035Z",
  "end_time": "2026-08-17T11:01:27.163Z"
}
```

---

## 6. Download Call Recording by Index

```http
GET /api/v1/call-center/call-history/:id/recordings/:index/download
```

Download a specific recording file with `Content-Disposition: attachment`. When `redirect=false`, returns JSON metadata with the pre-signed `download_url`; otherwise responds with a `302` redirect to start the file download.

### Parameters

| Parameter  | In    | Type   | Required | Description                                                                                         |
| ---------- | ----- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `id`       | path  | string | Yes      | Call ID                                                                                             |
| `index`    | path  | string | Yes      | Zero-based recording index (e.g., `0`)                                                              |
| `redirect` | query | string | Yes      | Set to `"false"` to receive JSON metadata, or `"true"` to `302` redirect to the attachment download |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/call-history/call_01h900000000000000000001/recordings/0/download?redirect=false" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK` (`redirect=false`)

```json
{
  "call_id": "call_01h900000000000000000001",
  "recording_id": "rec_01h900000000000000000001",
  "recording_index": 0,
  "file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
  "format": "wav",
  "stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment...",
  "download_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment...",
  "size_bytes": 256000,
  "start_time": "2026-08-17T11:01:11.035Z",
  "end_time": "2026-08-17T11:01:27.163Z"
}
```

---

## 7. Get Call Transcription & AI Summary

```http
GET /api/v1/call-center/call-history/:id/transcription
```

Retrieve the complete AI transcription for a call, including the speaker-diarized `dialogues` timeline (`client` vs. `agent` channels), `full_text`, executive `summary`, `sentiment`, and `action_items`.

### Path Parameters

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

### Request

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

### Response `200 OK`

```json
{
  "id": "trans_01h900000000000000000001",
  "call_id": "call_01h900000000000000000001",
  "workspace_id": "ws_123456789",
  "direction": "inbound",
  "language": "en",
  "dialogue_count": 2,
  "duration_seconds": 18,
  "dialogues": [
    {
      "id": "dlg_01h900000000000000000001_0_1",
      "speaker": "client",
      "channel_index": 0,
      "text": "Hello, I would like to learn more about your cloud call center solutions.",
      "confidence": 0.98,
      "duration_ms": 3200,
      "timestamp": "2026-08-18T07:00:02.100Z"
    },
    {
      "id": "dlg_01h900000000000000000001_1_2",
      "speaker": "agent",
      "channel_index": 1,
      "text": "Hello! I would be delighted to assist you. What features are you most interested in?",
      "confidence": 0.99,
      "duration_ms": 2800,
      "timestamp": "2026-08-18T07:00:06.400Z"
    }
  ],
  "full_text": "Client: Hello, I would like to learn more about your cloud call center solutions.\nAgent: Hello! I would be delighted to assist you. What features are you most interested in?",
  "summary": "Customer inquired about enterprise cloud contact center solutions and pricing.",
  "sentiment": "positive",
  "action_items": [
    "Send Enterprise pricing sheet to customer",
    "Schedule live product demo"
  ],
  "created_at": "2026-08-18T07:00:10.500Z",
  "updated_at": "2026-08-18T07:00:10.500Z"
}
```

### Transcription Object Fields

| Field              | Type     | Description                                                                        |
| ------------------ | -------- | ---------------------------------------------------------------------------------- |
| `id`               | string   | Transcription ID                                                                   |
| `call_id`          | string   | Associated Call ID                                                                 |
| `workspace_id`     | string   | Workspace ID                                                                       |
| `direction`        | string   | Call direction (`inbound`, `outbound`, `internal`)                                 |
| `language`         | string   | Detected or configured language code (e.g., `en`, `vi`)                            |
| `dialogue_count`   | number   | Total number of speaker turns in `dialogues`                                       |
| `duration_seconds` | number   | Transcribed audio duration in seconds                                              |
| `dialogues`        | array    | Chronological list of utterances (`id`, `speaker`, `channel_index`, `text`, `confidence`, `duration_ms`, `timestamp`) |
| `full_text`        | string   | Concatenated plain-text transcript across all speakers                             |
| `summary`          | string   | AI-generated summary of the call                                                   |
| `sentiment`        | string   | Overall call sentiment (`positive`, `neutral`, `negative`)                         |
| `action_items`     | string[] | Extracted action items and next steps                                              |
| `created_at`       | string   | ISO 8601 creation timestamp                                                        |
| `updated_at`       | string   | ISO 8601 last-updated timestamp                                                    |

---

## 8. List Team Call History (Leader / Supervisor)

```http
GET /api/v1/call-center/teams/:team_id/call-history
```

Retrieve a paginated list of calls handled by agents belonging to a specific team. Requires the `leader` or `supervisor` role.

### Parameters

| Parameter    | In    | Type   | Required | Description                                                                     |
| ------------ | ----- | ------ | -------- | ------------------------------------------------------------------------------- |
| `team_id`    | path  | string | Yes      | Team ID                                                                         |
| `page`       | query | number | No       | Page number (`minimum: 1`, default: `1`)                                        |
| `limit`      | query | number | No       | Items per page (`minimum: 1`, `maximum: 100`, default: `20`)                    |
| `search`     | query | string | No       | Search by phone number or caller name (`maxLength: 50`)                         |
| `sort_field` | query | string | No       | Field to sort by (`maxLength: 25`)                                              |
| `sort_order` | query | string | No       | Sort order: `asc` or `desc` (default: `desc`)                                   |

### Request

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

### Response `200 OK`

```json
{
  "data": [
    {
      "id": "call_650000000000000000000150",
      "workspace_id": "my_workspace",
      "agent_id": "650000000000000000000001",
      "direction": "inbound",
      "status": "completed",
      "number": "+14155551234",
      "from": {
        "name": "John Doe",
        "number": "+14155551234"
      },
      "to": {
        "name": null,
        "number": "agent.01"
      },
      "duration": 120,
      "billsec": 100,
      "recording_url": "https://storage.firetell.app/recordings/call_150.wav",
      "start_time": "2026-08-04T11:42:27.143Z",
      "answer_time": "2026-08-04T11:42:36.123Z",
      "end_time": "2026-08-04T11:43:00.843Z",
      "created_at": "2026-08-04T11:42:27.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}
```

---

## 9. Get Team Call Details (Leader / Supervisor)

```http
GET /api/v1/call-center/teams/:team_id/call-history/:id
```

Retrieve detailed information for a specific call handled by an agent in your managed team. Requires the `leader` or `supervisor` role.

### Path Parameters

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `team_id` | string | Yes      | Team ID     |
| `id`      | string | Yes      | Call ID     |

### Request

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

### Response `200 OK`

```json
{
  "id": "call_650000000000000000000150",
  "workspace_id": "my_workspace",
  "agent_id": "650000000000000000000001",
  "direction": "inbound",
  "status": "completed",
  "number": "+14155551234",
  "from": {
    "name": "John Doe",
    "number": "+14155551234"
  },
  "to": {
    "name": null,
    "number": "agent.01"
  },
  "duration": 120,
  "billsec": 100,
  "recording_url": "https://storage.firetell.app/recordings/call_150.wav",
  "start_time": "2026-08-04T11:42:27.143Z",
  "answer_time": "2026-08-04T11:42:36.123Z",
  "end_time": "2026-08-04T11:43:00.843Z",
  "created_at": "2026-08-04T11:42:27.000Z"
}
```

See the [Teams API Reference](/developers/rest-api/agent-api/teams) for full team supervision and management endpoints.

---

## Error Responses

| Status | Description                                                        |
| ------ | ------------------------------------------------------------------ |
| `401`  | Missing or invalid `agent-api` Bearer JWT                          |
| `403`  | Insufficient permissions to access this call or team resource      |
| `404`  | Call, recording, or transcription not found                        |
