> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lume.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Runs

> Learn about runs, their statuses, and how they work in Lume

## 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:

| 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: <br />• For new flows: Analyzes source/target schemas and creates the initial mapper<br />• For existing flows: Processes data using the established mapping logic<br />• 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                                                                                                                                                                                                                                                                            |

<Note>
  If a run fails, crashes, or is incomplete, please contact support.
</Note>

## 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

<CodeGroup>
  ```typescript Simple Process theme={null}
  const results = await existingFlow.process(newSourceData);
  ```

  ```typescript Manual Control theme={null}
  // 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);
  }
  ```
</CodeGroup>

<Note>
  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.
</Note>

## Managing Runs Manually

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

```typescript theme={null}
// 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**
   ```typescript theme={null}
   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**
   ```typescript theme={null}
   if (run.status === "SUCCEEDED") {
     const results = await flow.getRunResults(run);
     console.log("Mapped data:", results.items);
   }
   ```

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

### 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

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