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

# Functions

> Reference for top-level functions in the Lume Python SDK.

These functions are the primary entry points for interacting with the Lume API.

## Configuration

### init()

<Card title="lume.init()" icon="gear">
  Initializes the Lume client with a specific API key and other configurations. This is only necessary if you are not setting the `LUME_API_KEY` environment variable.

  **Parameters**

  * `api_key` (str): Your Lume API key.
  * `request_timeout` (int, optional): The timeout in seconds for API requests. Defaults to `60`.

  **Example**

  ```python theme={null}
  import lume
  lume.init(api_key="your_api_key_here")
  ```
</Card>

## Pipeline Execution

### run()

<Card title="lume.run()" icon="play">
  Triggers a new, end-to-end Lume pipeline execution. This is an asynchronous operation that returns immediately.

  **Parameters**

  * `flow_version` (str): The name and version of the flow to execute (e.g., `"my_flow:v2"`).
  * `source_path` (str): A unique identifier pointing to the source data for this run.
  * `run_metadata` (dict, optional): A dictionary of custom key-value pairs to associate with the run, retrievable via webhook or `run_status()`.
  * `force_rerun` (bool, optional): If `True`, bypasses the idempotency check to re-process a `source_path` that has already succeeded. Defaults to `False`.

  **Returns**

  * `LumeRun`: An object representing the newly created run.

  **Example**

  ```python theme={null}
  run = lume.run(
      flow_version="invoice_processor:v3",
      source_path="s3://my-invoices/new/batch-001.csv",
      run_metadata={"triggered_by": "daily_cron_job"}
  )
  ```
</Card>

### run\_status()

<Card title="lume.run_status()" icon="circle-nodes">
  Retrieves the current status and metadata of a specific run by its ID.

  **Parameters**

  * `run_id` (str): The unique identifier of the run (e.g., `"run_01HY..."`).

  **Returns**

  * `LumeRun`: An object representing the run, with its `status` and `metadata` attributes populated.

  **Example**

  ```python theme={null}
  run = lume.run_status("run_01HY...")
  print(run.status)
  ```
</Card>

## Beta Functions

<Warning>
  The following functions are in beta. Their signature, behavior, and availability may change in future releases without notice. They are not recommended for use in production environments.
</Warning>

### upload\_file()

<Card title="lume.upload_file()" icon="upload">
  Uploads a local file to the Lume-managed staging area for S3-based flows, returning a `source_path` for use in `lume.run()`.

  **Parameters**

  * `local_file_path` (str): Path to the local file to upload.
  * `flow_version` (str): The Flow Version this file is for, used to determine the correct upload location.

  **Returns**

  * `str`: The `source_path` corresponding to the uploaded file.
</Card>

### get\_results\_dataframe()

<Card title="lume.get_results_dataframe()" icon="file-invoice">
  Downloads the mapped or rejected output from a completed run directly into a Pandas DataFrame. Requires `pandas`.

  **Parameters**

  * `run_id` (str): The ID of the completed run.
  * `result_type` (str, optional): The result set to download, either `"mapped"` or `"rejects"`. Defaults to `"mapped"`.

  **Returns**

  * `pandas.DataFrame`: A DataFrame containing the requested result data.
</Card>