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

# Batch Lifecycle

> Pause, resume, and cancel batches

## Overview

Batches can be controlled independently of their parent campaign. This is useful when you have multiple batches under one campaign and want to pause just one.

| Action     | Endpoint                    | Effect                                                 |
| ---------- | --------------------------- | ------------------------------------------------------ |
| **Pause**  | `POST /batches/{id}/pause`  | Stops new dispatches; in-flight calls finish naturally |
| **Resume** | `POST /batches/{id}/resume` | Re-triggers dispatch of remaining contacts             |
| **Cancel** | `POST /batches/{id}/cancel` | Hard-stops. Terminal — cannot be resumed               |

***

## Pause Batch

**POST** `https://api.graine.ai/api/v1/batches/{batch_id}/pause`

Sets a Redis pause flag that stops the Kafka consumer from dispatching new contacts. In-flight calls complete naturally.

### What happens internally

* `batch.status` → `paused`
* Redis pause flag set for this batch ID
* Kafka consumer skips this batch's pending contacts
* Scheduled retry / follow-up jobs are preserved

### Example Request

```bash theme={null}
curl -X POST "https://api.graine.ai/api/v1/batches/btc_xyz001/pause" \
  -H "Authorization: Bearer gat_your_token"
```

### Response 200 OK

```json theme={null}
{
  "batch_id": "btc_xyz001",
  "status": "paused",
  "message": "Batch paused successfully"
}
```

***

## Resume Batch

**POST** `https://api.graine.ai/api/v1/batches/{batch_id}/resume`

Clears the Redis pause flag and re-triggers `execute_batch` to dispatch remaining `PENDING` contacts.

### What happens internally

* `batch.status` → `in_progress`
* Redis pause flag cleared
* `execute_batch` re-invoked — publishes all `PENDING` contacts to the dispatch Kafka topic

### Example Request

```bash theme={null}
curl -X POST "https://api.graine.ai/api/v1/batches/btc_xyz001/resume" \
  -H "Authorization: Bearer gat_your_token"
```

### Response 200 OK

```json theme={null}
{
  "batch_id": "btc_xyz001",
  "status": "in_progress",
  "message": "Batch resumed successfully"
}
```

***

## Cancel Batch

**POST** `https://api.graine.ai/api/v1/batches/{batch_id}/cancel`

Hard-stops a batch. This is **terminal** — a cancelled batch cannot be resumed.

<Warning>
  Cancellation is irreversible. Any contacts in `PENDING`, `DISPATCHED`, `RETRYING`, or `FOLLOWUP_SCHEDULED` states will be marked `SKIPPED` and will never be called.
</Warning>

### What happens internally

1. `batch.status` → `CANCELLED`
2. Redis cancel flag set for the batch
3. All `PENDING`, `DISPATCHED`, `RETRYING`, and `FOLLOWUP_SCHEDULED` contacts → `SKIPPED`
4. All APScheduler retry / follow-up jobs for this batch removed from Postgres

Calls already accepted by the telephony router finish naturally.

### Example Request

```bash theme={null}
curl -X POST "https://api.graine.ai/api/v1/batches/btc_xyz001/cancel" \
  -H "Authorization: Bearer gat_your_token"
```

### Response 200 OK

```json theme={null}
{
  "batch_id": "btc_xyz001",
  "status": "cancelled",
  "message": "Batch cancelled successfully"
}
```

***

## Pause vs Cancel — Which to Use?

| Scenario                             | Recommendation                              |
| ------------------------------------ | ------------------------------------------- |
| Temporary hold while you verify data | **Pause** → Resume when ready               |
| Campaign-wide hold                   | **Pause the campaign** (pauses all batches) |
| Wrong contacts uploaded              | **Cancel** → Create a new corrected batch   |
| Hard regulatory stop                 | **Cancel**                                  |

## Next Steps

<CardGroup cols={2}>
  <Card title="Force Dispatch" icon="bolt" href="/api-reference/batches/dispatch">
    Manually re-trigger call dispatch
  </Card>

  <Card title="Debug Batch" icon="bug" href="/api-reference/batches/debug">
    Diagnose stuck or slow batches
  </Card>
</CardGroup>