API referenceWorkflows

Create a workflow campaign

A campaign of one published version (pinned now).

A campaign of one published version (pinned now). Add contacts while it is a draft, then start it.

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.

POST

/v2/workflow-campaigns

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

Request Body

application/jsonRequired

`workflow_id`
Required
Workflow Id

The workflow.

`version`Version | null

The version to pin; the latest when omitted.

Minimum: 1

`name`Name | null

Its name.

Maximum length: 120

`max_in_flight`Max In Flight | null

The most runs in a call at a time (default 10).

Minimum: 1Maximum: 200

Response Body

201

A draft: add contacts, then start.

`id`
Required
Id

The campaign's id.

`workflow_id`
Required
Workflow Id

Its workflow.

`version`
Required
Version

The version it pinned when it was created.

`name`
Required
Name

Its name.

`status`
Required
Status

draft | awaiting_approval | running | paused | completed | cancelled.

`max_in_flight`
Required
Max In Flight

The most runs in a call (or about to place one) at a time.

`entries`
Required
Entries

Contacts added.

`refused`
Required
Refused

Contacts refused when added.

`created_by`Created By | null

Who created it.

`created_at`Created At | null

When.

`started_by`Started By | null

Who started it.

`started_at`Started At | null

When.

`approved_by`Approved By | null

Who approved the start, when it needed one.

`paused_by`Paused By | null

Who paused it last.

`stopped_by`Stopped By | null

Who cancelled it.

`completed_at`Completed At | null

When it had nothing left to do.

`updated_at`Updated At | null

When it last changed.

`totals`Any properties in WorkflowCampaignTotals

401

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

`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 organization. GET /v2/scopes reports what a 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 resource in your organization. A resource belonging to another organization answers 404, never 403.

`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 resource's current state does not allow this action.

`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 — the per-organization request rate or concurrent-call limit was reached. 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.

curl -X POST "https://api.graine.ai/v2/workflow-campaigns" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "owf_8a1d4e7c2b90f1a2b3c4d5e6",
    "version": 2,
    "name": "October renewals",
    "max_in_flight": 10
  }'

A draft: add contacts, then start.

{
  "id": "ocm_4e1f9a2b6c7d8e9f0a1b2c3d",
  "workflow_id": "owf_8a1d4e7c2b90f1a2b3c4d5e6",
  "version": 2,
  "name": "October renewals",
  "status": "running",
  "max_in_flight": 10,
  "entries": 460,
  "refused": 4,
  "created_by": "member-live-1a2b3c",
  "created_at": "2026-10-25T08:00:00+00:00",
  "started_by": "member-live-1a2b3c",
  "started_at": "2026-10-25T08:10:00+00:00",
  "approved_by": "member-live-9f8e7d",
  "paused_by": "member-live-1a2b3c",
  "stopped_by": "member-live-1a2b3c",
  "completed_at": "2026-10-26T18:00:00+00:00",
  "updated_at": "2026-10-25T08:10:00+00:00",
  "totals": {
    "queued": 120,
    "running": 2,
    "waiting": 35,
    "ended": 300,
    "failed": 3,
    "cancelled": 0,
    "success": 180,
    "failure": 90,
    "neutral": 33
  }
}

Previous

Start a workflow campaign POST

Next

Cancel a run POST