Graine AI
API referenceCampaigns

Cancel a campaign

Hard-stop a campaign.

Hard-stop a campaign. This cannot be undone.

Unlike /pause, which keeps the work, cancelling throws it away:

  • every batch still running is cancelled;
  • every contact still waiting, retrying or scheduled for a follow-up is marked skipped, so the counters stop claiming work that will never happen;
  • every pending retry, follow-up and batch-start job is removed, so nothing wakes up later and dials;
  • the campaign becomes cancelled, which is terminal — /resume on it answers 409.

What cancelling cannot do: calls already connected finish naturally at the carrier. No new call is placed, and no retry or follow-up is scheduled for them when they end.

A campaign that is already cancelled, completed, expired or archived answers 409.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

POST
/v2/campaigns/{campaign_id}/cancel
/v2/campaigns/31ff3ea9-8bb5-433f-868f-286ac3c31328/cancel

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

organization_idOrganization Id

Must match the organisation the API key belongs to.

Response Body

200

What was stopped: the batches, the contacts and the scheduled jobs.

campaign_id
Required
Campaign Id

Campaign identifier.

statusStatus

Always 'cancelled'. Terminal — the campaign will not resume.

Default: "cancelled"

batches_cancelledBatches Cancelled

The batches that were still running and have now been stopped.

contacts_skippedContacts Skipped

Undialled and retrying contacts marked skipped, so the counters tell the truth.

Default: 0

scheduled_jobs_cancelledScheduled Jobs Cancelled

Pending retry, follow-up and batch-start jobs removed, so nothing wakes up later.

Default: 0

calls_in_progress_note
Required
Calls In Progress Note

What cancel cannot do: calls already connected finish naturally.

400

1000 — malformed or contradictory input: an unknown timezone, a working-hours window that is not 24-hour HH:MM, an end_time at or before start_time, 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.

409

1201 — the campaign's state does not allow this action: resuming or cancelling a campaign that has already been cancelled, completed, expired or archived; editing a cancelled campaign; or deleting one that still has batches running.

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; 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 — the agent service 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 — the agent service 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 POST "https://api.graine.ai/v2/campaigns/31ff3ea9-8bb5-433f-868f-286ac3c31328/cancel?organization_id=string" \
  -H "Authorization: Bearer <token>"

What was stopped: the batches, the contacts and the scheduled jobs.

{
  "campaign_id": "31ff3ea9-8bb5-433f-868f-286ac3c31328",
  "status": "cancelled",
  "batches_cancelled": [
    "7d1f0a52-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
  ],
  "contacts_skipped": 2100,
  "scheduled_jobs_cancelled": 44,
  "calls_in_progress_note": "Calls already connected finish naturally; no new calls are placed."
}

Previous

List campaigns GET

Next

Pause a campaign POST