> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Calls

> List calls for your workspace with pagination, date filters, call id filters, batch call id filters, statuses, sentiments, end reasons, and export mode.

Read only
Returns every call placed in your workspace, paginated and sorted by creation time (newest first). A `duration` sort orders by duration instead, and an export of one batch (`export=true` with `batch_call_id`) follows the lead file order. Each entry includes the call's `id`, current `status`, `agent_id`, the number that placed the call (`from_number`) and the number that received it (`to_number`), its `call_direction` (`inbound` or `outbound`), `duration`, `end_reason`, and when it was placed (`called_time`). Use this endpoint for lightweight call browsing, status polling against a known set of recent calls, and quick filtering by agent, call id, batch call id, outcome, or time range. ID filters support comma-separated multi-value input.

Paginated results leave out retry attempts; send `export=true` or `call_id` to include them. Retry attempts carry `batch_id: null`. For the recording URL of one result, use [Get Call Details](https://dialnexa.com/docs/api-reference/v1/calls/get.md). The list endpoint is the lightweight view for browsing and filtering many calls.

## When to use this

* **Operational dashboards**: render a recent-calls table with status, duration, and end reason.
* **Live monitoring**: filter to the in-flight statuses (`created`, `sent`, `initiated`, `received`) to see calls that have not ended yet.
* **Per-agent health checks**: filter by `agent_id` to spot agents producing unusually high failure rates.
* **Batch exports**: pass `batch_call_id` with `export=true` to receive every matching call of one or more batches in a single JSON array, without pagination. Convert it to CSV on your side if you need a file.

## Query parameters

| Parameter | Type | Description |
| - | - | - |
| `agent_id` | string | Filter by one agent ID or a comma-separated list of agent IDs. Ignored when `agent_version_id` is sent, and replaced by `agent_version_name` when that name matches a version. |
| `call_id` | string | Filter by one call ID or a comma-separated list of call IDs. `call_` prefixes are accepted. |
| `batch_call_id` | string | Filter by one batch call ID or a comma-separated list of batch call IDs. `batch_` and `campaign_` prefixes are accepted. Combine with `export=true` to receive every matching call of those batches in one JSON array. |
| `from` | string | Filter by the workspace phone number on the call (the number dialled from, or for an inbound call the number that was called), as a partial match on its digits. |
| `to` | string | Filter by recipient phone number, as a partial match on the batch lead's number as stored. The value is not reduced to digits, and Indian lead numbers are stored as `91XXXXXXXXXX` without `+`, so send digits only. Only batch calls carry a lead, so single calls and retry attempts never match. |
| `type` | string | Filter by one call type or a comma-separated list: `phone`, `web`. Any other value returns `400`. |
| `call_direction` | string | Filter by one call direction or a comma-separated list: `inbound`, `outbound`. Any other value returns `400`. |
| `agent_version_id` | string | Filter batch calls by agent version, written as `<agent_id>-<version_number>` (for example `agent_2g7Xy3tY53gRlp-3`); one value or a comma-separated list. Only calls placed by a batch match. A value in any other format is ignored, and when no value is valid the filter is dropped. When it is sent, `agent_id` is not applied. |
| `agent_version_name` | string | Search by agent version name using a case-insensitive partial match. |
| `sentiment` | string | Filter by one sentiment or a comma-separated list of `positive`, `neutral`, `negative`, `unknown`, such as `positive,negative`. Values are lowercase; any other value returns `400`. |
| `start_date` | string | Return only calls created on or after the start of this day in UTC. The value is converted to UTC first, then widened to 00:00:00 UTC of that day, so a time with an offset can move the day. Send a plain date (`YYYY-MM-DD`). |
| `end_date` | string | Return only calls created on or before the end of this day in UTC. The value is converted to UTC first, then widened to 23:59:59.999 UTC of that day, so a time with an offset can move the day. Send a plain date (`YYYY-MM-DD`). |
| `duration_greater_than` / `duration_less_than` | number | Return calls longer or shorter than this many seconds. |
| `duration_min` / `duration_max` | number | Filter by an inclusive duration range in seconds. Send both: one sent alone is ignored. |
| `page` | integer | Page number, starting from 1. |
| `limit` | integer | Results per page. Minimum: `1`. Default: `20`. Maximum: `200`. |
| `created_at` | string | Sort by creation date. Values: `asc`, `desc`. |
| `duration` | string | Sort by call duration. Values: `asc`, `desc`. |
| `status` | string | Filter by one call status or a comma-separated list of `initiated`, `received`, `sent`, `did_not_pick`, `busy`, `failed`, `no_answer`, `completed`, `created`, `cancelled`, `retry_expired`, such as `completed,failed`. Any other value returns `400`. |
| `export` | boolean | Set to `true` to return every matching call in one JSON array without pagination, up to the applicable export limit, including retry attempts. Omit it or send `false` to receive pages. Combine with `batch_call_id` or `call_id` to pull a whole set of calls; convert it to CSV on your side if you need a file. For a batch export, the row limit counts the original calls only; retry attempts are added on top, so the array can be longer. |
| `end_reason` | string | Filter by one exact hang up reason or a comma-separated list: `agent_disconnected`, `user_disconnected`, `user_busy`, `user_did_not_pick_up`, `invalid_phone_number`, `unallocated_phone_number`, `unknown`, `network_failure`, `voicemail_detected`, `user_unreachable`, `destination_forbidden`, `system_failure`, `system_at_capacity`, `insufficient_balance`, `agent_not_found`, `sip_auth_failed`, `sip_trunk_unreachable`, `spend_cap_reached`, `dnc_blocked`. Unknown values are ignored; if none is known, no calls match. |
| `columns` | string | Export only. Comma-separated column keys. Excluding both `transcript` and `summary` raises the single-export limit from `5,000` to `10,000` rows. Omit this parameter to include all columns. |
| `is_ivr` | boolean | True for IVR calls including handoffs, false for other calls; omit for all. |
| `tags` | string | Comma-separated workflow lead tags copied to calls when placed. |
| `tags_match` | string | Whether calls must match any or all supplied tags. One of `any`, `all`. Default: `any`. |
| `agent_type` | string | Filter by agent type. ivr is equivalent to is\_ivr=true and includes IVR handoffs. Other types require an agent ID retained on the call; calls without one do not match those types. One of `single_prompt`, `conversational_flow`, `speech_to_speech`, `ivr`. |

Exports are limited to `5,000` matching calls. When `columns` is sent and leaves out both `transcript` and `summary`, the limit is `10,000`. A request over the applicable limit returns `400 Bad Request` with the matched row count and guidance to narrow the date range or add filters.

## Filter IVR Calls And Lead Tags

* `is_ivr=true` selects IVR calls, including conversational handoffs. Use `false` for non-IVR calls or omit it for all calls.
* `tags=priority,september` selects workflow lead tags copied to call records when calls were placed.
* `tags_match=any` matches at least one tag and is the default. Use `tags_match=all` to require every selected tag. Tags are normalized to lowercase.

These read-only filters can be combined with a date range and retried safely.

## List Calls By Agent Type

Set `agent_type` to `single_prompt`, `conversational_flow`, `speech_to_speech`, or `ivr`. For example, `GET /v1/calls?agent_type=conversational_flow` selects calls handled by a Conversational Flow Agent.

The existing `is_ivr` parameter remains supported. `agent_type=ivr` includes IVR menu calls and IVR handoffs, like `is_ivr=true`. The other three values require the call to retain an agent ID; older records without one do not match those filters. Omit both parameters to inspect all types.

## Errors

* `400 Bad Request` is returned when one or more query parameters are invalid, including a `status`, `type`, `call_direction` or `sentiment` value outside its list (the message names the value and the allowed ones), or when an export exceeds the applicable row limit.
* `401 Unauthorized` is returned when the API key is missing or invalid.
* `500 Internal Server Error` is returned on an unexpected server-side failure.

## Related endpoints

* [Get Call Details](https://dialnexa.com/docs/api-reference/v1/calls/get.md): fetch a single call's detail.
* [Trigger a Call](https://dialnexa.com/docs/api-reference/v1/calls/create.md): start a new outbound call.
* [API pagination](https://dialnexa.com/docs/api-reference/api-fundamentals.md#paginate-dialnexa-list-responses): how DialNexa list endpoints paginate.


## OpenAPI

````yaml GET /v1/calls
openapi: 3.0.0
info:
  title: DialNexa API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Organization Folders
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
  - name: Authentication
  - name: Agent Builder
  - name: Agent Evaluations
paths:
  /v1/calls:
    get:
      tags:
        - Calls
      summary: List Calls
      description: >-
        Returns calls for the authenticated workspace using the supplied
        filters, newest records first (a `duration` sort orders by duration
        instead, and an export of one batch follows the lead file order), as a
        root JSON array without pagination metadata. Paginated results leave out
        retry attempts; send `export=true` or `call_id` to include them.
      operationId: listCalls
      parameters:
        - name: agent_id
          required: false
          in: query
          description: >-
            Filter by agent ID: one ID or a comma-separated list (e.g.,
            agent_abc,agent_def). Ignored when agent_version_id is sent, and
            replaced by agent_version_name when that name matches a version.
          schema:
            type: string
        - name: call_id
          required: false
          in: query
          description: >-
            Filter by call ID - single or comma-separated list (e.g.,
            call_abc,call_def)
          schema:
            type: string
        - name: batch_call_id
          required: false
          in: query
          description: >-
            Filter by batch call ID - single or comma-separated list (e.g.,
            batch_abc,batch_def). With export=true, every matching call of those
            batches is returned in one JSON array.
          schema:
            type: string
        - name: from
          required: false
          in: query
          description: >-
            Filter by the workspace phone number on the call (the number dialled
            from, or for an inbound call the number that was called), as a
            partial match on its digits.
          schema:
            type: string
        - name: to
          required: false
          in: query
          description: >-
            Filter by recipient phone number, as a partial match on the batch
            lead's number as stored. The value is not reduced to digits, and
            Indian lead numbers are stored as `91XXXXXXXXXX` without `+`, so
            send digits only. Only batch calls carry a lead, so single calls and
            retry attempts never match this filter.
          schema:
            type: string
        - name: type
          required: false
          in: query
          description: >-
            Filter by call type: one value or a comma-separated list of `phone`,
            `web`.
          schema:
            type: string
        - name: call_direction
          required: false
          in: query
          description: >-
            Filter by call direction: one value or a comma-separated list of
            `inbound`, `outbound`.
          schema:
            type: string
        - name: agent_version_id
          required: false
          in: query
          description: >-
            Filter batch calls by agent version, written as
            `<agent_id>-<version_number>` (for example
            `agent_2g7Xy3tY53gRlp-3`); one value or a comma-separated list. Only
            calls placed by a batch match. A value in any other format is
            ignored, and when no value is valid the whole filter is dropped.
            When this parameter is sent, `agent_id` is not applied.
          schema:
            type: string
            example: agent_2g7Xy3tY53gRlp-3
        - name: agent_version_name
          required: false
          in: query
          description: Search by agent version name (partial match, case-insensitive)
          schema:
            type: string
        - name: sentiment
          required: false
          in: query
          description: >-
            Filter by user sentiment: one value or a comma-separated list of
            `positive`, `neutral`, `negative`, `unknown`.
          schema:
            type: string
        - name: start_date
          required: false
          in: query
          description: >-
            Return calls created on or after the start of this day in UTC (ISO
            8601). The value is converted to UTC first, then widened to 00:00:00
            UTC of that day, so a time with an offset can move the day. Send a
            plain date (`YYYY-MM-DD`).
          schema:
            type: string
        - name: end_date
          required: false
          in: query
          description: >-
            Return calls created on or before the end of this day in UTC (ISO
            8601). The value is converted to UTC first, then widened to
            23:59:59.999 UTC of that day, so a time with an offset can move the
            day. Send a plain date (`YYYY-MM-DD`).
          schema:
            type: string
        - name: duration_greater_than
          required: false
          in: query
          description: Return calls longer than this many seconds.
          schema:
            minimum: 0
            type: number
        - name: duration_less_than
          required: false
          in: query
          description: Return calls shorter than this many seconds.
          schema:
            minimum: 0
            type: number
        - name: duration_min
          required: false
          in: query
          description: >-
            Lower bound of a duration range in seconds, inclusive. Applied only
            together with duration_max; sent alone it is ignored.
          schema:
            minimum: 0
            type: number
        - name: duration_max
          required: false
          in: query
          description: >-
            Upper bound of a duration range in seconds, inclusive. Applied only
            together with duration_min; sent alone it is ignored.
          schema:
            minimum: 0
            type: number
        - name: page
          required: false
          in: query
          description: 'Page number (default: 1)'
          schema:
            minimum: 1
            type: integer
        - name: limit
          required: false
          in: query
          description: 'Results per page (default: 20)'
          schema:
            minimum: 1
            maximum: 200
            default: 20
            type: integer
        - name: created_at
          required: false
          in: query
          description: Sort by creation date
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: duration
          required: false
          in: query
          description: Sort by call duration
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: status
          required: false
          in: query
          description: >-
            Filter by call status: one value or a comma-separated list, for
            example completed,failed. Values: initiated, received, sent,
            did_not_pick, busy, failed, no_answer, completed, created,
            cancelled, retry_expired. An unknown value returns 400.
          schema:
            type: string
        - name: export
          required: false
          in: query
          description: >-
            Set to `true` to return every matching call in one JSON array
            without pagination, up to the export row limit, including retry
            attempts. Omit it or send `false` to receive pages. For a batch
            export, the row limit counts the original calls only; retry attempts
            are added on top, so the array can be longer.
          schema:
            type: boolean
        - name: end_reason
          required: false
          in: query
          description: >-
            Filter by why the call ended: one value or a comma-separated list of
            `agent_disconnected`, `user_disconnected`, `user_busy`,
            `user_did_not_pick_up`, `invalid_phone_number`,
            `unallocated_phone_number`, `unknown`, `network_failure`,
            `voicemail_detected`, `user_unreachable`, `destination_forbidden`,
            `system_failure`, `system_at_capacity`, `insufficient_balance`,
            `agent_not_found`, `sip_auth_failed`, `sip_trunk_unreachable`,
            `spend_cap_reached`, `dnc_blocked`. Unknown values are ignored; if
            no value is known, no calls match.
          schema:
            type: string
        - name: columns
          required: false
          in: query
          description: >-
            Export only: comma-separated list of column keys being exported
            (e.g. "duration,status,end_reason"). Lets the server skip fetching
            heavy columns nobody asked for, which raises the export row limit.
            Omit to fetch everything, as before.
          schema:
            type: string
        - name: is_ivr
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            True for IVR calls including handoffs, false for other calls; omit
            for all.
        - name: tags
          in: query
          required: false
          schema:
            type: string
            example: priority,september
          description: Comma-separated workflow lead tags copied to calls when placed.
        - name: tags_match
          in: query
          required: false
          schema:
            default: any
            type: string
            enum:
              - any
              - all
          description: Whether calls must match any or all supplied tags.
        - name: agent_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - single_prompt
              - conversational_flow
              - speech_to_speech
              - ivr
          description: >-
            Filter by agent type. ivr is equivalent to is_ivr=true and includes
            IVR handoffs. Other types require an agent ID retained on the call;
            calls without one do not match those types.
      responses:
        '200':
          description: Calls returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: call_abc123
                      description: Signed call ID
                    agent_id:
                      type: string
                      nullable: true
                      example: agent_2g7Xy3tY53gRlp
                      description: Agent that handled the call.
                    batch_id:
                      type: string
                      nullable: true
                      description: >-
                        Signed batch ID of the batch the call belongs to; null
                        for single calls and for retry attempts.
                    from_number:
                      type: string
                      nullable: true
                      description: >-
                        Number that placed the call: your DialNexa number for an
                        outbound call, and the caller's number for an inbound
                        call. Returned as recorded, so it may not start with
                        `+`. Null for a web call.
                      example: '+918012345678'
                    to_number:
                      type: string
                      nullable: true
                      example: '+919876543210'
                      description: >-
                        Number that received the call: the contact's number for
                        an outbound call, and your DialNexa number for an
                        inbound call. Returned as recorded: for a batch call it
                        is the lead's stored number, where an Indian number
                        appears as `91XXXXXXXXXX` without `+`.
                    call_direction:
                      type: string
                      description: 'Direction of the call: `inbound` or `outbound`.'
                      example: outbound
                    phone_number_id:
                      type: string
                      nullable: true
                      example: phn_abc123
                      description: >-
                        ID of the workspace phone number the call was placed
                        from.
                    called_time:
                      type: string
                      format: date-time
                    duration:
                      type: string
                      example: '42'
                      description: >-
                        Call duration in seconds, serialized as a string (the
                        column is a 64-bit integer); null until a duration is
                        recorded.
                      nullable: true
                    status:
                      type: string
                    initiated_time:
                      type: string
                    end_reason:
                      type: string
                      description: >-
                        Why the call ended; `unknown` until the call ends. One
                        of `agent_disconnected`, `user_disconnected`,
                        `user_busy`, `user_did_not_pick_up`,
                        `invalid_phone_number`, `unallocated_phone_number`,
                        `unknown`, `network_failure`, `voicemail_detected`,
                        `user_unreachable`, `destination_forbidden`,
                        `system_failure`, `system_at_capacity`,
                        `insufficient_balance`, `agent_not_found`,
                        `sip_auth_failed`, `sip_trunk_unreachable`,
                        `spend_cap_reached`, `dnc_blocked`.
                    postcallanalysis:
                      type: object
                      nullable: true
                      additionalProperties: true
                      description: >-
                        Post-call analysis fields extracted for this call, keyed
                        by field name. An empty object until analysis has run.
                    llm_name:
                      type: string
                      nullable: true
                      example: gpt-4o
                      description: Display name of the language model used on the call.
                    voice_model_name:
                      type: string
                      nullable: true
                      description: Display name of the voice used on the call.
                    recording_sas_url:
                      type: string
                      nullable: true
                      description: >-
                        Time-limited link to the recording. Absent from the
                        response unless export=true.
                  required:
                    - id
              examples:
                success:
                  summary: Successful response
                  value:
                    - id: call_abc123
                      agent_id: agent_2g7Xy3tY53gRlp
                      to_number: '+919876543210'
                      duration: '42'
                      status: completed
                      end_reason: user_disconnected
        '400':
          description: Bad request - invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    message: >-
                      Request validation failed: limit must not be greater than
                      200
                unknownFilterValue:
                  summary: Unknown filter value
                  value:
                    message: >-
                      Request validation failed: Invalid status filter value:
                      foo. Allowed values: initiated, received, sent,
                      did_not_pick, busy, failed, no_answer, completed, created,
                      cancelled, retry_expired
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    message: >-
                      API key is missing or invalid. You can generate this by
                      logging in into dashboard
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    message: An unexpected error occurred. Please try again later.
      security:
        - bearer: []
components:
  schemas:
    FilteredErrorResponse:
      type: object
      description: >-
        Error body on calls, batch calls, voices, languages and LLMs, which
        return only the message (and data for a coded refusal).
      properties:
        message:
          type: string
        data:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable refusal code.
          description: >-
            Present for a coded refusal: code and the details listed for that
            code.
        validation_errors:
          type: array
          description: >-
            Present when uploaded rows fail number validation (batch and
            workflow lead uploads): one group per distinct error.
          items:
            type: object
            properties:
              error:
                type: string
              rows:
                type: array
                items:
                  type: integer
                description: Row numbers with this error.
              phone_numbers:
                type: array
                items:
                  type: string
        invalid_row_count:
          type: integer
          description: 'Present with validation_errors: how many rows failed.'
      required:
        - message
  securitySchemes:
    bearer:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.