optimization

Run Optimization

Trigger a GEPA prompt optimization run.

post/api/v1/optimization/run

Request body

dataset_pathstring nullable

Relative filesystem path to the dataset file.

dataset_idstring nullable

Registered dataset identifier to optimize against.

program_specstring

DSPy program specification string to optimize in module:attr form. Required when module_slug is not provided.

module_slugstring nullable

Registered module slug for server-side dispatch. When provided, program_spec is auto-resolved from the module registry.

output_pathstring nullable

Optional filesystem path to save the optimized program.

auto'light' | 'medium' | 'heavy'

GEPA optimization intensity level.

train_rationumber

Fraction of examples to use for training (remainder used for validation).

Successful Response

okboolean

Whether the optimization run completed successfully.

optimizerstring

Optimizer backend that was used.

program_specstring required

DSPy program specification that was optimized.

train_examplesinteger required

Number of training examples used.

validation_examplesinteger required

Number of validation examples used.

validation_scorenumber nullable

Validation score from the optimized program, when available.

output_pathstring nullable

Filesystem path where the optimized program was saved.

manifest_pathstring nullable

Filesystem path to the optimization manifest, when available.

module_slugstring nullable

Module slug used for this optimization run, when server-side dispatch was used.

errorstring nullable

Error message when the optimization run failed.