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 201 immediately with the run in pending status; the run moves to running and then to completed, failed, or cancelled on its own. Poll Get Optimization for progress and the winning trial, or list its trials with List Optimization Trials. A run samples up to budget.max_trials points from search_space and evaluates each as a trial against validation_examples. When the run ends, whether it completed, failed, or was cancelled, it picks the completed feasible trial with the best primary score as best_trial_id. Without primary (or the deprecated objective), the blueprint’s own headline is maximized. Trials that miss a bound in constraints are marked infeasible and are excluded from the winner. So are trials that cannot be judged because a bounded objective has no value. targets changes how every trial is scored, the same way it does for an eval: for example, to score a per-class objective the blueprint does not declare. overrides are applied to every trial, and to any blueprint promoted from one. Together with search_space, they must provide every value the blueprint declares as required (written ${required}).
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 misses any 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.

Errors

The request is rejected with 400 when:
  • both primary and objective are given
  • the headline is not one the run computes, with targets applied
  • a targets key does not name a target the blueprint declares
  • the blueprint has a trainable node but training_examples is missing or empty
  • the blueprint has no trainable node but training_examples is not empty
  • the blueprint’s trainable node does not take exactly one model through a models slot
  • the blueprint has more than one trainable node
  • the budget exceeds the platform ceiling
  • an overrides key is not one of the blueprint’s values or model slots, or is also searched over in search_space
  • an override is not literal (it holds a ${...} reference)
  • a model override targets the model the optimization fits, or names an archived tag
  • a required value is provided by neither overrides nor search_space
  • a training example’s class is not one of the target’s labels
  • a constraint bounds an objective the run does not compute, gives neither min nor max, or has a min above its max
The request is rejected with 422 when a field is malformed, including a primary or a constraint objective that is not written <target>.<objective>.
Starting with version 2.0.0, a malformed primary is rejected with 422 instead of 400.
The request is rejected with 403 (capability_locked) when the blueprint is not available to the caller’s organization, and with 404 when the blueprint is not found or a model override names an unknown tag. A run over a blueprint in a project is in that project. Creating it requires being able to modify the project: you get 403 when you can see the project but not modify it, and 404 when the blueprint is in a project you cannot see. The run’s jobs belong to the project’s creator, whoever starts it, and every training, validation, and calibration file must be one the project’s creator can see. Any other file returns 400. A blueprint outside any project, including a canonical blueprint, can’t be optimized directly: the request returns 400 with code project_required. Copy the blueprint into a project with Copy Blueprint and optimize the copy. v2.0.1+

Request

string
required
The blueprint to search — a blp_ ID. Must be visible to the caller’s organization.
object
required
How many trials to run.
  • max_trials (integer, required) — the most trials the run may spend. Minimum 1. A ceiling, not a quota: every trial is a distinct point of the search space, so a space offering fewer points than this runs only as many trials as it has points. Check the created run’s trial count for what it will actually do. Requests above the platform ceiling are rejected with 400.
array
required
Scoring examples — every trial’s eval scores against these. Each entry is an example, in the same shape Create Eval accepts.
string
The headline every trial is scored on and the run maximizes, as <target>.<objective> — e.g. state.macro_f1. Defaults to the blueprint’s own. Must name a target the blueprint declares and an objective the run computes for it, with targets applied. Mutually exclusive with objective.
string
deprecated
Deprecated: use primary. An objective of the blueprint’s own headline target, so that objective: "accuracy" on a blueprint headlined state.macro_f1 means primary: "state.accuracy". Mutually exclusive with primary.
string
Optional human label. Defaults to an empty string.
object
The parameter space to sample from. Keys must match tunable blueprint values (values.*). See Search space.
object
Per-target scoring overrides for every trial, keyed by target name. Each entry takes the same fields as an eval’s target override, and every field falls back to what the blueprint’s target declares, so a run that wants nothing different omits this entirely. A key must name a target the blueprint declares. An entry’s objectives replaces the target’s own list for this run, and may include objectives the target does not declare, such as the recall of one class. v2.0.0+
integer
Seed for the sampler. Minimum 0. Send the same seed with the same search space to reproduce a run’s trials; omit it for random sampling. v2.0.0+
object
Blueprint values and models set for every trial, rather than searched over, and kept in any blueprint promoted from one. Typically knowledge only you have about your use case, such as the states an operational-state blueprint classifies over. See Overrides.
A blueprint value written ${required} has no default: it must be given either here or as a value parameter of search_space, or the request is rejected with 400.
array
Fit examples, consumed by the fit and never scored. Required, and must be non-empty, when the blueprint has a trainable node. Omit it, or send it empty, for a blueprint with nothing to fit (e.g. one tuning inference-time knobs only). That blueprint’s trials are only scored and produce no fitted model.
A blueprint with more than one trainable node cannot be optimized yet.
Starting with version 2.0.1, a non-empty training_examples for a blueprint with no trainable node is rejected with 400, because nothing would use it.
array
Calibration examples: a family-specific held-out slice, e.g. Anomaly Discovery threshold calibration.
array | object
Bounds a trial must meet to be eligible as best_trial_id, replacing those the blueprint declares. Omit it to use the blueprint’s; send [] for none. Each entry names an objective the run computes, with a min, a max, or both. See Constraint. A trial is feasible when every bound holds. A trial with no value for a bounded objective cannot be judged, and is not eligible either.
Starting with version 2.0.0, constraints is an array of bounds on any objective the run computes, and the blueprint’s own constraints apply when you omit it. The earlier {"min_metric": [...]} form is deprecated but still accepted. Its entries become floors on the target the run maximizes. See Metric threshold.

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 kind of blueprint override the sampled value writes to: value or model.
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.

