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 the caller’s optimization runs, newest first by default. Use sort and order to rank them by creation time, name, or score instead. Each row carries the same progress trial-status breakdown as Get Optimization, so a listing can render a progress bar per run without a read each. Filter by lifecycle status, by the blueprint being tuned, or by project, or search by name and ID. Without a project filter, the page holds the runs outside projects and those of every project you can see.
The training_examples, validation_examples, and calibration_examples arrays are always empty on rows returned from this endpoint, and best_trial is not inlined. Real-world runs inline hundreds of examples per row, and loading them for a list page would pull tens of MB per request. To see a run’s examples, fetch it with Get Optimization.
after and before are opaque cursors that snapshot the sort key of the run at the edge of a page. Passing both, passing a malformed one, or replaying a cursor under a different sort than the one it was minted for returns HTTP status 400.

Request

integer
default:"100"
Page size. Minimum 1, maximum 1000.
string
Forward cursor: return the runs ranked after the edge of the previous page in the current sort order. Pass the next_cursor of the previous page to fetch the next page. Valid only under the sort it was minted for.
This parameter is mutually exclusive with before; using both results in an error.
string
Backward cursor: return the runs ranked before the edge of the current page in the current sort order. Pass the prev_cursor of the current page to walk back.
This parameter is mutually exclusive with after; using both results in an error.
string
Filter to a single lifecycle status (e.g. pending, completed). Omit for all statuses. One of pending, running, completed, failed, cancelled. This is an exact-match filter.
string
Case-insensitive substring match over the run name and ID. Omit for no search filter.
string
Restrict to runs targeting the blueprint with the specified blp_ ID. This is an exact-match filter.
string
Filter by project. Omitted: the runs outside projects and those of every project you can see. A project’s prj_ id: that project’s runs only (404 when it does not exist or you cannot see it). none: the runs outside any project. v2.0.0+
string
default:"created_at"
Sort field: created_at (default) ranks runs by creation, name alphabetically (case-sensitive), and score by the best trial’s objective_value. Runs that have no best trial yet are placed last in both directions. A cursor is only valid under the sort it was minted for; replaying it with a different sort is rejected with HTTP status code 400. v1.1.13+
string
Sort direction: asc or desc. Defaults per field: desc for created_at and score, asc for name. Keep it constant while paging with a cursor. v1.1.13+
boolean
default:"false"
When true, the response includes total. Off by default because it costs an extra count per request. v2.0.1+

Response

array
required
The page, ordered by the active sort and order (newest first by default). Each entry is an optimization run, in the same format Get Optimization returns. A backward page is flipped so it still reads in the active sort direction, so you should always render the contents of data as returned.
Since each row in data includes a progress property that summarizes the progress that run is making, you don’t need to perform a secondary lookup to get that information.
training_examples, validation_examples, and calibration_examples are always [] on entries returned by this endpoint, regardless of what the run actually declared, and best_trial is null. Fetch the run with Get Optimization to see whether it truly has no training set or its examples are simply not loaded.
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.
integer
How many optimizations match the request’s filters across all pages, ignoring limit and the cursor. Present only when you set include_total=true. v2.0.1+