---
title: Call History
excerpt: List the phone calls CX-Engine has received for a customer account, with filters, sorting and pagination.
order: 5
---

CX-Engine stores every phone call it receives from the PBX (through [CRM Lookup](/en/docs/cx-api/lookup) or by fetching it from the PBX) before processing it and pushing it to the connected CRM. This endpoint lists those stored calls.

> `GET /api/crm/phone-calls` reads the calls stored in CX-Engine. `GET /api/crm/lookup/phone-calls` reads the calls stored in the connected CRM (see [CRM Lookup](/en/docs/cx-api/lookup#get-apicrmlookupphone-calls)).

**Headers:** `Authorization: Bearer {workspace-token}`

---

## GET /api/crm/phone-calls

Returns a paginated list of the calls of the selected customer, most recent first.

Requires the `client` OAuth scope and the `crm-phone-call.view` permission. The customer is selected with the `customer_account` query parameter (see [Selecting the customer account](/en/docs/cx-api/smart-routings#selecting-the-customer-account)).

**Query parameters**

| Parameter | Description |
|---|---|
| `customer_account` | **Required.** Customer account code |
| `filter[direction]` | `inbound`, `outbound` or `internal` |
| `filter[status]` | `completed`, `failed`, `busy` or `no-answer` |
| `filter[answered]` | Whether the call was answered (`1` or `0`) |
| `filter[processing_status]` | `pending`, `queued`, `in_progress`, `completed`, `skipped` or `failed` |
| `filter[number_from]` | Caller number |
| `filter[number_to]` | Callee number |
| `filter[number_did]` | DID number |
| `filter[start_time]` | Call start time |
| `filter[end_time]` | Call end time |
| `filter[duration]` | Duration in seconds |
| `filter[subject]` | Call subject |
| `filter[body]` | Call notes |
| `filter[agent_first_name]` | Agent first name |
| `filter[agent_last_name]` | Agent last name |
| `filter[agent_email]` | Agent email address |
| `filter[pbx3cx_host_id]` | ID of the 3CX host the call comes from |
| `filter[pbx3cx_call_id]` | Call ID on the 3CX PBX |
| `include` | Comma-separated relations to load: `segments`, `logs` |
| `sort` | `start_time`, `end_time`, `created_at` or `updated_at`. Prefix with `-` for descending. Default: `-start_time` |
| `per_page` | Results per page (default: 20) |
| `page` | Page number |

Text filters match partial values (`filter[agent_email]=acme.com` matches every agent of that domain).

**Response `200`** — paginated response

```json
{
  "current_page": 1,
  "data": [
    {
      "id": 1842,
      "uuid": "9b1d6c1e-6f0a-4c7e-9a43-2f5d8a7b1c20",
      "source": "3cx",
      "ingested_via": "webhook",
      "customer_id": 12,
      "pbx3cx_host_id": 3,
      "pbx3cx_call_id": "48211",
      "processing_status": "completed",
      "processing_step": "complete",
      "number_from": "+33612345678",
      "number_to": { "number": "201" },
      "number_did": "+33142000000",
      "direction": "inbound",
      "status": "completed",
      "answered": true,
      "start_time": "2026-10-08T09:15:02.000000Z",
      "end_time": "2026-10-08T09:19:40.000000Z",
      "duration": {
        "y": 0, "m": 0, "d": 0, "h": 0, "i": 0, "s": 278, "f": 0,
        "invert": 0, "days": false, "from_string": false
      },
      "subject": "Support call",
      "body": null,
      "recording_url": null,
      "agent_first_name": "Bob",
      "agent_last_name": "Smith",
      "agent_email": "bob@acme.com",
      "queue_extension": "800",
      "created_at": "2026-10-08T09:19:41.000000Z",
      "updated_at": "2026-10-08T09:20:05.000000Z"
    }
  ],
  "first_page_url": "https://acme.cx-engine.app/api/crm/phone-calls?page=1",
  "from": 1,
  "last_page": 12,
  "last_page_url": "https://acme.cx-engine.app/api/crm/phone-calls?page=12",
  "links": [...],
  "next_page_url": "https://acme.cx-engine.app/api/crm/phone-calls?page=2",
  "path": "https://acme.cx-engine.app/api/crm/phone-calls",
  "per_page": 20,
  "prev_page_url": null,
  "to": 20,
  "total": 231
}
```

**Field notes**

| Field | Description |
|---|---|
| `source` | PBX the call comes from: `3cx` or `yeastar` |
| `ingested_via` | How CX-Engine received the call: `webhook` (pushed through the API) or `pbx_pull` (fetched from the PBX) |
| `processing_status` | Progress of the processing pipeline (recordings, transcription, CRM push…) |
| `processing_step` | Current step of the pipeline, `complete` once done |
| `number_from`, `number_to`, `number_did` | External numbers are E.164 strings; internal extensions are objects such as `{ "number": "201" }` |
| `duration` | Interval object; the duration in seconds is in `s` |

**Response `403`** — no customer selected, or not authorized