Interface: WorkflowRunsClient

Workflow runs: start, read, list and summarise; a run's step trace and related records; cancelling and replaying a run; and the admin-only event history.

Properties

cancel

cancel: (id, body) => Promise<{
  context: z.ZodRecord<z.ZodString, z.ZodUnknown>;
  correlationId?: string | null;
  createdAt: Date;
  currentStepId?: string | null;
  decisionId?: string | null;
  definitionId: string;
  definitionKey: string;
  definitionVersion: number;
  error?: string | null;
  finishedAt?: Date | null;
  id: string;
  replayOf?:   | {
     runId: string;
     stepId: string;
   }
     | null;
  startedAt: Date;
  status:   | "failed"
     | "completed"
     | "running"
     | "waiting_collection"
     | "waiting_manual"
     | "waiting_callback"
     | "cancelled";
  subjectId: string;
  temporalRunId?: string | null;
  temporalWorkflowId: string;
  tenantId: string;
  traceId?: string | null;
  trigger: "console" | "api" | "replay";
  updatedAt: Date;
}>;

Cancels an active run (runs:write); 409 run_finished once it has finished.

Parameters

id

string

body

reason

string

Returns

Promise<{ context: z.ZodRecord<z.ZodString, z.ZodUnknown>; correlationId?: string | null; createdAt: Date; currentStepId?: string | null; decisionId?: string | null; definitionId: string; definitionKey: string; definitionVersion: number; error?: string | null; finishedAt?: Date | null; id: string; replayOf?: | { runId: string; stepId: string; } | null; startedAt: Date; status: | "failed" | "completed" | "running" | "waiting_collection" | "waiting_manual" | "waiting_callback" | "cancelled"; subjectId: string; temporalRunId?: string | null; temporalWorkflowId: string; tenantId: string; traceId?: string | null; trigger: "console" | "api" | "replay"; updatedAt: Date; }>

---

get

get: (id) => Promise<{
  context: z.ZodRecord<z.ZodString, z.ZodUnknown>;
  correlationId?: string | null;
  createdAt: Date;
  currentStepId?: string | null;
  decisionId?: string | null;
  definitionId: string;
  definitionKey: string;
  definitionVersion: number;
  error?: string | null;
  finishedAt?: Date | null;
  id: string;
  replayOf?:   | {
     runId: string;
     stepId: string;
   }
     | null;
  startedAt: Date;
  status:   | "failed"
     | "completed"
     | "running"
     | "waiting_collection"
     | "waiting_manual"
     | "waiting_callback"
     | "cancelled";
  subjectId: string;
  temporalRunId?: string | null;
  temporalWorkflowId: string;
  tenantId: string;
  traceId?: string | null;
  trigger: "console" | "api" | "replay";
  updatedAt: Date;
}>;

Parameters

id

string

Returns

Promise<{ context: z.ZodRecord<z.ZodString, z.ZodUnknown>; correlationId?: string | null; createdAt: Date; currentStepId?: string | null; decisionId?: string | null; definitionId: string; definitionKey: string; definitionVersion: number; error?: string | null; finishedAt?: Date | null; id: string; replayOf?: | { runId: string; stepId: string; } | null; startedAt: Date; status: | "failed" | "completed" | "running" | "waiting_collection" | "waiting_manual" | "waiting_callback" | "cancelled"; subjectId: string; temporalRunId?: string | null; temporalWorkflowId: string; tenantId: string; traceId?: string | null; trigger: "console" | "api" | "replay"; updatedAt: Date; }>

---

history

history: (id) => Promise<unknown>;

The run's Temporal event history as proto JSON, for replaying it against a new worker bundle (node dist/replay.js). Admin only; 409 when the API has no Temporal client.

Parameters

id

string

Returns

Promise<unknown>

---

listBySubject

listBySubject: (subjectId) => Promise<object[]>;

The subject's newest runs (50 at most), as an array.

Parameters

subjectId

string

Returns

Promise<object[]>

---

listPage

