curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?status=completed" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"
cursor = None
while True:
params = {"limit": 100, "status": "completed"}
if cursor:
params["after"] = cursor
response = requests.get(
f"{base_url}/agents/optimizations/{optimization_id}/trials",
headers=headers,
params=params,
)
page = response.json()
for trial in page["data"]:
mark = "" if trial["feasible"] else " (infeasible)"
print(f"#{trial['trial_number']:>3} {trial['objective_value']} {trial['trial_values']}{mark}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20', status: 'completed' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(trial => {
const mark = trial.feasible ? '' : ' (infeasible)';
console.log(`#${trial.trial_number} ${trial.objective_value} ${JSON.stringify(trial.trial_values)}${mark}`);
});
{
"data": [
{
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"trial_number": 24,
"trial_values": {"window_size": 1024, "n_neighbors": 11},
"status": "completed",
"objective_value": 0.89,
"feasible": true,
"metrics_report": {
"schema_version": "v1",
"primary": {"target": "state", "name": "macro_f1", "value": 0.89},
"targets": {
"state": {
"type": "category",
"aggregate": {"macro_f1": 0.89, "accuracy": 0.93},
"class_names": ["running", "idle", "fault_bearing"],
"per_class": {
"precision": [0.94, 0.9, 0.79],
"recall": [0.97, 0.87, 0.82],
"f1": [0.95, 0.88, 0.8],
"support": [4120, 1880, 260]
},
"confusion_matrix": [
[3996, 106, 18],
[199, 1636, 45],
[31, 16, 213]
]
}
}
},
"created_at": "2026-09-18T13:38:12Z",
"started_at": "2026-09-18T13:38:20Z",
"completed_at": "2026-09-18T13:47:01Z",
"error": null
},
{
"id": "otr_01jcb2t4k9r2wq6nv8h3mdzx5p",
"optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"trial_number": 23,
"trial_values": {"window_size": 512, "n_neighbors": 4},
"status": "completed",
"objective_value": 0.84,
"feasible": false,
"metrics_report": null,
"created_at": "2026-09-18T13:29:44Z",
"started_at": "2026-09-18T13:29:51Z",
"completed_at": "2026-09-18T13:37:58Z",
"error": null
}
],
"has_more": true,
"next_cursor": "<cursor>",
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid query parameter.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Optimizations
List Optimization Trials
Page through one optimization run’s trials, optionally filtered by status
GET
/
agents
/
optimizations
/
{optimization_id}
/
trials
curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?status=completed" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"
cursor = None
while True:
params = {"limit": 100, "status": "completed"}
if cursor:
params["after"] = cursor
response = requests.get(
f"{base_url}/agents/optimizations/{optimization_id}/trials",
headers=headers,
params=params,
)
page = response.json()
for trial in page["data"]:
mark = "" if trial["feasible"] else " (infeasible)"
print(f"#{trial['trial_number']:>3} {trial['objective_value']} {trial['trial_values']}{mark}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20', status: 'completed' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(trial => {
const mark = trial.feasible ? '' : ' (infeasible)';
console.log(`#${trial.trial_number} ${trial.objective_value} ${JSON.stringify(trial.trial_values)}${mark}`);
});
{
"data": [
{
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"trial_number": 24,
"trial_values": {"window_size": 1024, "n_neighbors": 11},
"status": "completed",
"objective_value": 0.89,
"feasible": true,
"metrics_report": {
"schema_version": "v1",
"primary": {"target": "state", "name": "macro_f1", "value": 0.89},
"targets": {
"state": {
"type": "category",
"aggregate": {"macro_f1": 0.89, "accuracy": 0.93},
"class_names": ["running", "idle", "fault_bearing"],
"per_class": {
"precision": [0.94, 0.9, 0.79],
"recall": [0.97, 0.87, 0.82],
"f1": [0.95, 0.88, 0.8],
"support": [4120, 1880, 260]
},
"confusion_matrix": [
[3996, 106, 18],
[199, 1636, 45],
[31, 16, 213]
]
}
}
},
"created_at": "2026-09-18T13:38:12Z",
"started_at": "2026-09-18T13:38:20Z",
"completed_at": "2026-09-18T13:47:01Z",
"error": null
},
{
"id": "otr_01jcb2t4k9r2wq6nv8h3mdzx5p",
"optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"trial_number": 23,
"trial_values": {"window_size": 512, "n_neighbors": 4},
"status": "completed",
"objective_value": 0.84,
"feasible": false,
"metrics_report": null,
"created_at": "2026-09-18T13:29:44Z",
"started_at": "2026-09-18T13:29:51Z",
"completed_at": "2026-09-18T13:37:58Z",
"error": null
}
],
"has_more": true,
"next_cursor": "<cursor>",
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid query parameter.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
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 — highesttrial_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.curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?status=completed" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"
cursor = None
while True:
params = {"limit": 100, "status": "completed"}
if cursor:
params["after"] = cursor
response = requests.get(
f"{base_url}/agents/optimizations/{optimization_id}/trials",
headers=headers,
params=params,
)
page = response.json()
for trial in page["data"]:
mark = "" if trial["feasible"] else " (infeasible)"
print(f"#{trial['trial_number']:>3} {trial['objective_value']} {trial['trial_values']}{mark}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20', status: 'completed' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(trial => {
const mark = trial.feasible ? '' : ' (infeasible)';
console.log(`#${trial.trial_number} ${trial.objective_value} ${JSON.stringify(trial.trial_values)}${mark}`);
});
{
"data": [
{
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"trial_number": 24,
"trial_values": {"window_size": 1024, "n_neighbors": 11},
"status": "completed",
"objective_value": 0.89,
"feasible": true,
"metrics_report": {
"schema_version": "v1",
"primary": {"target": "state", "name": "macro_f1", "value": 0.89},
"targets": {
"state": {
"type": "category",
"aggregate": {"macro_f1": 0.89, "accuracy": 0.93},
"class_names": ["running", "idle", "fault_bearing"],
"per_class": {
"precision": [0.94, 0.9, 0.79],
"recall": [0.97, 0.87, 0.82],
"f1": [0.95, 0.88, 0.8],
"support": [4120, 1880, 260]
},
"confusion_matrix": [
[3996, 106, 18],
[199, 1636, 45],
[31, 16, 213]
]
}
}
},
"created_at": "2026-09-18T13:38:12Z",
"started_at": "2026-09-18T13:38:20Z",
"completed_at": "2026-09-18T13:47:01Z",
"error": null
},
{
"id": "otr_01jcb2t4k9r2wq6nv8h3mdzx5p",
"optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"trial_number": 23,
"trial_values": {"window_size": 512, "n_neighbors": 4},
"status": "completed",
"objective_value": 0.84,
"feasible": false,
"metrics_report": null,
"created_at": "2026-09-18T13:29:44Z",
"started_at": "2026-09-18T13:29:51Z",
"completed_at": "2026-09-18T13:37:58Z",
"error": null
}
],
"has_more": true,
"next_cursor": "<cursor>",
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid query parameter.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Was this page helpful?