> ## 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
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
Returns every call placed in your workspace, paginated and sorted by start time (newest first). Each entry includes the call's `id`, current `status`, `agent_id`, destination phone number, duration, and creation timestamp. 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.
For richer per-call data, full transcripts, recording URLs, sentiment, and the structured post-call analysis fields configured on the agent, use [List Call Logs](/docs/api-reference/call-logs/list) instead. Call logs carry the analytics payload while `/calls` is the lightweight scheduling-layer view.
## When to use this
* **Operational dashboards**: render a recent-calls table without paying the cost of full transcripts.
* **Live monitoring**: quickly filter to `initiated` and `in-progress` calls to see active conversations.
* **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 download a combined CSV for one or more batches.
## Query parameters
| Parameter | Type | Description |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | string | Filter by one agent ID or a comma-separated list of agent IDs. |
| `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` for a merged CSV across multiple batches. |
| `from` | string | Filter by sender phone number. |
| `to` | string | Filter by recipient phone number. |
| `type` | string | Filter by one call type or a comma-separated list of call types. |
| `call_direction` | string | Filter by one call direction or a comma-separated list of call directions. |
| `latency_min` / `latency_max` | number | Filter by minimum or maximum latency in milliseconds. |
| `agent_version_id` | string | Filter by one agent version ID or a comma-separated list of agent version IDs. |
| `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, such as `positive,negative`. |
| `start_date` | string | Return only calls created on or after this ISO 8601 timestamp. |
| `end_date` | string | Return only calls created on or before this ISO 8601 timestamp. |
| `duration_greater_than` / `duration_less_than` | number | Filter by minimum or maximum call duration in milliseconds. |
| `duration_min` / `duration_max` | number | Filter by a duration range in milliseconds. |
| `page` | string | Page number, starting from 1. Send decimal digits. |
| `limit` | string | Results per page. Send decimal digits. 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, such as `completed,failed`. |
| `export` | boolean | Set to `true` to return all matching rows as a flat list, bypassing pagination. Use with `batch_call_id` or `call_id` for combined CSV exports. |
| `end_reason` | string | Filter by one exact hang up reason or a comma-separated list of `end_reason` values. |
## Errors
* `400 Bad Request` is returned when one or more query parameters are invalid.
* `401 Unauthorized` is returned when the API key is missing or invalid.
* `403 Forbidden` is returned when the API key does not have access to this organization.
* `500 Internal Server Error` is returned on an unexpected server-side failure.
## Related endpoints
* [Get Call Details](/docs/api-reference/v1/calls/get): fetch a single call's detail.
* [Trigger a Call](/docs/api-reference/v1/calls/create): start a new outbound call.
* [List Call Logs](/docs/api-reference/call-logs/list): richer call data with transcript and analysis.
* [Pagination](/docs/api-reference/pagination): how DialNexa list endpoints paginate.
## OpenAPI
````yaml GET /v1/calls
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/calls:
get:
tags:
- Calls
- Calls V1
- V1
summary: List Calls
description: >-
Returns calls for the authenticated workspace using the supplied
filters, newest records first.
operationId: CallsV1Controller_findAll
parameters:
- name: agent_id
required: false
in: query
description: >-
Filter by agent ID(s) - can be a single ID or comma-separated list
(e.g., 1,2,3)
schema:
type: string
- name: call_id
required: false
in: query
description: >-
Filter by call ID - can be a single ID 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 - can be a single ID or comma-separated list
(e.g., batch_abc,batch_def)
schema:
type: string
- name: from
required: false
in: query
description: Filter by sender phone number
schema:
type: string
- name: to
required: false
in: query
description: Filter by recipient phone number
schema:
type: string
- name: type
required: false
in: query
description: >-
Filter by call type(s) - can be a single value or comma-separated
list
schema:
type: string
enum:
- phone
- web
- name: call_direction
required: false
in: query
description: >-
Filter by call direction(s) - can be a single value or
comma-separated list
schema:
type: string
enum:
- inbound
- outbound
- name: latency_min
required: false
in: query
description: Filter by minimum latency (in milliseconds)
schema:
type: number
- name: latency_max
required: false
in: query
description: Filter by maximum latency (in milliseconds)
schema:
type: number
- name: agent_version_id
required: false
in: query
description: >-
Filter by agent version ID(s) - can be a single ID or
comma-separated list (e.g., 1,2,3)
schema:
type: string
- 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 sentiment(s) - can be a single value or comma-separated
list
schema:
type: string
enum:
- positive
- neutral
- negative
- unknown
- name: start_date
required: false
in: query
description: Filter by start date (ISO format)
schema:
type: string
- name: end_date
required: false
in: query
description: Filter by end date (ISO format)
schema:
type: string
- name: duration_greater_than
required: false
in: query
description: Filter by minimum call duration (in milliseconds)
schema:
type: number
- name: duration_less_than
required: false
in: query
description: Filter by maximum call duration (in milliseconds)
schema:
type: number
- name: duration_min
required: false
in: query
description: Filter by minimum duration range (in milliseconds)
schema:
type: number
- name: duration_max
required: false
in: query
description: Filter by maximum duration range (in milliseconds)
schema:
type: number
- name: page
required: false
in: query
description: Page number (starts from 1)
schema:
type: string
- name: limit
required: false
in: query
description: 'Number of records per page (min: 1, default: 20, max: 200)'
schema:
type: string
- name: created_at
required: false
in: query
description: Sort by created_at (asc or desc)
schema:
type: string
enum:
- asc
- desc
- name: duration
required: false
in: query
description: Sort by duration (asc or desc)
schema:
type: string
enum:
- asc
- desc
- name: status
required: false
in: query
description: >-
Filter by call status(es) - can be a single status or
comma-separated list
schema:
type: string
- name: export
required: false
in: query
description: Set to true to export all data without pagination
schema:
type: boolean
- name: end_reason
required: false
in: query
description: >-
Filter by end/hangup reason - exact match; comma-separate multiple
values for OR filtering
schema:
type: string
responses:
'200':
description: Calls returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CallLogs'
examples:
success:
summary: Successful response
value:
- id: call_abc123
agent_id: agent_2g7Xy3tY53gRlp
to_number: '+919876543210'
from_number: '+14155552671'
status: initiated
call_direction: outbound
createdAt: '2026-07-03T10:30:00.000Z'
duration: 42
end_reason: completed
'400':
description: Bad request - invalid query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: Invalid query parameters
error: Bad Request
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: >-
Destination country or network prefix is not enabled for
this workspace
error: Forbidden
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
CallLogs:
type: object
properties:
id:
type: string
example: call_abc123
description: Signed call ID
required:
- id
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````