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. Trials are listed newest first — highest trial_number first — regardless of which direction you’re paging through them. A trial records the point it sampled from the parent’s search space, what that point scored, and whether it satisfied the run’s feasibility constraints. A trial’s state moves independently from the parent: a failed trial does not fail the run. 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 with a lower trial_number than this one. Pass the next_cursor of the previous page to fetch the next page. Mutually exclusive with before.
string
Backward cursor: return trials with a higher trial_number than this one. Pass the prev_cursor of the current page to walk back. Mutually exclusive with after.
string
Filter to a single lifecycle status. Omit for all statuses. One of pending, running, completed, failed, cancelled.

Response

array
required
The page, newest trial first (highest trial_number).
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 parent run’s opt_ id.
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
Creation timestamp (date-time).
number
Convenience projection of metrics_report’s objective value. null until the trial has scored.
boolean
Feasibility against the parent’s constraints. null while pending; only true trials qualify for the parent’s best_trial_id.
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 scored metrics report, in the same shape an eval returns. null until the trial has scored.
string
When the trial dispatched; null before then.
string
When the trial finished; null while unfinished.
string
Failure details if the trial failed; otherwise null.