Workflow Events

Retrieve the ordered sequence of events that make up a workflow's execution history. Events are the fundamental unit of the workflow event-sourcing model — the current state of any workflow can always be reconstructed by replaying its event log from the beginning.

Endpoint

GET /api/v1/workflows/{workflowId}/events

Required Role

MEMBER

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes
X-Tenant-ID	Tenant identifier string	Yes

Path Parameters

Parameter	Type	Description
workflowId	string	The unique identifier of the workflow.

Query Parameters

Parameter	Type	Required	Description
fromSeq	integer	No	Return only events with a sequence number greater than or equal to this value. Defaults to 0 (all events). Use this to poll for new events after a known position without re-fetching the full history.

Response Body

The response is a JSON array of event objects, ordered by sequence number ascending.

[
  {
    "sequence": 1,
    "workflowId": "wf-abc123",
    "eventType": "WORKFLOW_STARTED",
    "payload": {},
    "occurredAt": "2024-01-15T10:30:00Z"
  },
  {
    "sequence": 2,
    "workflowId": "wf-abc123",
    "eventType": "POLICY_EVALUATED",
    "payload": {
      "policyModule": "Loan.Approval",
      "policyFunction": "isEligible",
      "result": true,
      "executionTimeMs": 6
    },
    "occurredAt": "2024-01-15T10:30:00Z"
  },
  {
    "sequence": 3,
    "workflowId": "wf-abc123",
    "eventType": "WORKFLOW_COMPLETED",
    "payload": {
      "finalResult": true
    },
    "occurredAt": "2024-01-15T10:30:01Z"
  }
]

Field	Type	Description
sequence	integer	Monotonically increasing sequence number within the workflow. Gaps indicate missing or compacted events.
workflowId	string	Identifier of the owning workflow (mirrors the path parameter).
eventType	string	Event classification (e.g. WORKFLOW_STARTED, POLICY_EVALUATED, WORKFLOW_COMPLETED, COMPENSATION_STARTED).
payload	object	Event-specific data. Structure varies by eventType.
occurredAt	string	ISO 8601 timestamp when the event was recorded.

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded. Returns an array (may be empty if fromSeq is beyond the last recorded event).
400 Bad Request	Malformed fromSeq parameter.
401 Unauthorized	Missing or invalid bearer token.
403 Forbidden	Token is valid but the caller lacks the MEMBER role, or the workflow belongs to a different tenant.
404 Not Found	No workflow found with the given workflowId.
500 Internal Server Error	Unexpected engine failure.

Examples

curl

# Fetch all events for a workflow
curl -X GET "https://policy.aster-lang.dev/api/v1/workflows/wf-abc123/events" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-ID: acme-corp"

# Poll for new events after sequence 42
curl -X GET "https://policy.aster-lang.dev/api/v1/workflows/wf-abc123/events?fromSeq=43" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-ID: acme-corp"

JavaScript

const workflowId = 'wf-abc123';

// Fetch all events
const response = await fetch(
  `https://policy.aster-lang.dev/api/v1/workflows/${workflowId}/events`,
  {
    headers: {
      Authorization: 'Bearer <token>',
      'X-Tenant-ID': 'acme-corp',
    },
  }
);

const events = await response.json();

// Poll for new events after a known sequence
async function pollNewEvents(workflowId, lastSeq) {
  const params = new URLSearchParams({ fromSeq: String(lastSeq + 1) });
  const res = await fetch(
    `https://policy.aster-lang.dev/api/v1/workflows/${workflowId}/events?${params}`,
    {
      headers: {
        Authorization: 'Bearer <token>',
        'X-Tenant-ID': 'acme-corp',
      },
    }
  );
  return res.json();
}