getWorld
Retrieves the World instance for direct access to workflow storage, queuing, and streaming backends. This function returns a World which provides low-level access to manage workflow runs, steps, events, and hooks.
Use this function when you need direct access to the underlying workflow infrastructure, such as listing all runs, querying events, or implementing custom workflow management logic.
import { getWorld } from "workflow/api";
const world = getWorld();API Signature
Parameters
This function does not accept any parameters.
Returns
Returns a World object:
| Name | Type | Description |
|---|---|---|
start | () => Promise<void> | A function that will be called to start any background tasks needed by the World implementation. For example, in the case of a queue backed World, this would start the queue processing. |
getDeploymentId | () => Promise<string> | |
queue | (queueName: __wkf_step_${string} | __wkf_workflow_${string}, message: { runId: string; traceCarrier?: Record<string, string> | undefined; requestedAt?: Date | undefined; } | { workflowName: string; ... 4 more ...; requestedAt?: Date | undefined; }, opts?: QueueOptions | undefined) => Promise<...> | Enqueues a message to the specified queue. |
createQueueHandler | (queueNamePrefix: "__wkf_step_" | "__wkf_workflow_", handler: (message: unknown, meta: { attempt: number; queueName: __wkf_step_${string} | __wkf_workflow_${string}; messageId: string & $brand<"MessageId">; }) => Promise<...>) => (req: Request) => Promise<...> | Creates an HTTP queue handler for processing messages from a specific queue. |
runs | { create(data: CreateWorkflowRunRequest): Promise<{ runId: string; deploymentId: string; workflowName: string; input: any[]; createdAt: Date; updatedAt: Date; ... 6 more ...; startedAt?: Date | undefined; } | { ...; } | { ...; } | { ...; }>; ... 5 more ...; resume(id: string, params?: ResumeWorkflowRunParams | undef... | |
steps | { create(runId: string, data: CreateStepRequest): Promise<{ runId: string; stepId: string; stepName: string; status: "pending" | "running" | "cancelled" | "completed" | "failed"; ... 8 more ...; retryAfter?: Date | undefined; }>; get(runId: string | undefined, stepId: string, params?: GetStepParams | undefined): Pro... | |
events | { create(runId: string, data: { eventType: "step_completed"; correlationId: string; eventData: { result: any; }; } | { eventType: "step_failed"; correlationId: string; eventData: { error: any; stack?: string | undefined; fatal?: boolean | undefined; }; } | ... 9 more ... | { ...; }, params?: CreateEventParams | unde... | |
hooks | { create(runId: string, data: CreateHookRequest, params?: GetHookParams | undefined): Promise<{ runId: string; hookId: string; token: string; ownerId: string; projectId: string; environment: string; createdAt: Date; metadata?: unknown; }>; get(hookId: string, params?: GetHookParams | undefined): Promise<...>; getByT... | |
writeToStream | (name: string, runId: string | Promise<string>, chunk: string | Uint8Array<ArrayBufferLike>) => Promise<void> | |
closeStream | (name: string, runId: string | Promise<string>) => Promise<void> | |
readFromStream | (name: string, startIndex?: number | undefined) => Promise<ReadableStream<Uint8Array<ArrayBufferLike>>> | |
listStreamsByRunId | (runId: string) => Promise<string[]> |
Examples
List Workflow Runs
List all workflow runs with pagination:
import { getWorld } from "workflow/api";
export async function GET(req: Request) {
const url = new URL(req.url);
const cursor = url.searchParams.get("cursor") ?? undefined;
try {
const world = getWorld();
const runs = await world.runs.list({
pagination: { cursor },
});
return Response.json(runs);
} catch (error) {
return Response.json(
{ error: "Failed to list workflow runs" },
{ status: 500 }
);
}
}Cancel a Workflow Run
Cancel a running workflow:
import { getWorld } from "workflow/api";
export async function POST(req: Request) {
const { runId } = await req.json();
if (!runId) {
return Response.json({ error: "No runId provided" }, { status: 400 });
}
try {
const world = getWorld();
const run = await world.runs.cancel(runId);
return Response.json({ status: run.status });
} catch (error) {
return Response.json(
{ error: "Failed to cancel workflow run" },
{ status: 500 }
);
}
}