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

# Campaigns API

> Lifecycle management for outbound calling campaigns

## Overview

A **Campaign** is the top-level container that defines *how* calls are made: which agent speaks, which phone numbers are used, when calls are allowed, and what retry logic to apply. Every [Batch](/api-reference/batches/overview) belongs to exactly one campaign and inherits its settings.

**Base URL:** `https://api.graine.ai/api/v1`

**Authentication:** All campaign endpoints require `Authorization: Bearer gat_<token>`.

## Campaign Object

```json theme={null}
{
  "campaign_id": "cmp_abc123",
  "name": "Q2 Insurance Renewals",
  "organization_id": "org_xyz",
  "agent_id": "agent_abc123",
  "status": "active",
  "phone_numbers": ["+919876543210", "+919876543211"],
  "phone_number_strategy": "round_robin",
  "working_hours_enforced": true,
  "timezone": "Asia/Kolkata",
  "working_hours": {
    "monday":    { "start": "09:00", "end": "18:00", "enabled": true },
    "tuesday":   { "start": "09:00", "end": "18:00", "enabled": true },
    "wednesday": { "start": "09:00", "end": "18:00", "enabled": true },
    "thursday":  { "start": "09:00", "end": "18:00", "enabled": true },
    "friday":    { "start": "09:00", "end": "18:00", "enabled": true },
    "saturday":  { "start": "10:00", "end": "14:00", "enabled": false },
    "sunday":    { "start": "10:00", "end": "14:00", "enabled": false }
  },
  "retry_policy": {
    "max_retries": 3,
    "strategy": "fixed",
    "cooldown_minutes": 30
  },
  "default_call_variables": {
    "language": "en",
    "product": "Health Insurance"
  },
  "metadata": {
    "concurrency_limit": 20
  }
}
```

## Campaign Fields

| Field                        | Type      | Description                                                              |
| ---------------------------- | --------- | ------------------------------------------------------------------------ |
| `campaign_id`                | string    | Unique identifier for the campaign                                       |
| `name`                       | string    | Human-readable campaign name                                             |
| `organization_id`            | string    | Owning organization. Defaults to token's org if omitted                  |
| `agent_id`                   | string    | The AI agent that makes the calls                                        |
| `status`                     | string    | Current state: `draft` · `active` · `paused` · `cancelled` · `completed` |
| `phone_numbers`              | string\[] | Outbound caller IDs to use                                               |
| `phone_number_strategy`      | string    | How to pick numbers: `round_robin` · `random` · `least_loaded`           |
| `working_hours_enforced`     | boolean   | If `true`, calls only go out within per-day windows                      |
| `timezone`                   | string    | IANA timezone for working hours (e.g. `Asia/Kolkata`)                    |
| `working_hours`              | object    | Per-day `{ start, end, enabled }` schedule                               |
| `retry_policy`               | object    | `max_retries`, `strategy` (`fixed`/`exponential`), `cooldown_minutes`    |
| `default_call_variables`     | object    | Variables merged into every contact's call (contact-level values win)    |
| `metadata.concurrency_limit` | integer   | Max concurrent outbound calls across all batches                         |

## Campaign Status Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> draft
    draft --> active : first batch started
    active --> paused : /pause
    paused --> active : /resume
    active --> cancelled : /cancel
    paused --> cancelled : /cancel
    active --> completed : all batches done
```

| Status      | Description                                  |
| ----------- | -------------------------------------------- |
| `draft`     | Created but no batches yet                   |
| `active`    | Dispatching calls                            |
| `paused`    | Temporarily stopped — resumes with `/resume` |
| `cancelled` | Hard-stopped. Terminal — cannot resume       |
| `completed` | All batches finished naturally               |

## Endpoints

<CardGroup cols={2}>
  <Card title="Create Campaign" icon="plus" href="/api-reference/campaigns/create">
    POST /campaigns/
  </Card>

  <Card title="List Campaigns" icon="list" href="/api-reference/campaigns/list">
    GET /campaigns/
  </Card>

  <Card title="Get Campaign" icon="eye" href="/api-reference/campaigns/get">
    GET /campaigns/:id
  </Card>

  <Card title="Update Campaign" icon="pen" href="/api-reference/campaigns/update">
    PATCH /campaigns/:id
  </Card>

  <Card title="Delete Campaign" icon="trash" href="/api-reference/campaigns/delete">
    DELETE /campaigns/:id
  </Card>

  <Card title="Pause / Resume / Cancel" icon="circle-pause" href="/api-reference/campaigns/lifecycle">
    Control campaign execution
  </Card>

  <Card title="Campaign Stats" icon="chart-bar" href="/api-reference/campaigns/stats">
    GET /campaigns/:id/stats
  </Card>
</CardGroup>