world.events

Query the append-only event log for workflow state changes, audit trails, and run cancellation.

The world.events interface provides access to the append-only event log that drives all workflow state. Runs, steps, and hooks are materialized views derived from events. Use this interface for audit trails, debugging, and programmatic run cancellation.

Import

import { getWorld } from "workflow/runtime";

const world = getWorld();
const events = world.events;

Methods

create()

Create a new event for a workflow run. Most commonly used to cancel a run.

await world.events.create(runId, { 
  eventType: "run_cancelled", 
});

Parameters:

Parameter	Type	Description
`runId`	`string`	The workflow run ID
`data`	`object`	Event data including `eventType`
`params`	`object`	Optional parameters

Returns: Event

get()

Retrieve a single event by run ID and event ID.

const event = await world.events.get(runId, eventId);

Parameters:

Parameter	Type	Description
`runId`	`string`	The workflow run ID
`eventId`	`string`	The event ID
`params`	`object`	Optional parameters

Returns: Event

list()

List events with cursor pagination.

const result = await world.events.list({ 
  runId,
  pagination: { cursor },
});

Parameters:

Parameter	Type	Description
`params.runId`	`string`	Filter events by run ID
`params.pagination.cursor`	`string`	Cursor for the next page

Returns: { data: Event[], cursor?: string }

listByCorrelationId()

List events that share a correlation ID, useful for tracing related events across runs.

const result = await world.events.listByCorrelationId({ 
  correlationId: "order-123",
});

Parameters:

Parameter	Type	Description
`params.correlationId`	`string`	The correlation ID to filter by
`params.pagination.cursor`	`string`	Cursor for the next page

Returns: { data: Event[], cursor?: string }

Event Types

Events are grouped by the entity they affect:

Run Events

Event Type	Description
`run_created`	Workflow run was created
`run_started`	Workflow run execution began
`run_completed`	Workflow run completed successfully
`run_failed`	Workflow run failed with an error
`run_cancelled`	Workflow run was cancelled

Step Events

Event Type	Description
`step_created`	Step was created
`step_started`	Step execution began
`step_completed`	Step completed successfully
`step_failed`	Step failed with an error
`step_retrying`	Step scheduled for retry

Hook Events

Event Type	Description
`hook_created`	Hook was created (workflow paused)
`hook_received`	Hook received a payload
`hook_disposed`	Hook was disposed (workflow reached terminal state)
`hook_conflict`	Hook token conflict detected

Wait Events

Event Type	Description
`wait_created`	Workflow entered a wait state (e.g., `sleep()`)
`wait_completed`	Wait state completed

Events are the append-only source of truth for all workflow state. WorkflowRun, Step, and Hook objects are materialized views derived from these events.

Examples

List Events for a Run as Audit Trail

import { getWorld } from "workflow/runtime";

export async function GET(req: Request) {
  const url = new URL(req.url);
  const runId = url.searchParams.get("runId");

  if (!runId) {
    return Response.json({ error: "runId required" }, { status: 400 });
  }

  const world = getWorld();
  const events = await world.events.list({ runId }); 

  return Response.json(events);
}

Cancel a Run via Event Creation

Cancelling a run is done by creating a run_cancelled event:

import { getWorld } from "workflow/runtime";

export async function POST(req: Request) {
  const { runId } = await req.json();

  const world = getWorld();
  await world.events.create(runId, { 
    eventType: "run_cancelled", 
  }); 

  return Response.json({ cancelled: true });
}

world.runs.cancel(runId) is a convenience wrapper around this event creation pattern. Use world.events.create() directly when you need to attach custom data to the cancellation event.

List Events by Correlation ID

Trace related events across workflow runs using a shared correlation ID:

import { getWorld } from "workflow/runtime";

const world = getWorld();
const events = await world.events.listByCorrelationId({ 
  correlationId: "order-123", 
}); 

for (const event of events.data) {
  console.log(event.eventType, event.runId, event.createdAt);
}

world.runs — Inspect runs (materialized from events)
world.steps — Inspect steps (materialized from events)
world.hooks — Inspect hooks (materialized from events)

world.events

On this page