---
title: "Aggregate CDRs"
method: POST
path: "/{sub_domain}/api/cdrs/cdrs-aggregate"
tags: ["CDRs"]
---

# Aggregate CDRs

`POST /{sub_domain}/api/cdrs/cdrs-aggregate`

## Request

- Base URL: `https://api.commpeak.com/pbx`
- URL: `https://api.commpeak.com/pbx/{sub_domain}/api/cdrs/cdrs-aggregate`
- Auth: API key in header `Authorization`

Aggregate the Call Analytics call records into grouped summary rows over a required date range.

**When to use.** Produce summary rows (totals, durations, ACD, ASR, cost) grouped by one or more dimensions such as user, destination, or trunk. For the individual call rows behind Call Analytics rather than aggregates, use `GET /cdrs`.

**Request body.** `group` and `filter` are required, and `filter` must include `filter.start_at` and `filter.end_at`. See [Core API Concepts](https://td.commpeak.link/ReadMe-PBX-api-docs).

- `group` (string, required): semicolon-separated dimensions to group by, for example `user;call status;duration;hangup;destination;caller_id;q850;sip termination status;extension number;transfer to;conference to;trunk;network_type`.
- `fields` (string): semicolon-separated columns to include in each row, for example `user;call status;duration;total calls;successful calls;total duration;total bill duration;ACD;ASR;cost;transfer duration;conference duration;transfer cost;conference cost;total transfer;call agent duration`.
- `period` (string): semicolon-separated time buckets. Defaults to `year;month;day`. Example `year;month;day;hour`.
- `filter` (object, required): filter criteria. `start_at` and `end_at` are required and do not accept an operator. Other keys accept a single value, an array, or a `value;operator` expression, for example `"duration": "5;>|9999;<"`. Supported keys include `destination`, `caller_id`, `callAttributes`, `user`, `original_trunk_id`, `callsType`, `bill_duration` and `duration`.
- `order` (string): sort order, for example `user;desc`. The field must appear in `group` or `fields`.
- `limit` (integer): maximum rows to return, 1 to 500, default 500.
- `offset` (integer): row offset for pagination.

**Notes.** `callsType` accepts an array of call-type ids: PHONEBOOK 2, MANUAL_CALL 3, INCOMING 4, MISSED_CALL 7, INTERNAL_CALL 8.

**Returns.** `201` with an array of aggregated rows. Each row carries the grouped dimensions plus the requested metrics (`total`, `successful`, `call_duration`, `call_bill_duration`, `acd`, `asr`, `cost`, and so on). Durations are formatted as `H:MM:SS` and `period` reflects the chosen buckets.

**Example.**

```json
{
  "group": "user;call status;destination;trunk",
  "fields": "user;call status;total calls;successful calls;ACD;ASR;cost",
  "period": "year;month;day",
  "filter": {
    "start_at": "2020-01-01 00:00:00",
    "end_at": "2025-01-01 00:00:00",
    "user": [2, 3],
    "duration": "5;>|9999;<"
  },
  "order": "user;desc",
  "limit": 100,
  "offset": 0
}
```

## Path parameters

- `sub_domain` string, required: PBX Name (subdomain)

## Request body

- CDRAggregateInput
  - `group` string, required: Semicolon-separated list of fields to group the CDRs by. Required.
  - `fields` string, nullable: Semicolon-separated list of fields (columns) to include in the aggregated rows.
  - `period` string, nullable: Semicolon-separated time period for aggregation. Defaults to year;month;day.
  - `filter` CDRAggregateFilter, required
    - `start_at` string, required: Required. Range start date-time (operator not supported).
    - `end_at` string, required: Required. Range end date-time (operator not supported).
  - `order` string, nullable: Order of the aggregated rows. The field must be present in group or fields.
  - `limit` integer, nullable: Maximum number of aggregated rows to return (1-500, default 500).
  - `offset` integer, nullable: Offset for paginating the aggregated rows.

## Response `201`

Successful Response

- CDRAggregateRow[]
  - `caller_user_id` integer, nullable
  - `status` string, nullable
  - `dst_country` string, nullable: Destination country name detected from the dialed number prefix, when grouped by destination country. Null when no country could be detected.
  - `period` string, nullable
  - `total` string, nullable
  - `successful` string, nullable
  - `call_duration` string, nullable: Formatted as H:MM:SS.
  - `call_bill_duration` string, nullable: Formatted as H:MM:SS.
  - `acd` string, nullable
  - `asr` string, nullable
  - `cost` number, nullable
  - `transfer_duration` string, nullable
  - `conference_duration` string, nullable
  - `transfer_cost` number, nullable
  - `conference_cost` number, nullable
  - `total_transfer` string, nullable
  - `call_agent_duration` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/commpeak/apis/commpeak-pbx-api.md) - [All operations](https://skmtc.dev/commpeak/apis/commpeak-pbx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/commpeak/apis/commpeak-pbx-api/revisions/0b1e8c7fd3f6?raw)