listPage: (query?) => Promise<Page<{
  context: z.ZodRecord<z.ZodString, z.ZodUnknown>;
  correlationId?: string | null;
  createdAt: Date;
  currentStepId?: string | null;
  decisionId?: string | null;
  definitionId: string;
  definitionKey: string;
  definitionVersion: number;
  durationMs: number;
  error?: string | null;
  finishedAt?: Date | null;
  id: string;
  outcome: "approve" | "reject" | "manual_review" | null;
  replayOf?:   | {
     runId: string;
     stepId: string;
   }
     | null;
  startedAt: Date;
  status:   | "failed"
     | "completed"
     | "running"
     | "waiting_collection"
     | "waiting_manual"
     | "waiting_callback"
     | "cancelled";
  subject?: {
     country?: string;
     displayName: string;
     externalId?: string | null;
     id: string;
     kind: "user" | "merchant" | "seller";
  };
  subjectId: string;
  temporalRunId?: string | null;
  temporalWorkflowId: string;
  tenantId: string;
  traceId?: string | null;
  trigger: "console" | "api" | "replay";
  updatedAt: Date;
}>>;

One page of the tenant's runs, newest first, with the number of matches. Each run carries durationMs and the outcome of its decision (runs:read).

Parameters

query?

WorkflowRunPageQuery

Returns

Promise<Page<{ context: z.ZodRecord<z.ZodString, z.ZodUnknown>; correlationId?: string | null; createdAt: Date; currentStepId?: string | null; decisionId?: string | null; definitionId: string; definitionKey: string; definitionVersion: number; durationMs: number; error?: string | null; finishedAt?: Date | null; id: string; outcome: "approve" | "reject" | "manual_review" | null; replayOf?: | { runId: string; stepId: string; } | null; startedAt: Date; status: | "failed" | "completed" | "running" | "waiting_collection" | "waiting_manual" | "waiting_callback" | "cancelled"; subject?: { country?: string; displayName: string; externalId?: string | null; id: string; kind: "user" | "merchant" | "seller"; }; subjectId: string; temporalRunId?: string | null; temporalWorkflowId: string; tenantId: string; traceId?: string | null; trigger: "console" | "api" | "replay"; updatedAt: Date; }>>

---

related

related: (id) => Promise<{
  cases: object[];
  decision:   | {
     caseId?: string | null;
     createdAt: Date;
     decidedBy?: string | null;
     id: string;
     outcome: "approve" | "reject" | "manual_review";
     reasons: object[];
     riskScore?: number | null;
     ruleResults: object[];
     ruleSetKey?: string | null;
     ruleSetVersion?: number | null;
     source: "manual" | "automated";
     subjectId: string;
     tenantId: string;
     workflowRunId?: string | null;
   }
     | null;
  deliveries: object[];
  replayOf:   | {
     id: string;
     startedAt: Date;
     status:   | "failed"
        | "completed"
        | "running"
        | "waiting_collection"
        | "waiting_manual"
        | "waiting_callback"
        | "cancelled";
     stepId: string | null;
   }
     | null;
  replays: object[];
  traceUrl: string | null;
}>;

Its cases and decision, the run it replayed, its replays and (ops:read) a trace link.

Parameters

id

string

Returns

Promise<{ cases: object[]; decision: | { caseId?: string | null; createdAt: Date; decidedBy?: string | null; id: string; outcome: "approve" | "reject" | "manual_review"; reasons: object[]; riskScore?: number | null; ruleResults: object[]; ruleSetKey?: string | null; ruleSetVersion?: number | null; source: "manual" | "automated"; subjectId: string; tenantId: string; workflowRunId?: string | null; } | null; deliveries: object[]; replayOf: | { id: string; startedAt: Date; status: | "failed" | "completed" | "running" | "waiting_collection" | "waiting_manual" | "waiting_callback" | "cancelled"; stepId: string | null; } | null; replays: object[]; traceUrl: string | null; }>

---

replay

replay: (id, body) => Promise<{
  context: z.ZodRecord<z.ZodString, z.ZodUnknown>;
  correlationId?: string | null;
  createdAt: Date;
  currentStepId?: string | null;
  decisionId?: string | null;
  definitionId: string;
  definitionKey: string;
  definitionVersion: number;
  error?: string | null;
  finishedAt?: Date | null;
  id: string;
  replayOf?:   | {
     runId: string;
     stepId: string;
   }
     | null;
  startedAt: Date;
  status:   | "failed"
     | "completed"
     | "running"
     | "waiting_collection"
     | "waiting_manual"
     | "waiting_callback"
     | "cancelled";
  subjectId: string;
  temporalRunId?: string | null;
  temporalWorkflowId: string;
  tenantId: string;
  traceId?: string | null;
  trigger: "console" | "api" | "replay";
  updatedAt: Date;
}>;

Starts a new run of the same version at fromStepId with the context the run had there (runs:write); 409 run_active before it finishes, step_not_reached for a step it never reached.

Parameters

id

string

body

fromStepId

string

Returns

