Batches API

Group contacts and dispatch outbound calls under a campaign

Overview

A Batch is a group of contacts dispatched together under a Campaign. When you create a batch, Apollo immediately begins dispatching calls to every contact (or waits until scheduled_start if set).

Batches inherit the parent campaign’s retry policy, working hours, phone number strategy, and concurrency settings — but each of these can be overridden per-batch.

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

Authentication: All batch endpoints require Authorization: Bearer gat_<token>.

Batch Object

{
  "batch_id": "btc_xyz001",
  "campaign_id": "cmp_abc123",
  "organization_id": "org_xyz",
  "status": "in_progress",
  "total_contacts": 100,
  "concurrency_limit": 10,
  "scheduled_start": null,
  "counters": {
    "pending": 22,
    "dispatched": 3,
    "in_flight": 5,
    "retrying": 4,
    "completed": 58,
    "failed": 3,
    "busy": 5,
    "no_answer": 0
  },
  "created_at": "2026-05-08T09:00:00Z",
  "updated_at": "2026-05-10T08:30:00Z"
}

Batch Fields

Field	Type	Description
batch_id	string	Unique identifier
campaign_id	string	Parent campaign
organization_id	string	Owning org
status	string	Current state (see lifecycle below)
total_contacts	integer	Total contacts uploaded to this batch
concurrency_limit	integer	Max parallel calls. Inherits from campaign if not set
scheduled_start	datetime	When to start dispatching. null = immediately
counters	object	Live real-time contact status breakdown
max_retries_override	integer	Overrides campaign.retry_policy.max_retries for this batch only

Batch Status Lifecycle

Status	Description
pending	Waiting for scheduled_start
in_progress	Actively dispatching calls
paused	Stopped — resumes with /resume
completed	All contacts reached a terminal state
cancelled	Hard-stopped. Terminal
expired	Passed end window without completing

Contact Status Values

Each contact within a batch can be in one of these states:

Status	Description
pending	Waiting to be dispatched
dispatched	Published to Kafka — call is being placed
in_progress	Call actively ringing or in conversation
retrying	Scheduled for a retry attempt
followup_scheduled	A follow-up call is scheduled
completed	Call was answered and completed
failed	Call failed (network/provider error)
busy	Line was busy
no_answer	No answer within timeout
skipped	Manually skipped — no further attempts
max_retries_reached	Exhausted all retry attempts

Endpoints

Create Batch

POST /batches/

List Batches

GET /batches/

Get Batch

GET /batches/:id

List Batch Contacts

GET /batches/:id/contacts

Export CSV

GET /batches/:id/export.csv

Pause / Resume / Cancel

Control batch execution

Force Dispatch

POST /batches/:id/dispatch

Debug Batch

GET /batches/:id/debug