Graine AI
API referenceCampaigns

List a campaign's batches

Every batch dialling under this campaign, newest first.

Every batch dialling under this campaign, newest first.

A campaign created by POST /v2/campaigns with contacts holds exactly one batch: those contacts. Each such request creates a NEW campaign rather than adding to an existing one, so a second list is a second campaign, not a second entry here. A campaign holds several batches only when further lists are added to it outside POST /v2/campaigns; every one of them is listed.

counts is computed from the contacts on every read, so it is always current. A contact that answered once stays in completed even if a later follow-up fails, which is the rule the dashboard uses, so the two never disagree.

A campaign belonging to another organisation answers 404 before any batch is read.

Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

GET
/v2/campaigns/{campaign_id}/batches
/v2/campaigns/31ff3ea9-8bb5-433f-868f-286ac3c31328/batches?status=in_progress&page=1&page_size=20

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Path Parameters

campaign_id
Required
Campaign Id

Campaign identifier.

Query Parameters

statusStatus

Batch status: created, scheduled, pending, in_progress, paused, calls_dispatched, completed, failed, cancelled, expired.

organization_idOrganization Id

Must match the organisation the API key belongs to.

pagePage

1-indexed page number (max 10000 — narrow the window instead)

Default: 1Minimum: 1Maximum: 10000

page_sizePage Size

Items per page (max 100)

Default: 20Minimum: 1Maximum: 100

Response Body

200

A page of batches, newest first.

data
Required
Data

Batches under this campaign, newest first.

pagination
Required
Pagination

page, page_size, total, total_pages, has_more.

400

1000 — malformed or contradictory input: an unknown status filter or timezone, a start_time or end_time without a timezone offset, an end_time at or before start_time or more than 365 days ahead, or an empty patch body. 1002 — a required parameter is missing.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such campaign, or no such agent, in this organisation. A campaign belonging to another organisation answers 404, never 403, so ids cannot be probed.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation — an unknown field, a value out of range, or a working-hours time that is not 24-hour HH:MM. The message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — per-organisation rate limit exceeded. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — a service this endpoint depends on is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

504

1502 — a service this endpoint depends on did not respond in time.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X GET "https://api.graine.ai/v2/campaigns/31ff3ea9-8bb5-433f-868f-286ac3c31328/batches?status=in_progress&organization_id=string&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

A page of batches, newest first.

{
  "data": [
    {
      "batch_id": "7d1f0a52-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
      "name": "UP list, week 2",
      "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
      "campaign_id": "31ff3ea9-8bb5-433f-868f-286ac3c31328",
      "status": "in_progress",
      "total_contacts": 3000,
      "counts": {
        "pending": 2100,
        "in_flight": 12,
        "completed": 780,
        "failed": 108,
        "do_not_call": 0,
        "total": 3000
      },
      "scheduled_at": "2026-08-27T05:30:00.000Z",
      "started_at": "2026-08-27T05:30:04.118Z",
      "completed_at": "2026-08-27T14:02:51.907Z",
      "created_at": "2026-08-26T10:48:18.239Z",
      "updated_at": "2026-08-26T10:51:46.003Z",
      "metadata": {
        "crm_campaign": "UP-Q3"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_more": true
  }
}

Previous

List audit events GET

Next

Get a campaign's live progress GET