Skip to main content
POST
Requires version 1.1.12 or later of the Archetype platform.

​
Overview

This endpoint creates and starts an optimization run over a blueprint. It returns immediately with the run’s ID and a pending status. The platform drives it to completed, failed, or cancelled through its controller; poll Get Optimization to observe progress and the winning trial. A run samples points from search_space, fits and scores a trial at each one, and maximizes objective — a metric name the blueprint’s metrics schema declares. Every trial’s eval scores against validation_examples. Trials that violate constraints are marked infeasible and are excluded from the winner.
The three example sets play different roles: training_examples feed the fit and are never scored, validation_examples are what every trial’s eval scores against, and calibration_examples are a family-specific held-out slice.
A trial that violates any min_metric constraint is marked feasible: false and cannot win, but it is still promotable if you prefer it over the winner. The run does not publish a blueprint per trial. Materialize the one you want with the Promote Trial endpoint.

​
Request

​
string
required
The blueprint to search — a blp_ ID. Must be visible to the caller’s organization.
​
string
required
Primary metric name to maximize. Must be one of the objectives declared by the blueprint’s metrics schema.
​
object
required
Budget knobs for the run.
  • max_trials (integer, required) — how many trials the run may create. Minimum 1.
​
array
required
Scoring examples — every trial’s eval scores against these. Each entry is an example, in the same shape Create Eval accepts.
​
string
Human label for this run.
​
object
The parameter space to sample from. Keys must match tunable blueprint values (values.*).
​
array
Fit examples. Omit when the blueprint’s fit needs no external training data — a Task Verification Agent or Manual Generation Agent run tuning inference-time knobs, for example. Consumed by the fit, never scored.
Omit training_examples when the blueprint’s fit needs no external training data.
​
array
Calibration examples: a family-specific held-out slice, e.g. Activity Detection threshold calibration.
​
object
Per-trial feasibility constraints. A trial that fails any of them is marked feasible: false and excluded from best_trial_id.
  • min_metric (array) — “the trial’s metric must be ≥ min_value” checks.

​
Search space (search_space)

Each entry names a parameter, the values it can take, and where the sampled value plugs in at trial time.
​
object
required
Parameter name to entry. The name is the destination key inside the entry’s kind bucket at trial time.
​
string
required
Which override kind the sampled value writes to: value, model, or fitting. Each maps to a distinct argument the training / eval resolution consumes.
​
object
required
The domain the sampler draws from. One of three forms:
  • {"type": "categorical", "values": [...]} — a fixed set to sample from, e.g. ["Uniform", "Distance"] or [512, 1024, 2048]. Each value is an integer or a string.
  • {"type": "int_range", "min": 16, "max": 1024} — an integer range, both bounds inclusive.
  • {"type": "float_range", "min": 0.01, "max": 0.5} — a float range, both bounds inclusive.

​
Metric threshold (constraints.min_metric[])

​
string
required
Metric name — must be a value the trial’s metrics report emits, e.g. macro_f1 or recall.
​
number
required
Minimum acceptable value, inclusive.
​
string
When set, the threshold applies to this class’s per-class value of metric — class fault_bearing recall, for example. Unset applies it to the aggregate.

​
Response

Returns 201 Created with the run in pending status. See Get Optimization for the full field list.
​
string
required
TypeID-encoded optimization identifier (opt_ prefix).
​
string
required
Human label for the run.
​
string
required
Organization identifier the run belongs to.
​
string
required
The blueprint being searched.
​
string
required
The primary metric name being maximized.
objective must be one of the objectives the blueprint’s metrics schema declares; a blueprint publishing no metrics catalog cannot be optimized.
​
object
required
The parameter space the run samples from.
​
object
required
The run’s budget knobs.
​
array
required
The scoring examples as resolved: named, their inputs pinned with the CRC32C of the bytes used, and their ground-truth declarations filled in from the blueprint’s defaults.
​
string
required
Optimization lifecycle status: pending, running, completed, failed, or cancelled.
​
object
required
Per-status trial counts, so a caller can render a progress bar without listing trials. All zero on a fresh run.
​
string
required
Subject id (usr_... or key_...) that created this run.
​
string
required
Creation timestamp (date-time).
​
string
Set by the promotion step on successful completion; the trial the run picked as its winner.
​
array
The fit examples as resolved; null when the run supplied none.
​
array
The calibration examples as resolved; null when the run supplied none.
​
object
The per-trial feasibility constraints; null when the run supplied none.
​
string
When the run started; null before then.
​
string
When the run finished; null while unfinished.
​
string
Failure detail; null unless the run failed.