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

​
Configuration

​
init()

lume.init()

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

import lume
lume.init(api_key="your_api_key_here")

​
Pipeline Execution

​
run()

lume.run()

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

run = lume.run(
    flow_version="invoice_processor:v3",
    source_path="s3://my-invoices/new/batch-001.csv",
    run_metadata={"triggered_by": "daily_cron_job"}
)

​
run_status()

lume.run_status()

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

run = lume.run_status("run_01HY...")
print(run.status)

​
Beta Functions

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.

​
upload_file()

lume.upload_file()

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.

​
get_results_dataframe()

lume.get_results_dataframe()

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.