> ## 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.
# Update Batch Call Status
> Pause, resume, or cancel a v1 batch call.
Changes state - verify before retry
**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.
Update Batch Call Status changes the execution state of a batch call. Use it when you need to temporarily stop new outbound calls, continue a paused batch, or permanently cancel queued work. A batch can be paused while it is `running` or `waiting`. In the current lifecycle, `running` is the only active sending state, so pause a running batch before cancelling it permanently.
## When To Use Update Batch Call Status
* Use `pause` when a `running` or `waiting` batch should stop creating new calls, but calls already in progress can finish.
* Use `resume` when a paused batch should continue calling remaining leads.
* Use `cancel` when a non-running batch should stop permanently and queued calls should be removed. If the batch is `running`, pause it first, then cancel.
## Status Actions
| Action | Result |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pause` | Stops new outbound calls, moves the batch to `paused`, and keeps the batch resumable. |
| `resume` | Re-enqueues remaining leads for a paused batch. The campaign can return to `running` or `waiting` depending on start time and queue availability. |
| `cancel` | Removes queued calls and prevents the batch from resuming. For a `running` batch, pause first and cancel from `paused`. |
## Verify The Result
After the request succeeds, check the returned `campaign.status` value. You can also call [Get Batch Call](/docs/api-reference/v1/batches/get) to inspect the call logs and confirm that no new calls are being created after a pause or cancel action. If resume returns `waiting`, the batch is accepted but is not yet the active sender for the organization. See [Batch Call Retries And Statuses](/docs/batch-calls/retries-and-statuses#batch-lifecycle-state-machine) for the full status diagram.
## Common Errors
* `400 Bad Request` means the action is invalid or the current batch status does not allow that transition.
* `403 Forbidden` means the batch call does not belong to the authenticated workspace.
* `404 Not Found` means the batch call ID was not found.
## Related Endpoints
* [Create Batch Call](/docs/api-reference/v1/batches/create): upload leads and create a batch.
* [List Batch Calls](/docs/api-reference/v1/batches/list): find batch IDs in your workspace.
* [Get Batch Call](/docs/api-reference/v1/batches/get): inspect calls generated by a batch.
## OpenAPI
````yaml PATCH /v1/batch-calls/{id}/status
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/batch-calls/{id}/status:
patch:
tags:
- Batch Calls V1
- V1
summary: Update Batch Call Status
description: >-
Changes the execution status of a batch call. Use `pause` to halt new
outbound calls, `resume` to continue a paused batch, or `cancel` to
permanently stop the batch and remove queued calls.
operationId: BatchCallsV1Controller_updateStatus
parameters:
- name: id
required: true
in: path
description: Batch call ID
schema:
type: string
example: batch_abc123
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- action
properties:
action:
type: string
enum:
- pause
- resume
- cancel
example: pause
description: The status transition to apply.
examples:
pause:
summary: Pause a batch call
value:
action: pause
resume:
summary: Resume a batch call
value:
action: resume
cancel:
summary: Cancel a batch call
value:
action: cancel
responses:
'200':
description: Batch call status updated successfully.
content:
application/json:
examples:
success:
summary: Successful response
value:
success: true
message: Campaign paused successfully
campaign:
id: batch_abc123
status: paused
title: Q3 Follow-up Batch
affectedCalls:
initiated: 0
queued: 0
removedFromQueue: 12
cancelledCallLogs: 0
resumedCallLogs: 0
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Campaign paused successfully
campaign:
type: object
properties:
id:
type: string
example: batch_abc123
status:
type: string
enum:
- initiated
- draft
- waiting
- scheduled
- running
- paused
- completed
- cancelled
- deleted
example: paused
title:
type: string
example: Q3 Follow-up Batch
affectedCalls:
type: object
properties:
initiated:
type: number
example: 0
queued:
type: number
example: 0
removedFromQueue:
type: number
example: 12
cancelledCallLogs:
type: number
example: 0
resumedCallLogs:
type: number
example: 0
'400':
description: >-
Invalid action, or action not allowed for the current batch call
status.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: 'Invalid action. Must be one of: pause, resume, cancel'
error: Bad Request
'401':
description: Unauthorized - missing or invalid API key.
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 - batch call does not belong to your organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: You do not have permission to access this resource
error: Forbidden
'404':
description: Batch call not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 404 Not Found
value:
statusCode: 404
message: Batch call not found
error: Not Found
'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
bearerFormat: JWT
type: http
````