Graine AI
API referenceWorkflows

Start a run

Start one contact's run on a published version.

Start one contact's run on a published version. The wallet and every agent the version calls are asked first (402; 409 with 1202 / 1203). A contact already running this workflow (by reference_id, default its number) is refused (409).

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/workflows/{workflow_id}/runs
/v2/workflows/owf_8a1d4e7c2b90f1a2b3c4d5e6/runs

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

Request Body

application/jsonRequired

contact
Required
Contact

The contact: mobile_number, and the fields the workflow's start step declares (reference_id, name and email are always accepted).

versionVersion | null

The version to run; the latest when omitted.

Minimum: 1

Path Parameters

workflow_id
Required
Workflow Id

The workflow's id.

Response Body

201

The run, moving.

id
Required
Id

The run's id.

workflow_id
Required
Workflow Id

Its workflow.

version
Required
Version

The version it runs.

campaign_idCampaign Id | null

Its campaign, if any.

sourceSource | null

How it started: dashboard | api | campaign | trigger.

status
Required
Status

queued | running | waiting | ended | failed | cancelled.

nodeNode | null

The step it is on.

outcomeOutcome | null

success | failure | neutral, once ended.

labelLabel | null

The ending's label.

termination_reasonTermination Reason | null

Why it ended.

warnings
Required
Warnings

Optional values that were missing.

reference_idReference Id | null

The contact's reference.

waitAny properties in WorkflowRunWait

created_atCreated At | null

When it started.

updated_atUpdated At | null

When it last moved.

ended_atEnded At | null

When it ended.

last_eventLast Event | null

Its latest step, on a list.

variables
Required
Variables

entry, run, call, extraction, response, callback, state, node.

timeline
Required
Timeline

Every step, oldest first (the last 500).

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.

402

1400 — your credit balance cannot fund this call. Top up and retry.

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.

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.

curl -X POST "https://api.graine.ai/v2/workflows/owf_8a1d4e7c2b90f1a2b3c4d5e6/runs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "mobile_number": "+919876543210",
      "name": "Asha",
      "plan": "gold"
    },
    "version": 2
  }'

The run, moving.

{
  "id": "oex_2c9e8f1a7b3d4c5e6f7a8b9c",
  "workflow_id": "owf_8a1d4e7c2b90f1a2b3c4d5e6",
  "version": 2,
  "campaign_id": "ocm_4e1f9a2b6c7d8e9f0a1b2c3d",
  "source": "api",
  "status": "waiting",
  "node": "call",
  "outcome": "success",
  "label": "qualified",
  "termination_reason": "ended",
  "warnings": 0,
  "reference_id": "lead-4471",
  "wait": {
    "kind": "call",
    "node": "call",
    "until": "2026-10-25T10:00:00+00:00",
    "held": "calling_window",
    "reason": "insufficient_credits",
    "call_execution_id": "6f1c2d3e-4b5a-6978-c0d1-e2f3a4b5c6d7",
    "channel": "app",
    "due_at": "2026-10-25T12:30:00+00:00"
  },
  "created_at": "2026-10-25T09:40:00+00:00",
  "updated_at": "2026-10-25T09:41:00+00:00",
  "ended_at": "2026-10-25T09:52:00+00:00",
  "last_event": {
    "at": "2026-10-25T09:41:00+00:00",
    "kind": "waiting",
    "node": "call",
    "wait": "call"
  },
  "variables": {
    "entry": {
      "mobile_number": "+919876543210",
      "plan": "gold"
    },
    "call": {
      "status": "completed",
      "duration_s": 42
    }
  },
  "timeline": [
    {
      "at": "2026-10-25T09:40:00+00:00",
      "kind": "entered"
    }
  ]
}

Previous

Publish a workflow POST

Next

Check a workflow POST