LumeRun
Reference for the LumeRun object.
The LumeRun object is the central data structure in the Lume SDK. It represents a single execution of a Lume pipeline and holds all its associated state and results. An instance of this object is returned by lume.run() and lume.run_status().
Attributes
id
Type: str
The unique identifier for the run, prefixed with run_. This ID is used to query the run’s status and access its results.
Example: "run_01HYE5ZJ..."
status
Type: str
The current state of the run in its lifecycle. See the Run Lifecycle documentation for a full list of possible statuses.
Example: "TRANSFORMING"
metadata
Type: dict
A dictionary containing detailed results and metrics after a run completes. See the detailed Metadata Schema below for the full structure.
Methods
wait()
run.wait()
Blocks execution and polls the run’s status until it reaches a terminal state (SUCCEEDED, FAILED, PARTIAL_FAILED, or CRASHED). This method updates the LumeRun object in-place.
Note on Production Use: While wait() is convenient for scripts, for scalable, event-driven applications, we strongly recommend using Webhooks to receive notifications about run completion instead of polling.
Parameters
timeout(int, optional): The maximum number of seconds to wait. If the timeout is reached, aTimeoutErroris raised. Defaults to3600(1 hour).poll_interval(int, optional): The number of seconds to wait between status checks. Defaults to5.
Returns
None
Example
refresh()
run.refresh()
Manually refreshes the LumeRun object in-place, updating its status and metadata with the latest information from the Lume server. This is equivalent to calling run = lume.run_status(run.id).
Parameters
None
Returns
None
Example
Metadata Schema
The metadata attribute contains a rich, structured object detailing the outcome of a completed run.
Top-Level Structure
run Object
Contains identifiers and high-level information about the run itself.
| Field | Type | Description |
|---|---|---|
run_id | string | The unique identifier for this run. |
flow_version | string | The flow version that was executed. |
source_path | string | The unique source path that triggered this run. |
status | string | The terminal status of the run. |
pipeline Object
Details the performance of each stage in the sync-transform-sync pipeline.
| Field | Type | Description |
|---|---|---|
created_at | timestamp | When the run was first accepted by the Lume API. |
completed_at | timestamp | When the run reached a terminal state. |
duration_seconds | float | Total time from created_at to completed_at. |
stages | object | Timings for each individual pipeline stage. |
pipeline.stages Object
| Field | Type | Description |
|---|---|---|
sync_source_seconds | float | Time spent syncing data from your source. |
transform_seconds | float | Time spent executing the transformation logic. |
sync_target_seconds | float | Time spent writing results to your target. |
results Object
Summarizes the outcome of the data transformation.
| Field | Type | Description |
|---|---|---|
input_rows | integer | Total number of rows synced from the source. |
mapped_rows | integer | Number of rows successfully transformed. |
rejected_rows | integer | Number of rows that failed validation. |
target_locations | object | URIs pointing to the output locations. |
results.target_locations Object
| Field | Type | Description |
|---|---|---|
mapped | string | The path where mapped (successful) data was written. |
rejects | string | The path where rejected (failed) data was written. |
validation Object
Provides a detailed summary of data quality test outcomes.
| Field | Type | Description |
|---|---|---|
tests_executed | integer | Total number of validation tests performed. |
tests_failed | integer | Total number of validation tests that failed. |
error_rate | float | The ratio of tests_failed to tests_executed. |
top_errors | array | An array of objects summarizing the most common failures. |
validation.top_errors Array Object
| Field | Type | Description |
|---|---|---|
error_code | string | A machine-readable code for the error. |
field | string | The target field where the error occurred. |
count | integer | The number of times this specific error occurred. |
errors Array
This array is empty for SUCCEEDED or PARTIAL_FAILED runs. If the run FAILED, it contains objects detailing the cause.
| Field | Type | Description |
|---|---|---|
stage | string | The pipeline stage where the failure occurred. |
error_code | string | A machine-readable code for the system error. |
message | string | A human-readable description of the error. |