---
title: "List terminated calls with advanced filters"
method: POST
path: "/calls"
tags: ["calls"]
---

# List terminated calls with advanced filters

`POST /calls`

Retrieve a paginated list of terminated calls with advanced filtering capabilities. This is the more powerful version of `GET /calls` — it supports filtering by tags, stars, users, groups, IVRs (with optional scenario IDs), and external/internal phone numbers.

**Permission:** `Calls Read` required.

**Monitoring:** This route always returns **all team calls** regardless of the Monitoring flag. The Monitoring setting has no effect on call listing — the underlying stats service does not filter by user. This applies identically whether Monitoring is ON or OFF.

**Date range:** Maximum allowed range is **15 days**. Defaults to the last 15 days if not specified.

**Advanced filtering:** Set `filter` to `ADVANCED` in the request body to enable the `advanced` object. This allows precise filtering by specific user IDs, group IDs, IVR IDs (with optional scenario IDs), and phone numbers (internal or external).

**Pagination:** Use `limit_count` and `limit_offset` for offset-based pagination, or `last_id_returned` for cursor-based deep pagination.

> **Note:** Multiple items may share the same `call_id` — this occurs when a call is transferred or routed through an IVR.

## Request body

- CallsFilter — Filter criteria for retrieving terminated calls. All fields are optional. The maximum date range is **15 days**. Set `filter` to `ADVANCED` to enable filtering by specific users, groups, IVRs, and phone numbers via the `advanced` object.
  - `filter` 'ALL' | 'DIRECT' | 'IVR' | 'ADVANCED', nullable — Scope of the call filter: - `ALL`: All calls (default). - `DIRECT`: Only direct calls (excludes IVR calls). - `IVR`: Only calls routed through IVRs. - `ADVANCED`: Enables the `advanced` object for fine-grained filtering by users, groups, IVRs, and numbers.
  - `start_date` string, date-time, nullable — Start of the date range (inclusive). Must be used together with `end_date`. Defaults to 15 days ago. Format: ISO 8601.
  - `end_date` string, date-time, nullable — End of the date range (inclusive). Must be used together with `start_date`. The difference between `start_date` and `end_date` must not exceed **15 days**. Defaults to tomorrow at midnight.
  - `ascending_order` boolean — [Deprecated] Sort order. Calls are returned in descending order (most recent first) by default.
  - `call_type` string[], nullable — Filter by call types. Multiple values can be combined.
  - `advanced` object, nullable — Advanced filters. **Only used when `filter` is set to `ADVANCED`.** Allows filtering by specific IVRs (with optional scenario IDs), groups (resolved to member user IDs server-side), individual users, and phone numbers.
    - `ivrs` IvrFilter[], nullable — Filter by specific IVR(s). Each entry can optionally include scenario IDs to further narrow results.
      - `ivr_id` integer — The identifier of the ivr
      - `numbers` integer[], nullable
      - `scenarios` integer[], nullable — The identifier of the scenario
    - `groups` integer[], nullable — Filter by group IDs. The server resolves group IDs to their member user IDs automatically.
    - `users` integer[], nullable — Filter by specific user IDs.
    - `ext_numbers` integer[], nullable — Filter by external phone numbers (E.164 format without '+').
    - `int_numbers` integer[], nullable — Filter by internal Ringover numbers (E.164 format without '+').
  - `stars` string[], nullable — Filter by star ratings assigned to calls.
  - `contacts` integer[], nullable — Filter by contact IDs to retrieve calls associated with specific contacts.
  - `tags` integer[], nullable — Filter by tag IDs to retrieve calls with specific tags.
  - `out_planning` boolean, nullable — When `true`, include only calls received outside of working hours. When `false`, exclude those calls.
  - `no_digit` boolean, nullable — When `true`, include only calls where no digit was pressed. When `false`, exclude those calls.
  - `ringing` boolean, nullable — When `true`, include only inbound calls that did not ring to any user. When `false`, exclude those calls.
  - `note` boolean, nullable — When `true`, include only calls with notes. When `false`, exclude calls with notes.
  - `tag` boolean, nullable — When `true`, include only calls with tags. When `false`, exclude calls with tags.
  - `short` boolean, nullable — When `true`, include only calls shorter than `exclude_short_value` seconds. When `false`, exclude those calls. Requires `exclude_short_value` > 0.
  - `long` boolean, nullable — When `true`, include only calls longer than `exclude_long_value` seconds. When `false`, exclude those calls. Requires `exclude_long_value` > 0.
  - `amd` boolean, nullable — When `true`, include only outbound calls detected as answered by a machine (AMD). When `false`, exclude those calls.
  - `exclude_short_value` integer, nullable — Duration threshold in seconds for the `short` filter.
  - `exclude_long_value` integer, nullable — Duration threshold in seconds for the `long` filter.
  - `limit_count` integer, nullable — Maximum number of calls to return. Default: 100.
  - `limit_offset` integer, nullable — Number of calls to skip for pagination. Default: 0. Maximum: 9000.
  - `last_id_returned` integer, nullable — Cursor-based pagination: returns call logs with a `cdr_id` lower than this value. Alternative to `limit_offset` for deep pagination.

## Response `200`

Successful operation

