Skip to main content

Instances

A process instance is a running execution of a process definition. This guide covers how to start, monitor, suspend, resume, and terminate instances via the API.

Instance Status​

StatusDescription
runningThe instance is actively executing
completedThe instance reached an end event
errorAn unhandled error occurred during execution
suspendedExecution is paused
terminatedStopped before completion

Starting an Instance​

Launch a new instance of a process definition:

Request:

curl -X POST https://api.stateway.io/v1/instances \
  -H "X-API-Key: sw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "definition_key": "expense-approval",
    "variables": {
      "amount": 1500,
      "requester": "john@acme.com"
    }
  }'

Response:

{
  "data": {
    "id": "inst_01j...",
    "definition_key": "expense-approval",
    "definition_version": 1,
    "status": "running",
    "variables": {
      "amount": 1500,
      "requester": "john@acme.com"
    },
    "started_at": "2026-04-26T12:00:00.000Z"
  }
}

Pass an optional correlation_id to link the instance to an external entity (e.g., an order ID). You can later filter by it:

Request:

curl -X POST https://api.stateway.io/v1/instances \
  -H "X-API-Key: sw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "definition_key": "expense-approval",
    "correlation_id": "order-789",
    "variables": { "amount": 1500 }
  }'

Response:

{
  "data": {
    "id": "inst_01j...",
    "definition_key": "expense-approval",
    "status": "running",
    "correlation_id": "order-789",
    "variables": { "amount": 1500 },
    "started_at": "2026-04-26T12:00:00.000Z"
  }
}

Listing Instances​

Request:

curl https://api.stateway.io/v1/instances \
  -H "X-API-Key: sw_live_your_key"

Response:

{
  "data": [
    {
      "id": "inst_01j...",
      "definition_key": "expense-approval",
      "status": "running",
      "started_at": "2026-04-26T12:00:00.000Z"
    }
  ]
}

Available filters:

# Filter by status
curl "https://api.stateway.io/v1/instances?status=running" \
  -H "X-API-Key: sw_live_your_key"

# Filter by correlation_id
curl "https://api.stateway.io/v1/instances?correlation_id=order-789" \
  -H "X-API-Key: sw_live_your_key"

Pagination​

GET /v1/instances is paginated with page/page_size query parameters:

curl "https://api.stateway.io/v1/instances?page=2&page_size=20" \
  -H "X-API-Key: sw_live_your_key"
  • page_size: results per page. Default 50, maximum 200. Requests without page/page_size get the default page size — the response is not the full unfiltered result set.
  • page: 1-indexed page number. Default 1.
  • Results are ordered by started_at descending (most recent first).
  • A page_size above 200 returns 400 VALIDATION_ERROR naming the offending field.

This is offset-based pagination (same trade-offs as any LIMIT/OFFSET query — see Search: Pagination for why the dedicated /v1/instances/search endpoint uses cursor pagination instead). For simple tenant-scoped listing this is fine; for large-scale iteration over search results, use /v1/instances/search.

Getting Instance Details​

Request:

curl https://api.stateway.io/v1/instances/{instance_id} \
  -H "X-API-Key: sw_live_your_key"

Response:

{
  "data": {
    "id": "inst_01j...",
    "definition_key": "expense-approval",
    "status": "running",
    "variables": {
      "amount": 1500,
      "requester": "john@acme.com"
    },
    "started_at": "2026-04-26T12:00:00.000Z"
  }
}

Instance Tokens​

Get the current execution tokens — shows where the process is paused:

Request:

curl https://api.stateway.io/v1/instances/{instance_id}/tokens \
  -H "X-API-Key: sw_live_your_key"

Response:

{
  "data": [
    {
      "id": "tok_01j...",
      "element_id": "review-expense",
      "element_type": "userTask",
      "status": "waiting",
      "arrived_at": "2026-04-26T12:01:00.000Z"
    }
  ]
}

Token status values:

StatusMeaning
activeToken is currently executing
waitingToken is paused (e.g., at a userTask or timerEvent)
completedToken has finished
deadToken was killed by an error or recovery operation and can no longer advance

Instance Variables​

Request:

curl https://api.stateway.io/v1/instances/{instance_id}/variables \
  -H "X-API-Key: sw_live_your_key"

Response:

{
  "data": {
    "amount": 1500,
    "requester": "john@acme.com"
  }
}

Updating Variables​

Merge new or updated values into the instance variables:

Request:

curl -X POST https://api.stateway.io/v1/instances/{instance_id}/variables \
  -H "X-API-Key: sw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "approved": true,
      "approvedAmount": 1500
    }
  }'

Response:

{
  "data": {
    "amount": 1500,
    "requester": "john@acme.com",
    "approved": true,
    "approvedAmount": 1500
  }
}
warning

Updating variables does not automatically advance the process. Use this for data correction or external system updates.

Instance Lifecycle Operations​

Suspend​

Pause execution (tokens remain in place):

Request:

curl -X POST https://api.stateway.io/v1/instances/{instance_id}/suspend \
  -H "X-API-Key: sw_live_your_key"

Response:

{
  "data": {
    "id": "inst_01j...",
    "status": "suspended"
  }
}

Resume​

Resume a suspended instance:

Request:

curl -X POST https://api.stateway.io/v1/instances/{instance_id}/resume \
  -H "X-API-Key: sw_live_your_key"

Response:

{
  "data": {
    "id": "inst_01j...",
    "status": "running"
  }
}

Terminate​

Force-stop an instance before completion:

Request:

curl -X POST https://api.stateway.io/v1/instances/{instance_id}/terminate \
  -H "X-API-Key: sw_live_your_key"

Response:

{
  "data": {
    "id": "inst_01j...",
    "status": "terminated"
  }
}
warning

Termination is irreversible. The instance status changes to terminated and no further execution occurs. All pending and claimed human tasks for that instance are automatically cancelled.

Instance Lifecycle Diagram​

  POST /v1/instances
         │
         ▼
    ┌─────────┐   suspend    ┌───────────┐
    │ running │────────────→ │ suspended │
    │         │ ←────────────┤           │
    └────┬────┘   resume     └───────────┘
         │
         ├─ end event  ────→ ┌───────────┐
         │                   │ completed │
         │                   └───────────┘
         │
         ├─ unhandled  ────→ ┌───────────┐
         │  error            │   error   │
         │                   └───────────┘
         │
         └─ terminate ─────→ ┌────────────┐
                              │ terminated │
                              └────────────┘

Best Practices​

  • Poll tokens after starting — use /instances/{id}/tokens to track process position
  • Check status before acting — a task may already be completed by another system
  • Use variables for context — include all data needed by human tasks at start time
  • Suspend before bulk updates — prevents race conditions when updating variables
  • Set up webhooks — receive events instead of polling for status changes