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

Overview

This endpoint returns one optimization run by its opt_ ID, with a trial-status breakdown so a caller can render a progress bar without listing trials. Poll it to follow a run from pending through running to completed, failed, or cancelled, and to read the winning trial — both its ID, in best_trial_id, and the trial itself, inlined as best_trial — once the run has picked a winner.
The winning trial is not automatically promoted into a blueprint. To promote the winning trial once the run has ended, use the Promote Trial endpoint to promote the trial whose ID is found in best_trial_id.
Returns a 404 HTTP status code both when the specified optimization ID is unknown and when it belongs to another organization. These two cases are intentionally indistinguishable. A run in a project you cannot see also returns 404.

Request

string
required
Optimization opt_ ID.

Response

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>. 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): parameters, a map of parameter name to an entry carrying a kind (value or model) and a spec domain. See Search space.
object
required
The overrides given on create, applied to every trial: values and models maps (both empty when none were given). See Overrides.
object
required
The trial budget given on create — max_trials.
array
required
The examples every trial is scored against, as resolved: named, and their inputs pinned with the CRC32C of the bytes used. Each entry is a resolved example.
string
required
The run’s current 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. See Progress object.
For the per-trial details behind progress, page the results from the List Optimization Trials endpoint.
string
The project the run is in: its blueprint’s. This 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).
string
The trial the run picked as its winner: the highest-scoring feasible trial that completed. A trial that could not be judged against the constraints is not eligible. Set once the run ends, whether it completed, failed, or was cancelled, and absent when no trial qualifies.
The trial specified by best_trial_id is not automatically promoted into a blueprint. To do so, you must explicitly send the value of best_trial_id to the Promote Trial endpoint as the value of its trial_id parameter.
object
The winning trial, inlined so you don’t have to go hunting through the trials list for best_trial_id. Same shape as one entry returned by List Optimization Trials. null while the run is still going, when no trial qualifies, or on the list endpoint, which does not inline it.
array
The training examples given on create, as resolved: named, and their inputs pinned with the CRC32C of the bytes used. Absent when the blueprint’s fit needs none.
array
The calibration examples given on create, resolved the same way. 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.
Starting with version 2.0.0, constraints is always present, as an array of bounds, rather than the min_metric object given on create.
string
When the run began executing (date-time). Absent while pending.
string
When the run reached a terminal status (date-time). Absent until then.
string
Why the run failed. Present only when status is failed.

Progress object (progress)

Every trial ever created for the run is counted; a completed trial stays in completed after the run itself moves on.
To get the total number of trials created for the run, calculate pending + running + completed + failed + cancelled. Do not add infeasible or unjudged as part of this calculation; those trials are included in completed.
integer
required
The number of trials sampled but not yet started.
integer
required
The number of trials currently being trained and scored.
integer
required
The number of trials that finished and were scored (including infeasible and unjudged ones).
integer
required
The number of trials that stopped with an error.
integer
required
The number of trials stopped by canceling the run.
integer
required
The number of trials that reached completed but violated the run’s feasibility constraints. Not eligible to win. This bucket overlaps completed: such a trial is counted in both.
integer
required
The number of trials that reached completed but could not be judged against the run’s constraints, because a bounded objective has no value. Not eligible to win. This bucket overlaps completed: such a trial is counted in both. No other bucket overlaps. v2.0.0+