Campaign Lifecycle

Pause, resume, and cancel campaigns

Overview

Three actions control the execution state of a campaign and all its batches:

Action	Endpoint	Effect
Pause	POST /campaigns/{id}/pause	Stops new calls; in-flight calls finish naturally
Resume	POST /campaigns/{id}/resume	Restarts dispatching from where it left off
Cancel	POST /campaigns/{id}/cancel	Hard-stops everything — terminal, no resume possible

---

Pause Campaign

POST https://api.graine.ai/api/v1/campaigns/{campaign_id}/pause

Pauses the campaign and all its IN_PROGRESS batches. No new calls go out. In-flight calls complete naturally.

What happens internally

• Campaign status → paused
• All IN_PROGRESS batches → paused
• A Redis pause flag is set per batch, stopping the Kafka consumer from dispatching further contacts
• Scheduled retry/followup jobs are preserved (they will fire again on resume)

Example Request

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

Response 200 OK

{
  "campaign_id": "cmp_abc123",
  "status": "paused",
  "message": "Campaign paused successfully"
}

---

Resume Campaign

POST https://api.graine.ai/api/v1/campaigns/{campaign_id}/resume

Resumes a paused campaign and all its PAUSED batches. Pending contacts start dispatching immediately (respecting working hours and concurrency limits).

What happens internally

• Campaign status → active
• All PAUSED batches → in_progress
• Redis pause flags are cleared
• execute_batch is re-triggered for each batch to drain remaining PENDING contacts

Example Request

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

Response 200 OK

{
  "campaign_id": "cmp_abc123",
  "status": "active",
  "message": "Campaign resumed successfully"
}

---

Cancel Campaign

POST https://api.graine.ai/api/v1/campaigns/{campaign_id}/cancel

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

Cancel is irreversible. Use Pause if you want to stop temporarily and resume later.

What happens internally

1. All in-flight batches are cancelled (Redis cancel flag set + batch.status = CANCELLED)
2. All contacts with status PENDING, DISPATCHED, RETRYING, or FOLLOWUP_SCHEDULED are marked SKIPPED
3. All APScheduler retry/followup/batch-start jobs for these batches are removed from Postgres
4. Campaign status → cancelled

Calls already accepted by the telephony router finish naturally. No new outbound calls go out after this point.

Example Request

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

Response 200 OK

{
  "campaign_id": "cmp_abc123",
  "status": "cancelled",
  "message": "Campaign cancelled successfully"
}

---

Pause vs Cancel — Which to Use?

Scenario	Recommendation
Temporary halt (lunch break, holiday)	Pause → Resume later
Agent script needs fixing	Pause → Update agent → Resume
Compliance hold on specific numbers	Pause → Skip affected contacts → Resume
Campaign completed early / wrong contacts uploaded	Cancel
Hard regulatory stop — never call these contacts again	Cancel

Next Steps

Get Campaign Stats

Monitor live progress

Manage Individual Batches

Pause/cancel at the batch level