Understanding Runs

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:

Generate the mapping logic
Validate the transformation
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:

Status	Description
`CREATED`	The run has been created but not yet started
`PENDING`	The run is queued and waiting to start
`RUNNING`	The 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
`SUCCEEDED`	The run completed successfully
`FAILED`	The run encountered errors during processing
`CRASHED`	The run terminated due to an internal error
`INCOMPLETE`	The 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:

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
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);

// Create run without waiting
const run = await flow.createRun({ source_data: data }, false);
// Wait for completion
await run.waitForCompletion();
// Check status and get results
if (run.status === "SUCCEEDED") {
  const results = await flow.getRunResults(run);
}

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:

Status Polling

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

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

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.

Welcome

Getting Started

Project Guides

Flow Guides

Security

Questions

Permissions

What are Runs?

Run Statuses

Working with Runs

Creating New Runs

Managing Runs Manually

Monitoring Run Progress

Run Results

​What are Runs?

​Run Statuses

​Working with Runs

​Creating New Runs

​Managing Runs Manually

​Monitoring Run Progress

​Run Results

What are Runs?

Run Statuses

Working with Runs

Creating New Runs

Managing Runs Manually

Monitoring Run Progress

Run Results