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

# 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()`](/pages/libraries/python-ent/api/functions#run) and [`lume.run_status()`](/pages/libraries/python-ent/api/functions#run-status).

## Attributes

<Card title="id" icon="fingerprint">
  **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..."`
</Card>

<Card title="status" icon="flag">
  **Type**: `str`

  The current state of the run in its lifecycle. See the [Run Lifecycle](/pages/libraries/python-ent/concepts#run-lifecycle) documentation for a full list of possible statuses.

  **Example**: `"TRANSFORMING"`
</Card>

<Card title="metadata" icon="binary">
  **Type**: `dict`

  A dictionary containing detailed results and metrics after a run completes. See the detailed **[Metadata Schema](#metadata-schema)** below for the full structure.
</Card>

## Methods

### wait()

<Card title="run.wait()" icon="hourglass">
  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.

  <Info>
    **Note on Production Use**: While `wait()` is convenient for scripts, for scalable, event-driven applications, we strongly recommend using [Webhooks](/pages/libraries/python-ent/production#asynchronous-processing-with-webhooks) to receive notifications about run completion instead of polling.
  </Info>

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

  ```python theme={null}
  run.wait(timeout=600, poll_interval=10)
  print(f"Run finished with status: {run.status}")
  ```
</Card>

### refresh()

<Card title="run.refresh()" icon="rotate-right">
  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**

  ```python theme={null}
  # Check status now
  run.refresh()
  print(f"Current status is: {run.status}")
  ```
</Card>

***

## Metadata Schema

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

### Top-Level Structure

```json theme={null}
{
  "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.     |