> ## 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.

# 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

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

### Response 200 OK

```json theme={null}
{
  "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

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

### Response 200 OK

```json theme={null}
{
  "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.

<Warning>
  Cancel is irreversible. Use Pause if you want to stop temporarily and resume later.
</Warning>

### 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

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

### Response 200 OK

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Get Campaign Stats" icon="chart-bar" href="/api-reference/campaigns/stats">
    Monitor live progress
  </Card>

  <Card title="Manage Individual Batches" icon="layer-group" href="/api-reference/batches/overview">
    Pause/cancel at the batch level
  </Card>
</CardGroup>