Running workflows

Both run helpers accept the same workflow argument: an inline Workflow object or a string reference to a published workflow — "<id>@<version>", where the id is the published <org-slug>/<workflow-slug> address (preferred, e.g. "acme/sprite-pack@2.1.0") or the workflow's internal UUID (see Versioning).

`run()` — run to completion

The simple path: streams events internally and resolves with the final outputs, or throws if the run fails.

import { BlitClient, run } from "@blitflow/sdk";

const client = new BlitClient({ apiKey: process.env.BLITFLOW_TOKEN });

const outputs = await run(
  client,
  "acme/sprite-pack@2.1.0",
  {
    prompt: { kind: "text", value: "isometric stone tower" },
    photo: { kind: "image", ref: "https://example.com/tower.jpg" },
  },
  { maxCostUsd: 0.25 },
);

// outputs: Record<string, Artifact>
console.log(outputs.image); // { kind: "image", ref: "https://…", … }

Inputs are Artifacts keyed by the workflow's declared input names.

`startRun()` — observe progress

Returns immediately with a handle; iterate events() for per-step progress:

import { startRun } from "@blitflow/sdk";

const handle = await startRun(client, "acme/sprite-pack@latest", inputs, {
  maxCostUsd: 0.5,
});

for await (const event of handle.events()) {
  switch (event.type) {
    case "step.started":
      console.log(`▶ ${event.nodeId}`);
      break;
    case "step.progress":
      console.log(`  ${event.nodeId}: ${event.message}`);
      break;
    case "step.completed":
      console.log(
        `✔ ${event.nodeId} ($${event.usage.costUsd}, ${event.usage.ms}ms)`,
      );
      break;
    case "run.completed":
      return event.outputs;
    case "run.failed":
      throw new Error(`${event.error.code}: ${event.error.message}`);
  }
}

The event union is documented in Runs & streaming.

Running an inline definition

Pass a Workflow object instead of a ref for one-off runs — nothing needs to be published:

const outputs = await run(
  client,
  {
    version: 2,
    nodes: [
      { id: "prompt", uses: "input", outputType: "TEXT" },
      {
        id: "gen",
        uses: "rd-fast",
        inputs: { prompt: "${prompt.value}", seed: 7 },
      },
      { id: "image", uses: "output", inputs: { value: "${gen.image}" } },
    ],
  },
  {
    prompt: { kind: "text", value: "a brass key" },
  },
);

See Building workflows for constructing these programmatically with validation.

`getWorkflow()` — fetch a published definition

import { getWorkflow } from "@blitflow/sdk";

const { id, version, sequence, workflow } = await getWorkflow(
  client,
  "acme/sprite-pack@2",
);
// version: "2.4.1" — the resolved highest 2.x.x

Useful for auditing what a ref resolves to, diffing versions, or grabbing a definition to modify and re-run inline.

run() — run to completion

startRun() — observe progress

Running an inline definition

getWorkflow() — fetch a published definition

On this page

`run()` — run to completion

`startRun()` — observe progress

`getWorkflow()` — fetch a published definition