Overrides (overrides)

Blueprint values and models an optimization sets for every one of its trials, as opposed to the ones search_space samples per trial. Unknown keys are rejected.
object
Blueprint values to set, by name. Each must name one of the blueprint’s values, may not also be a value parameter of search_space, and must be literal: it may not hold a ${...} reference, at any depth.
object
Model slots to set, from slot name to a model registry tag. Each must name one of the blueprint’s model slots other than the one the optimization fits, and may not also be a model parameter of search_space. An unknown tag is a 404; an archived one, a 400.

Constraint (constraints[])

A bound on one objective the run computes: a floor, a ceiling, or both. v2.0.0+
string
required
The objective bounded, as <target>.<objective>, naming an objective the run computes for that target, with targets applied. For example, state.macro_f1, or state.recall_idle for a per-class objective added through targets.
number
The lowest acceptable value, inclusive.
number
The highest acceptable value, inclusive.
A constraint must give min, max, or both. Unknown keys are rejected.

Metric threshold (constraints.min_metric[])

Deprecated: use the array form of constraints. Each entry is a floor on an objective of the target the run maximizes, converted to a constraint with only a min. The run’s resolved constraints show the converted form.
string
required
Without class, the name of an objective the run computes for the target, such as macro_f1. With class, a catalog objective that reads one class, such as recall.
number
required
Minimum acceptable value, inclusive.
string
When set, the floor applies to metric read on this class. The run uses the per-class objective it already computes for that class if there is one. Otherwise, it adds one to the target’s objectives for the run, named <metric>_<class> (for example, recall_fault_bearing), and resolved_targets shows it.

Response

Returns 201 Created with the run in pending status. See Get Optimization for the full field list.
string
required
The run’s opt_ id.
string
required
Human label given on create. Empty when none was given.
string
required
The organization that owns the run.
string
required
The blueprint being tuned.
string
required
The headline each trial is scored on and the run maximizes, as <target>.<objective> — resolved at creation, so this is what is actually scored rather than what was asked for.
string
required
deprecated
Deprecated: read primary. The objective part of primary.
object
required
The objectives every trial computes, keyed by target name: the blueprint’s own declaration folded together with the request’s targets, resolved at creation. primary names one of these, as <target>.<name>. Read this rather than the blueprint’s metrics to know what is scored, since a request may replace a target’s objectives. Empty for an optimization created before this field was recorded. v2.0.0+
object
required
The parameter space the trials are sampled from, as given on create (empty when none was given).
object
required
The overrides given on create, applied to every trial (both maps empty when none were given).
object
required
The trial budget given on create.
array
required
The examples every trial is scored against, as resolved: named, and their inputs pinned with the CRC32C of the bytes used.
string
required
The run’s current lifecycle status; pending on creation.
object
required
Per-status trial counts, so a caller can render a progress bar without listing trials. All zero on a fresh run.
string
The project the run is in: its blueprint’s. This value is null outside any project. v2.0.0+
string
required
Subject id (usr_... or key_...) that created this run.
string
required
When the run was created (date-time).
array
The training examples given on create, as resolved. Absent when the blueprint’s fit needs none.
array
The calibration examples given on create, as resolved. Absent when none were given.
array
required
The bounds every trial is judged against, resolved at creation: the request’s, or else the blueprint’s, with the earlier min_metric form converted. Empty when there are none. See Constraint.
string
The trial the run picked as its winner: the highest-scoring feasible trial that completed. Set once the run ends, whether it completed, failed, or was cancelled, and absent when no trial qualifies.
object
The winning trial, inlined. null while the run is still going or when no trial qualifies.
string
When the run began executing. Absent while pending.
string
When the run reached a terminal status. Absent until then.
string
Why the run failed. Present only when status is failed.