Promise<{ context: z.ZodRecord<z.ZodString, z.ZodUnknown>; correlationId?: string | null; createdAt: Date; currentStepId?: string | null; decisionId?: string | null; definitionId: string; definitionKey: string; definitionVersion: number; error?: string | null; finishedAt?: Date | null; id: string; replayOf?: | { runId: string; stepId: string; } | null; startedAt: Date; status: | "failed" | "completed" | "running" | "waiting_collection" | "waiting_manual" | "waiting_callback" | "cancelled"; subjectId: string; temporalRunId?: string | null; temporalWorkflowId: string; tenantId: string; traceId?: string | null; trigger: "console" | "api" | "replay"; updatedAt: Date; }>

---

start

start: (body) => Promise<{
  context: z.ZodRecord<z.ZodString, z.ZodUnknown>;
  correlationId?: string | null;
  createdAt: Date;
  currentStepId?: string | null;
  decisionId?: string | null;
  definitionId: string;
  definitionKey: string;
  definitionVersion: number;
  error?: string | null;
  finishedAt?: Date | null;
  id: string;
  replayOf?:   | {
     runId: string;
     stepId: string;
   }
     | null;
  startedAt: Date;
  status:   | "failed"
     | "completed"
     | "running"
     | "waiting_collection"
     | "waiting_manual"
     | "waiting_callback"
     | "cancelled";
  subjectId: string;
  temporalRunId?: string | null;
  temporalWorkflowId: string;
  tenantId: string;
  traceId?: string | null;
  trigger: "console" | "api" | "replay";
  updatedAt: Date;
}>;

Parameters

body

correlationId?

string

definitionKey

string

subjectId

string

trigger?

"console" | "api"

Returns

Promise<{ context: z.ZodRecord<z.ZodString, z.ZodUnknown>; correlationId?: string | null; createdAt: Date; currentStepId?: string | null; decisionId?: string | null; definitionId: string; definitionKey: string; definitionVersion: number; error?: string | null; finishedAt?: Date | null; id: string; replayOf?: | { runId: string; stepId: string; } | null; startedAt: Date; status: | "failed" | "completed" | "running" | "waiting_collection" | "waiting_manual" | "waiting_callback" | "cancelled"; subjectId: string; temporalRunId?: string | null; temporalWorkflowId: string; tenantId: string; traceId?: string | null; trigger: "console" | "api" | "replay"; updatedAt: Date; }>

---

steps

steps: (id) => Promise<Page<{
  durationMs: number;
  error?: string | null;
  finishedAt?: Date | null;
  id: string;
  input: unknown;
  output: unknown;
  refs: {
     callbackId?: string;
     caseId?: string;
     decisionId?: string;
     evaluationId?: string;
     invocationId?: string;
     submissionId?: string;
  };
  round: number;
  runId: string;
  startedAt: Date;
  status: "failed" | "completed" | "running" | "cancelled" | "waiting";
  stepId: string;
  stepType: string;
  summary: string | null;
  visit: number;
}>>;

The step visits the worker traced, in the order they started, with the number recorded. Inputs and outputs are redacted without runs:context.

Parameters

id

string

Returns

Promise<Page<{ durationMs: number; error?: string | null; finishedAt?: Date | null; id: string; input: unknown; output: unknown; refs: { callbackId?: string; caseId?: string; decisionId?: string; evaluationId?: string; invocationId?: string; submissionId?: string; }; round: number; runId: string; startedAt: Date; status: "failed" | "completed" | "running" | "cancelled" | "waiting"; stepId: string; stepType: string; summary: string | null; visit: number; }>>

---

summary

summary: (query?) => Promise<{
  autoDecidedPct: number | null;
  byStatus: z.ZodRecord<z.ZodEnum<{
     cancelled: "cancelled";
     completed: "completed";
     failed: "failed";
     running: "running";
     waiting_callback: "waiting_callback";
     waiting_collection: "waiting_collection";
     waiting_manual: "waiting_manual";
  }>, z.ZodNumber>;
  p95DurationMs: number | null;
  total: number;
}>;

Counts per status and the p95 duration of the runs started in a window.

Parameters

query?

WorkflowRunSummaryParams

Returns

Promise<{ autoDecidedPct: number | null; byStatus: z.ZodRecord<z.ZodEnum<{ cancelled: "cancelled"; completed: "completed"; failed: "failed"; running: "running"; waiting_callback: "waiting_callback"; waiting_collection: "waiting_collection"; waiting_manual: "waiting_manual"; }>, z.ZodNumber>; p95DurationMs: number | null; total: number; }>