optimization

Create Optimization Run

Create a non-blocking prompt optimization run.

Returns immediately with the run_id. The optimization executes as a background task. Poll GET /runs/{run_id} for progress and results.

post/api/v1/optimization/runs

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.

skill_namestring nullable

Bundled or mounted Fleet skill name to optimize as a markdown skill artifact.

skill_pathstring nullable

Relative path to a SKILL.md-compatible markdown file to optimize.

trace_bundle_pathsstring[]

Optional offline trace bundle paths available to the RLM-GEPA instruction proposer.

reflection_profile_idstring nullable

Optional LLM provider profile id for the GEPA proposer/reflection model.

reflection_model_idstring nullable

Optional provider-native model id for the GEPA proposer/reflection model.

output_pathstring nullable

Optional filesystem path to save the optimized program.

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

Optimization intensity level.

max_metric_callsinteger nullable

Optional GEPA metric-call budget override for short offline smoke runs.

train_rationumber

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

optimizer'gepa'

Optimizer backend to use. GEPA is the only supported optimizer.

Successful Response

run_idstring required

Unique identifier for the created run.

statusstring

Initial run status.