Workflow State

Retrieve the current materialized state of a workflow. The state is derived from the workflow's event log and may be supplemented by a periodic snapshot to accelerate reads. Use this endpoint when you need the latest status and result without fetching the full event history.

Endpoint

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

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.

Response Body

{
  "workflowId": "wf-abc123",
  "status": "COMPLETED",
  "lastEventSeq": 5,
  "result": {
    "eligible": true,
    "approvedAmount": 25000
  },
  "snapshot": {
    "intermediateState": "..."
  },
  "snapshotSeq": 3,
  "createdAt": "2024-01-15T10:29:58Z",
  "updatedAt": "2024-01-15T10:30:01Z"
}

Field	Type	Description
workflowId	string	Unique identifier of the workflow.
status	string	Current lifecycle status. See Status Values below.
lastEventSeq	integer	Sequence number of the most recently applied event.
result	any | null	Final output produced by the workflow. Populated once status reaches a terminal state (COMPLETED, FAILED, COMPENSATED, COMPENSATION_FAILED). null for non-terminal workflows.
snapshot	object | null	Opaque intermediate state snapshot used to accelerate event replay. null if no snapshot has been taken yet.
snapshotSeq	integer | null	Sequence number at which the snapshot was taken. null when snapshot is null.
createdAt	string	ISO 8601 timestamp when the workflow was created.
updatedAt	string	ISO 8601 timestamp of the most recent state change.

Status Values

Status	Terminal	Description
READY	No	Workflow has been created but not yet started.
RUNNING	No	Workflow is actively executing.
COMPLETED	Yes	Workflow finished successfully. result is populated.
FAILED	Yes	Workflow terminated due to an unrecoverable error.
COMPENSATING	No	Workflow is executing compensation (rollback) steps.
COMPENSATED	Yes	Compensation completed successfully.
COMPENSATION_FAILED	Yes	Compensation steps also failed. Manual intervention may be required.

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded. Returns the current workflow state.
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

curl -X GET "https://policy.aster-lang.dev/api/v1/workflows/wf-abc123/state" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-ID: acme-corp"

JavaScript

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

const state = await response.json();

if (state.status === 'COMPLETED') {
  console.log('Workflow result:', state.result);
} else if (state.status === 'FAILED') {
  console.error('Workflow failed. Last event sequence:', state.lastEventSeq);
}

Example Response

{
  "workflowId": "wf-abc123",
  "status": "COMPLETED",
  "lastEventSeq": 5,
  "result": {
    "eligible": true,
    "approvedAmount": 25000
  },
  "snapshot": null,
  "snapshotSeq": null,
  "createdAt": "2024-01-15T10:29:58Z",
  "updatedAt": "2024-01-15T10:30:01Z"
}