> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simz.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simz.com/_mcp/server.

# Batch Management

> Check batch status and pause, resume, or cancel accepted lead backlog.

When you submit leads, SimZ creates a batch and returns a `batchId`. Save that value in your CRM or application so you can check progress and control dialing later.

## Check batch status

Use `GET /api/lead-receive-service/agent/batches/{batchId}` to inspect the batch summary and per-entry call progress.

```bash
curl "https://api.simz.com/api/lead-receive-service/agent/batches/batch_123" \
  -H "X-Company-API-Key: sk_comp_example"
```

The response includes batch status, accepted and rejected counts, and entry-level call fields such as `status`, `callSid`, and `callDuration`.

## Pause a batch

`POST /api/lead-receive-service/agent/batches/{batchId}/pause` pauses only the accepted backlog that has not yet been dialed.

* Dispatchable batches (`queued` or `processing`) can be paused.
* Leads already in `accepted` status and waiting to dial are held.
* Calls already accepted by core may continue and remain traceable.

```bash
curl -X POST "https://api.simz.com/api/lead-receive-service/agent/batches/batch_123/pause" \
  -H "X-Company-API-Key: sk_comp_example"
```

## Resume a batch

`POST /api/lead-receive-service/agent/batches/{batchId}/resume` resumes a paused batch that still has accepted backlog.

* Only batches in `paused` status can be resumed.
* If nothing has been dialed yet, the batch returns to `queued`.
* If dialing already started, the batch returns to `processing`.

## Cancel a batch

`POST /api/lead-receive-service/agent/batches/{batchId}/cancel` cancels accepted leads that have not yet been dialed.

* Accepted backlog entries are cancelled and will not be dialed.
* The batch is marked `cancelled` even when no accepted backlog remains (`cancelledEntries` may be `0`).
* Calls already accepted by core may still complete and remain traceable.
* You can optionally pass a `reason` in the request body. SimZ stores it on cancelled entries and defaults to `cancelled_by_client` when omitted.

```bash
curl -X POST "https://api.simz.com/api/lead-receive-service/agent/batches/batch_123/cancel" \
  -H "Content-Type: application/json" \
  -H "X-Company-API-Key: sk_comp_example" \
  -d '{"reason":"cancelled_by_client"}'
```

## Pause all or cancel all

Use company-wide controls when you need to stop multiple active batches at once.

| Endpoint                                                  | Behavior                                                                          |
| --------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `POST /api/lead-receive-service/agent/batches/pause-all`  | Pauses every dispatchable batch for your company that still has accepted backlog. |
| `POST /api/lead-receive-service/agent/batches/cancel-all` | Cancels accepted backlog across every controllable batch for your company.        |

Both endpoints accept an optional JSON body:

```json
{
  "agentId": "agent_123",
  "reason": "cancelled_by_client"
}
```

* `agentId` scopes the operation to one agent. Omit it to affect all matching batches for your company.
* `reason` is optional, only applies to `cancel-all`, and defaults to `cancelled_by_client` when omitted.

**Skip behavior:** neither endpoint fails the whole request when individual batches do not qualify.

* `pause-all` skips batches that are not dispatchable (`queued` or `processing`), already paused, or have no accepted backlog.
* `cancel-all` considers controllable batches (`queued`, `processing`, or `paused`) and skips any batch where no accepted entries were cancelled.

## Common errors

| Code                    | HTTP status | Meaning                                                                     |
| ----------------------- | ----------- | --------------------------------------------------------------------------- |
| `BATCH_NOT_FOUND`       | `404`       | Batch does not exist.                                                       |
| `FORBIDDEN`             | `403`       | Batch belongs to another company.                                           |
| `BATCH_NOT_PAUSABLE`    | `409`       | Batch is not in a dispatchable state (`queued` or `processing`).            |
| `BATCH_NOT_RESUMABLE`   | `409`       | Batch is not paused.                                                        |
| `BATCH_NOT_CANCELLABLE` | `409`       | Batch is terminal or not in `paused`, `queued`, or `processing` status.     |
| `NO_ACCEPTED_BACKLOG`   | `409`       | No accepted leads remain waiting to dial. Applies to pause and resume only. |

See [Errors and Rate Limits](/lead-receive-api/errors-and-rate-limits) for submission errors and retry guidance.