> ## 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 Batch Calls > List batch call jobs for your workspace and filter by draft, waiting, scheduled, running, paused, completed, cancelled, deleted, or compatibility active status. Read only Returns every batch call job in your workspace, paginated and sorted by creation date with the newest first. Each entry includes the batch title, current status, recipient and attempt counters, completed call rollups, latest dispatch time, and creation timestamp. Use List Batch Calls to power a batch history dashboard, build automation that watches for new batches, or audit which jobs have run in a given period. ## When to use this * **Operational dashboards**: render a batch history view with progress bars. * **Compliance audits**: list every batch run in a quarter for review. * **Reporting pipelines**: sync batch metadata into a data warehouse alongside call logs. * **Automation triggers**: detect newly created batches and start downstream reporting jobs. ## Query parameters | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | Page number, starting from 1. | | `limit` | Results per page (max 100, default 20). | | `status` | Filter by one batch status or comma-separated statuses. Supported values include `draft`, `waiting`, `scheduled`, `running`, `paused`, `completed`, `cancelled`, `deleted`, and compatibility `active`. | ## Response Counters | Field | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `attempt_stages` | Per-stage attempted and total counts. Depth `0` is the initial call, and depths `1` through `4` are retries. | | `picked_up_calls` | Completed call attempts across initial calls and retry children. In-progress and unanswered attempts are excluded. | | `picked_up_lead_count` | Legacy connected-recipient counter retained for compatibility. Prefer `picked_up_calls` for the current Picked Up value. | | `last_call_sent_at` | Latest dispatch timestamp across initial calls and retry children. | ## Verify The Result Confirm that `items` belongs to the authenticated workspace, then compare `picked_up_calls` and `attempt_stages` with campaign-linked Call History rows when exact recipient evidence matters. ## Errors * `403 Forbidden` is returned when the API key cannot read batch jobs on this workspace. ## Related endpoints * [Get Batch Call](/docs/api-reference/v1/batches/get): fetch a single batch's detail. * [Create Batch Call](/docs/api-reference/v1/batches/create): start a new batch. * [Pagination](/docs/api-reference/pagination): how DialNexa list endpoints paginate. * [Batch calling](/docs/batch-calls/overview): guidance on designing a batch. ## OpenAPI ````yaml GET /v1/batch-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: Transcribers - name: Webhooks - name: Voices - name: Workflows - name: Workflow Leads paths: /v1/batch-calls: get: tags: - Batch Calls summary: List Batch Calls description: >- Returns batch call jobs for the authenticated workspace, including status and progress fields. operationId: listBatchCalls parameters: - name: limit required: false in: query schema: example: 20 type: number - name: page required: false in: query schema: example: 1 type: number - name: status required: false in: query description: >- Filter by batch status - can be a single status or comma-separated list. Supported values include draft, waiting, scheduled, running, paused, completed, cancelled, deleted, and legacy active. schema: type: string responses: '200': description: Batch calls returned successfully. content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string example: batch_abc123 title: type: string status: type: string total_records: type: number createdAt: type: string format: date-time total_lead_count: type: number description: Total recipients loaded into the batch. sent_lead_count: type: number description: Initial recipient calls that have been sent. picked_up_lead_count: type: number description: >- Legacy connected-recipient counter retained for compatibility. Prefer picked_up_calls for the current Picked Up rollup. picked_up_calls: type: number description: >- Completed call attempts across initial calls and retry children. In-progress and unanswered outcomes are excluded. last_call_sent_at: type: string format: date-time nullable: true description: >- Latest dispatch time across initial calls and retry children. number_of_retries: type: number nullable: true description: Configured retry count. first_retry_count: type: number nullable: true description: Retry call logs scheduled for the first retry depth. second_retry_count: type: number nullable: true description: >- Retry call logs scheduled for the second retry depth. third_retry_count: type: number nullable: true description: Retry call logs scheduled for the third retry depth. fourth_retry_count: type: number nullable: true description: >- Retry call logs scheduled for the fourth retry depth. attempt_stages: type: array description: >- Per-stage attempt progress. Depth 0 is the initial call, and depths 1 through 4 are retry stages. Present when retry enrichment is available. items: type: object properties: depth: type: number example: 0 attempted: type: number example: 240 total: type: number example: 250 total: type: number page: type: number limit: type: number examples: success: summary: Successful response value: items: - id: batch_abc123 title: Q3 Follow-up Batch status: waiting total_records: 250 createdAt: '2026-07-03T10:30:00.000Z' total_lead_count: 250 sent_lead_count: 240 picked_up_lead_count: 120 picked_up_calls: 116 last_call_sent_at: '2026-07-03T11:42:18.000Z' number_of_retries: 2 first_retry_count: 80 second_retry_count: 25 third_retry_count: 0 fourth_retry_count: 0 attempt_stages: - depth: 0 attempted: 240 total: 250 - depth: 1 attempted: 60 total: 80 - depth: 2 attempted: 10 total: 25 total: 1 page: 1 limit: 20 '400': description: 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: 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 type: http ````