Audit Log

Stateway maintains a unified audit log that records both API-level and engine-level events in a single sequence. Every action — from creating a process instance to the engine resolving a gateway — appears in this log.

Entry structure

Each audit log entry contains:

Field	Type	Description
id	UUID	Unique entry identifier
actorType	string	Who performed the action (see below)
action	string	The action that occurred
payload	object	Action-specific details
createdAt	ISO 8601	When the action occurred

Actor types

actorType	Description
api_key	An action triggered by an API call from your application
system	An internal system action (e.g., webhook dispatch)
timer	A timer job that fired and advanced a process
engine	An internal engine action (element transitions, gateway decisions, etc.)

Engine events

When the engine executes a process, it emits events with actorType: "engine". These events provide granular traceability of the execution path.

action	When emitted
element.entered	A token arrives at any BPMN element
element.completed	A token leaves any BPMN element
gateway.resolved	An Exclusive or Inclusive Gateway resolves and a path is taken
parallel.joined	A Parallel Gateway receives all expected tokens
timer.fired	A timer job fires and advances the process
boundary.triggered	A Boundary Event activates (interrupting or non-interrupting)
instance.engine_completed	All End Events have been reached
business_rule.evaluated	A BusinessRuleTask completes a DMN evaluation

Gateway decisions

The gateway.resolved event contains the path taken and a snapshot of the process variables at the moment of the decision:

{
  "id": "log_01j...",
  "actorType": "engine",
  "action": "gateway.resolved",
  "payload": {
    "element_id": "gw_credit_check",
    "taken_flows": ["flow_approved"],
    "variables_snapshot": {
      "credit_score": 720,
      "amount_requested": 50000,
      "applicant_id": "cust_abc"
    }
  },
  "createdAt": "2026-05-19T10:05:02Z"
}

variables_snapshot is captured at the instant the decision is made. It is capped at 64 KB; if the process variables exceed this limit, the snapshot stores only the variable names (values are replaced with "<truncated>"). Fields ending in _binary, _blob, or _base64 are always excluded.

Retrieving instance history

GET /v1/instances/:id/history returns the full audit trail for a specific process instance, ordered by createdAt ascending.

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

{
  "data": [
    {
      "id": "log_01j...",
      "actorType": "api_key",
      "action": "instance.created",
      "payload": { "correlationId": "order-789" },
      "createdAt": "2026-05-19T10:05:00Z"
    },
    {
      "id": "log_02j...",
      "actorType": "engine",
      "action": "element.entered",
      "payload": { "element_id": "start_event", "element_type": "startEvent" },
      "createdAt": "2026-05-19T10:05:00Z"
    },
    {
      "id": "log_03j...",
      "actorType": "engine",
      "action": "gateway.resolved",
      "payload": {
        "element_id": "gw_credit_check",
        "taken_flows": ["flow_approved"],
        "variables_snapshot": { "credit_score": 720 }
      },
      "createdAt": "2026-05-19T10:05:02Z"
    }
  ]
}

Filter parameters

Parameter	Type	Description
actor_type	string	Filter by actor: api_key, system, timer, engine
action	string	Filter by action name, e.g. gateway.resolved
from	ISO 8601	Return entries at or after this time
to	ISO 8601	Return entries before this time
page	integer	Page number (default: 1)
page_size	integer	Entries per page (default: 50, max: 200)

Filter example: gateway decisions only

curl "https://api.stateway.io/v1/instances/inst_01j.../history?actor_type=engine&action=gateway.resolved" \
  -H "X-API-Key: sw_live_your_key"

This returns only the gateway resolution events for the instance, each with its variables_snapshot.