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 best_trial_id 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 is complete, 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.

Request

string
required
Optimization opt_ ID.

Response

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.
object
required
The parameter space the run samples from: parameters, a map of parameter name to an entry carrying a kind (value, model, or fitting) and a spec domain.
object
required
The run’s budget knobs — max_trials.
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.
For the per-trial details behind progress, page the results from the List Optimization Trials endpoint.
string
required
Subject id (usr_... or key_...) that created this run.
string
required
Creation timestamp (date-time).
string
Set upon successful completion to indicate the feasible trial the run picked as its winner. This value is null for non-terminal optimization runs.
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.
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.

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 as part of this calculation; infeasible trials are included in completed.
integer
required
The number of trials created but not yet dispatched.
integer
required
The number of trials currently running.
integer
required
The number of trials that finished successfully.
integer
required
The number of trials that failed.
integer
required
The number of trials that were cancelled.
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. No other bucket overlaps.