---
title: "Search phone calls"
method: POST
path: "/public-api/v1/phone_calls/list"
tags: ["phone_calls"]
---

# Search phone calls

`POST /public-api/v1/phone_calls/list`

## Request

- Base URL: `/` (relative, and the document’s source URL is not known)
- URL: `/public-api/v1/phone_calls/list`
- Auth: HTTP bearer and API key in header `x-tenant-code`

Search parent phone-call records visible to the caller.

One parent call can contain multiple call legs. Use
``POST /phone_call_legs/list`` when each result must be an individual leg.
Filter by time, user, number, type, keyword, tag, or free text; paginate
with ``first``, ``offset``, and ``after``. ``count`` is populated only when
``include_count=true``. Nested ``details`` are populated only when
``include_call_details=true``.

## Request body

- CallSearchRequest: Request body for ``POST /phone_calls/list`` — search filters and pagination.
  - `first` integer: Forward page size. 1 to 200.
  - `offset` integer: Number of matching calls to skip before this page. 0 to 5000.
  - `after` string, nullable: Cursor from the previous response's ``page_info.end_cursor``.
  - `starts_at` string, date-time, nullable: Filter calls by start time.
  - `ends_at` string, date-time, nullable: Filter calls by end time.
  - `call_types` AppSchemasCallsCallType[]: Restrict results to these call types.
  - `numbers` string[]: Restrict results to calls involving any of these phone numbers.
  - `user_ids` string[]: Restrict results to these numeric platform user IDs.
  - `keyword_values__include_and` string[]: Require calls to contain every supplied keyword value.
  - `tag_values__include_and` string[]: Require calls to have every supplied tag value.
  - `tag_values__exclude` string[]: Exclude calls with any supplied tag value.
  - `q` string, nullable: Free-text filter for call records.
  - `include_archived` boolean: When true, include archived calls. Default false.
  - `include_count` boolean: When true, populate `count` (costs an extra lookup). Default false.
  - `include_call_details` boolean: When true, populate each call's nested per-leg `details` array (participants, keywords, tags, audio analysis) — the same shape as `GET /phone_calls/{id}`. Default false, so list responses stay lightweight.

## Response `200`

A page of matching parent phone calls, an optional matched count, and pagination cursors.

- CallListResponse: Response body for the call list.
  - `calls` Call[], required: Matching parent phone-call records.
    - `id` string, uuid, required
    - `circuit_number` string, nullable, required
    - `dial_starts_at` string, date-time, required
    - `dial_ends_at` string, date-time, nullable, required
    - `acw_ends_at` string, date-time, nullable, required
    - `duration_talk` integer, nullable, required
    - `details` AppSchemasCallsCallDetail[]: Per-leg call details. Always present; populated only when the request sets `include_call_details=true` (empty list otherwise).
      - `id` string, uuid, nullable
      - `event_type` string, nullable
      - `answered` boolean, nullable
      - `circuit_number` string, nullable
      - `circuit_name` string, nullable
      - `from_number` string, nullable
      - `to_number` string, nullable
      - `dial_starts_at` string, date-time, nullable
      - `dial_answered_at` string, date-time, nullable
      - `dial_ends_at` string, date-time, nullable
      - `acw_ends_at` string, date-time, nullable
      - `queueing_starts_at` string, date-time, nullable
      - `queueing_answered_at` string, date-time, nullable
      - `queueing_ends_at` string, date-time, nullable
      - `monitoring_type` string, nullable
      - `group_name` string, nullable
      - `dtmf` string, nullable
      - `deleted` boolean, nullable
      - `call_type` string, nullable
      - `duration_wait` number, nullable
      - `duration_talk` number, nullable
      - `keywords` AppSchemasCallsKeyword[]
        - `participant_id` string, uuid, nullable
        - `starts_at` number, nullable
        - `value` string, nullable
      - `participants` AppSchemasCallsParticipant[]
        - `id` string, uuid, nullable
        - `from_to` string, nullable
        - `type` string, nullable
        - `name` string, nullable
        - `company_name` string, nullable
        - `analysis` AppSchemasCallsParticipantAnalysis: Per-participant audio analysis (voice metrics).
          - `f0` number, nullable
          - `speechrate` number, nullable
          - `variance` number, nullable
      - `tags` AppSchemasCallsTag[]
        - `value` string, nullable
        - `creator_type` string, nullable
      - `customers` AppSchemasCallsParticipant[]
        - `id` string, uuid, nullable
        - `from_to` string, nullable
        - `type` string, nullable
        - `name` string, nullable
        - `company_name` string, nullable
        - `analysis` AppSchemasCallsParticipantAnalysis: Per-participant audio analysis (voice metrics).
          - `f0` number, nullable
          - `speechrate` number, nullable
          - `variance` number, nullable
      - `operators` AppSchemasCallsParticipant[]
        - `id` string, uuid, nullable
        - `from_to` string, nullable
        - `type` string, nullable
        - `name` string, nullable
        - `company_name` string, nullable
        - `analysis` AppSchemasCallsParticipantAnalysis: Per-participant audio analysis (voice metrics).
          - `f0` number, nullable
          - `speechrate` number, nullable
          - `variance` number, nullable
      - `analysis` CallAnalysis: Call-quality analysis for a call detail.
        - `score` number, nullable
        - `tlr` number, nullable
        - `rally_count` integer, nullable
        - `overlap_count` integer, nullable
        - `silence_count` integer, nullable
  - `count` integer, nullable, required: Total matching calls when ``include_count=true``; otherwise null.
  - `page_info` AppSchemasCallsPageInfo, required: Pagination info for the list response.
    - `start_cursor` string, nullable: ID of the first record on this page, or null when the returned ``calls`` collection is empty. Treat this value as opaque.
    - `end_cursor` string, nullable: ID of the last record on this page. Pass it unchanged as ``after`` to fetch the next page. Continue until the returned ``calls`` collection is empty; do not use ``end_cursor`` as the completion signal.

## Other responses

- `400`: The tenant could not be resolved from the request.
- `401`: Error envelope (`public_api.unauthorized`).
- `403`: The request is not allowed for the current tenant or access configuration.
- `404`: Error envelope (`public_api.not_found`).
- `409`: Error envelope (`public_api.conflict`).
- `413`: The request body exceeds the maximum allowed size.
- `422`: Validation Error
- `429`: Rate limit exceeded. Wait for ``Retry-After`` seconds before retrying.
- `502`: Error envelope (`public_api.internal_error`).
- `503`: The request could not be served right now. Please retry.
- `504`: Error envelope (`public_api.request_timeout`).

---

[API](https://skmtc.dev/miitel/apis/miitel-public-api.md) - [All operations](https://skmtc.dev/miitel/apis/miitel-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/miitel/apis/miitel-public-api/revisions/961732756fa3?raw)