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

Overview

This endpoint returns a cursor-paginated list of one run’s trials. Each trial is one sampled point of the search space with its status, objective_value, feasibility, and full metrics_report once scored. A trial’s state moves independently from the parent: a failed trial does not fail the run. Trials can be filtered by status and feasible, and sorted by trial_number (the default), objective_value, or completed_at, in either direction. Trials without a value for the active sort — unscored under objective_value, unfinished under completed_at — are placed last in both directions. The after and before cursors are opaque sort-key snapshots. Passing both, or a malformed one, returns HTTP status code 400, and a cursor minted under one sort is rejected under another. 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 from one another.

Request

string
required
Parent optimization opt_ id.
integer
default:"100"
Page size. Minimum 1, maximum 1000.
string
Forward cursor: return trials ranked after the edge trial (the one next_cursor names). Pass the next_cursor of the previous page. Mutually exclusive with before.
The cursor is opaque and only meaningful under the same sort it was minted for. A cursor replayed under a different sort is rejected with 400.
string
Backward cursor: return trials ranked before the edge trial. Pass the prev_cursor of the current page. Mutually exclusive with after.
string
Filter to a single lifecycle status. Omit for all statuses. One of pending, running, completed, failed, cancelled.
boolean
Filter by the trial’s feasible field. true returns trials that satisfied every constraint; false returns trials that missed at least one. Omit for all.
Trials that have not scored yet, and scored trials that could not be judged against the constraints, have feasible = null and are excluded by either value.
string
default:"trial_number"
Sort field: trial_number, objective_value, or completed_at. Defaults to trial_number, the listing’s original order. Every sort ends in trial_number as the final tiebreak, since it is unique within an optimization.
string
Sort direction: asc or desc. Omit for the sort’s default, which is desc for every trial sort today. The cursor format is sort-specific and must stay constant while paging; order does not change the cursor’s shape, but a page uses it to decide which direction to walk.

Response

array
required
The page, ordered by the request’s sort and order (default trial_number desc). Trials with no value for the active sort — unscored under objective_value, unfinished under completed_at — are placed last in both directions. Each entry is a trial object.
boolean
required
True when more results exist beyond this page in the direction of travel.
string
Cursor to continue in the direction of travel: pass as after on a forward page, as before when the request used before. null when has_more is false.
string
Cursor to step back the way the page was reached. null when the request carried no cursor.

Trial object

Fields beyond the always-present ones fill in as the trial advances: started_at when it dispatches, metrics_report / objective_value / feasible / completed_at on success, error on failure.
string
required
TypeID-encoded trial identifier (otr_ prefix).
string
required
The optimization run this trial belongs to.
integer
required
1-based ordinal within the parent run. Dense and deterministic.
object
required
The sampled point in the parent’s search space, as {parameter_name: value}. Opaque shape — the value’s type varies per parameter and is defined by the parent’s search_space.
string
required
Trial lifecycle status: pending, running, completed, failed, or cancelled.
string
required
When the trial was sampled (date-time).
number
Convenience projection of metrics_report’s objective value. Absent while the trial has not scored.
boolean
Feasibility against the parent’s constraints. Absent while pending, and on a scored trial that could not be judged because a bounded objective has no value. Only true trials qualify for the parent’s best_trial_id.
Starting with version 2.0.0, a completed trial can have no feasible value when a bounded objective has no value. The run counts it in progress.unjudged.
Only trials for which feasible is true qualify to be selected as the best_trial_id. However, you can promote infeasible trials. Whether or not that’s a good idea is your decision.
object
The trial’s full scoring results, as described by the documentation for the Get Eval endpoint an eval returns. Present once the trial is completed.
object
The blueprint this trial was promoted into, by Promote Trial. null until the trial is promoted, or after the promoted blueprint was deleted. A trial can be promoted at most once; a second call is rejected with 409.
  • id (string, required) — the promoted blueprint’s blp_ id.
  • blueprint_key (string, required) — the blueprint’s catalog key. A trial-promoted blueprint carries the default key <base>-<trial_id> unless the promote request supplied one.
  • name (string, required) — display name, from the promoted blueprint’s document.
string
When the trial began executing. Absent while pending.
string
When the trial reached a terminal status. Absent until then.
string
Why the trial failed, or, on a cancelled trial, why it was not started. Absent otherwise.