> This page is for version dev.
> For other versions, use one of these documentation indexes:
> - 1.8.1 (default): https://docs.nvidia.com/networking/cloudai/1.8.1/llms.txt
> - 1.7.1: https://docs.nvidia.com/networking/cloudai/1.7.1/llms.txt
> - 1.6.1: https://docs.nvidia.com/networking/cloudai/1.6.1/llms.txt
> - dev: https://docs.nvidia.com/networking/cloudai/dev/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/networking/cloudai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/networking/cloudai/_mcp/server.

`cloudai.api` lets a Python program validate or run a scenario and find its saved results. Pass configuration file paths as `pathlib.Path` objects:

```python
from pathlib import Path

import cloudai.api

system = Path("conf/common/system/example_slurm_cluster.toml")
scenario = Path("conf/common/test_scenario/sleep.toml")

cloudai.api.validate_scenario(
    scenario, system, tests_dir=Path("conf/common/test")
)
experiment = cloudai.api.run_experiment(
    scenario, system, tests_dir=Path("conf/common/test")
)
print(experiment.status, experiment.path)
```

`validate_scenario` performs the same configuration loading checks as `run_experiment`. It returns `None` on success and raises configuration errors on failure, without creating a runner, installing dependencies, or submitting jobs. Pass `tests_dir` for referenced test definitions and `hook_dir` for custom hooks, as with `run_experiment`. Validation does not check cluster availability or whether a workload will run successfully.

`run_experiment` waits for the scenario to finish and returns an `Experiment` model with the same data saved in `experiment.json`. Workload failures appear in its status. Configuration and setup errors raise exceptions. Use `mode="dry-run"` to generate commands without running workloads. Use `single_sbatch=True` for a single Slurm allocation. Pass `hook_dir` to use a custom hook directory. Pass an `on_start` callback to receive the initial `Experiment` and a cancellation function after `experiment.json` is created and before execution begins. The function remains synchronous after calling the callback.

`list_experiments(system)` returns `(experiment_id, result_directory)` pairs from the system's configured output directory. Directories without `experiment.json` are skipped. A missing output directory gives an empty list; experiment file contents are not parsed.

`get_experiment(experiment_id, system)` loads an `Experiment` from that system's output directory. Pass a `Path` to a result directory to load it directly. Invalid IDs and missing, unreadable, or malformed experiment files raise `ValueError`.