LumeRun

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: strThe 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: strThe current state of the run in its lifecycle. See the Run Lifecycle documentation for a full list of possible statuses.Example: "TRANSFORMING"

metadata

Type: dictA 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, a TimeoutError is raised. Defaults to 3600 (1 hour).
poll_interval (int, optional): The number of seconds to wait between status checks. Defaults to 5.

Returns

None

Example

run.wait(timeout=600, poll_interval=10)
print(f"Run finished with status: {run.status}")

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

# Check status now
run.refresh()
print(f"Current status is: {run.status}")

Metadata Schema

The metadata attribute contains a rich, structured object detailing the outcome of a completed run.

Top-Level Structure

{
  "run": {},
  "pipeline": {},
  "results": {},
  "validation": {},
  "errors": []
}

`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.

Typescript

Python SDK

Attributes

id

status

metadata

Methods

wait()

run.wait()

refresh()

run.refresh()

Metadata Schema

Top-Level Structure

`run` Object

`pipeline` Object

`results` Object

`validation` Object

`errors` Array

​Attributes

id

status

metadata

​Methods

​wait()

run.wait()

​refresh()

run.refresh()

​Metadata Schema

​Top-Level Structure

​run Object

​pipeline Object

​results Object

​validation Object

​errors Array

Attributes

Methods

wait()

refresh()

Metadata Schema

Top-Level Structure

`run` Object

`pipeline` Object

`results` Object

`validation` Object

`errors` Array