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

curl -X POST "https://api.graine.ai/api/v1/batches/btc_xyz001/pause" \
  -H "Authorization: Bearer gat_your_token"

Response 200 OK

{
  "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

curl -X POST "https://api.graine.ai/api/v1/batches/btc_xyz001/resume" \
  -H "Authorization: Bearer gat_your_token"

Response 200 OK

{
  "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.

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

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

curl -X POST "https://api.graine.ai/api/v1/batches/btc_xyz001/cancel" \
  -H "Authorization: Bearer gat_your_token"

Response 200 OK

{
  "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

Force Dispatch

Manually re-trigger call dispatch

Debug Batch

Diagnose stuck or slow batches