- CallsList
  - `user_id` integer — The identifier of the user
  - `team_id` integer — The identifier of the team
  - `limit_count_setted` integer — Used to create a pagination cursor
  - `limit_offset_setted` integer — Used to create a pagination cursor
  - `last_id_offset_setted` integer — The request will return <b>cdr_id</b> (call logs) prior to this one
  - `filter` string — The used filter
  - `call_list_count` integer — The size of the array <em>list</em>, corresponds to the number of logs retrieved
  - `call_list` Call[] — Array containing the different logs generated by the call (for example in case of transfer)
    - `cdr_id` integer
    - `call_id` string
    - `channel_id` string
    - `type` string
    - `direction` 'in' | 'out'
    - `is_answered` boolean
    - `last_state` 'CANCELLED' | 'ANSWERED' | 'MISSED' | 'FAILED' | 'QUEUE_TIMEOUT' | 'BLIND_TRANSFERED' | 'VOICEMAIL' | 'PERMANENT_TRANSFERED' | 'NOANSWER_TRANSFERED' | 'FAX_RECEIVED' | 'FAX_FAILED' | 'FAX_OUT_SENT' | 'INCORRECT_PINCODE' | 'FAX_OUT_NOT_SENT' | 'ANNOUNCE' — The enum regroups some samples
    - `start_time` string
    - `answered_time` string — Can be null if call_type is `MISSED` in the query parameters
    - `end_time` string
    - `incall_duration` integer — Can be null if call_type is `MISSED` in the query parameters
    - `total_duration` integer
    - `contact_number` string
    - `queue_duration` number
    - `ringing_duration` number
    - `hold_duration` number
    - `aftercall_duration` number
    - `ivr_duration` number
    - `hangup_by` string
    - `from_number` string
    - `to_number` string
    - `note` string
    - `star` string
    - `tags` Tag[]
      - `tag_id` integer — The identifier of the tag
      - `name` string — The name of the tag
      - `color` 'ff6b6b' | 'F06292' | 'BA68C8' | '9575CD' | '7986CB' | '64B5F6' | '4FC3F7' | '4DD0E1' | '4DB6AC' | '81C784' | 'AED581' | 'DCE775' | 'FFD54F' | 'FFB74D' | 'FF8A65' | 'A1887F' | 'E0E0E0' | '90A4AE'
      - `description` string — The description of the tag
      - `creation_date` string, date-time
    - `voicemail` string
    - `record` string
    - `fax` string
    - `user` CallUserLight
      - `user_id` integer — The user identifier
      - `team_id` integer — The team identifier of the user
      - `initial` string — The initials of the user
      - `color` string
      - `firstname` string — The firstname of the user
      - `lastname` string — The lastname of the user
      - `company` string — The company of the user
      - `email` string — The email of the user
      - `picture` string — The picture of the user
      - `concat_name` string
    - `conference` Conference
      - `conference_id` integer — The conference identifier
      - `name` string — The name of the conference
      - `numbers` Number[] — The numbers of the conference
        - `number` integer — Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
        - `label` string — The label of the number
        - `type` string — The type of the number
        - `user_id` integer — The user identifier
        - `ivr_id` integer — The unique identifier of the IVR. Use `GET /ivrs` to discover available IVR IDs.
        - `conference_id` integer — The conference identifier
        - `is_sms` boolean
        - `is_sms_write` boolean
        - `is_callable` boolean
        - `format` FormatNumber
          - `raw` integer
          - `country_code` string
          - `country` string
          - `e164` string
          - `international` string
          - `international_alt` string
          - `national` string
          - `national_alt` string
          - `rfc3966` string
          - `is_short_code` boolean
    - `ivr` IvrLight
      - `ivr_id` integer — The identifier if the ivr
      - `name` string — The name of the ivr
      - `color` 'ff6b6b' | 'F06292' | 'BA68C8' | '9575CD' | '7986CB' | '64B5F6' | '4FC3F7' | '4DD0E1' | '4DB6AC' | '81C784' | 'AED581' | 'DCE775' | 'FFD54F' | 'FFB74D' | 'FF8A65' | 'A1887F' | 'E0E0E0' | '90A4AE'
    - `contact` Contact
      - `contact_id` integer
      - `is_shared` boolean
      - `im_owner` string
      - `social_service` string, nullable
      - `social_service_id` string
      - `social_profile_url` string, nullable
      - `social_data` string, nullable
      - `firstname` string
      - `lastname` string
      - `company` string
      - `concat_name` string
      - `color` string
      - `initial` string
      - `profile_picture` string, nullable
      - `creation_date` string, date-time
      - `numbers` integer[], nullable
    - `amd` boolean — Show OR exclude calls answered by a 'machine'
    - `is_archived` integer — 0 is for false, 1 is for true. There are other possible values but the concerned calls should not be accessible via this api
    - `scenario_name` string — name of the IVR scenario reached during an inbound call
    - `scenario_id` string — id of the IVR scenario reached during an inbound call
    - `digits_entered` string[]
    - `missed` string
    - `notes` object
    - `locations` string
    - `groups` integer[]
  - `total_call_count` integer — The total number of calls
  - `total_missed_call_count` integer — The total number of missed calls

## Other responses

- `204` — No calls found for the given criteria
- `400` — Invalid filters — check date range (max 15 days), limit_count (max 1000), limit_offset (max 9000), call_type or stars enum values
- `401` — Unauthorized — invalid API key or missing `Calls Read` permission
- `500` — Internal server error

---

[API](https://skmtc.net/ringover/apis/ringover-public-api.md) · [All operations](https://skmtc.net/ringover/apis/ringover-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ringover/ringover-public-api/revisions/9da73dd2f99e/schema)