​
What are Runs?

A run represents a single execution of a flow with specific source data. When you create a new flow, Lume automatically creates an initial run to:

  1. Generate the mapping logic
  2. Validate the transformation
  3. Process your initial source data

You can create multiple runs of the same flow to process new data using the same mapping logic. This is useful for:

  • Processing weekly data updates
  • Handling batch transformations
  • Testing mapping changes
  • Validating data quality

​
Run Statuses

Each run can have one of the following statuses:

StatusDescription
CREATEDThe run has been created but not yet started
PENDINGThe run is queued and waiting to start
RUNNINGThe run is processing data:
• For new flows: Analyzes source/target schemas and creates the initial mapper
• For existing flows: Processes data using the established mapping logic
• When enum classifications are present: May take longer to process new values that require AI classification
SUCCEEDEDThe run completed successfully
FAILEDThe run encountered errors during processing
CRASHEDThe run terminated due to an internal error
INCOMPLETEThe run failed to process some records

If a run fails, crashes, or is incomplete, please contact support.

​
Working with Runs

​
Creating New Runs

You can create new runs in several ways:

  1. Using the Lume App

    • Navigate to your flow and click “Create New Run”
    • Choose to use data from a previous run or upload new source data
    • Monitor progress directly in the UI

  2. Programmatically You can also create runs via code using either:

    • The process() method for simple transformations
    • Manual run creation for more control
const results = await existingFlow.process(newSourceData);

The first run on a new flow involves additional processing time to analyze your data structures and generate the mapping logic. Subsequent runs are typically faster, though processing time may increase when mapping new enum values that require AI classification.

​
Managing Runs Manually

If you want more control over Run creation, especially for parallel tasks or large transformations, you can manage the runs yourself:

// 1. Create a run but do not wait.
const flow = await lume.flowService.getFlow("my-long-flow-id");
const run = await flow.createRun({ source_data: data }, false);

// 2. Poll or wait for it to finish.
await run.waitForCompletion();  // blocks until Succeeded, Failed, or Crashed

// 3. Check the run status and get the results.
if (run.status === "SUCCEEDED") {
  // Page size is limited to 100 items per request
  const page = await flow.getRunResults(run, 1, 50);
  console.log("Manual run output:", page.items);
} else {
  console.error("Run ended with status:", run.status);
}

// paginate through the results as needed

​
Monitoring Run Progress

When monitoring runs, you can track their progress through the following methods:

  1. Status Polling

    const run = await flow.createRun({ source_data: data }, false);
await run.waitForCompletion();  // Blocks until final status

  2. Status Checks

    • Check run.status to get the current state
    • Final statuses include: SUCCEEDED, FAILED, CRASHED, INCOMPLETE
    • Intermediate statuses: CREATED, PENDING, RUNNING

  3. Results Retrieval

    if (run.status === "SUCCEEDED") {
  const results = await flow.getRunResults(run);
  console.log("Mapped data:", results.items);
}

For long-running transformations, consider implementing a polling strategy with appropriate timeouts and error handling.

​
Run Results

Each run stores:

  • The input source data used
  • The mapped output data produced
  • The version of the mapper used
  • Validation results and any errors
  • Performance metrics and statistics

Results are paginated with a default limit of 100 items per page. Use pagination parameters to retrieve all results for large datasets.

Managing FlowsBuilding a Target Schema