curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import time
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"
while True:
response = requests.get(f"{base_url}/agents/optimizations/{optimization_id}", headers=headers)
run = response.json()
progress = run["progress"]
done = progress["completed"] + progress["failed"] + progress["cancelled"]
print(f"{run['status']}: {done}/{run['budget']['max_trials']} trials, {progress['infeasible']} infeasible")
if run["status"] in ("completed", "failed", "cancelled"):
break
time.sleep(15)
if run["best_trial_id"]:
print(f"Winner: {run['best_trial_id']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
const { completed, failed, cancelled, infeasible } = body.progress;
const done = completed + failed + cancelled;
console.log(`${body.status}: ${done}/${body.budget.max_trials} trials, ${infeasible} infeasible`);
if (body.best_trial_id) {
console.log(`Winner: ${body.best_trial_id}`);
}
} else {
console.error('Error:', body.errors);
}
{
"id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"objective": "macro_f1",
"search_space": {
"parameters": {
"window_size": {
"kind": "value",
"spec": {"type": "categorical", "values": [512, 1024, 2048]}
},
"n_neighbors": {
"kind": "fitting",
"spec": {"type": "int_range", "min": 3, "max": 25}
}
}
},
"budget": {"max_trials": 24},
"constraints": {
"min_metric": [
{"metric": "recall", "class": "fault_bearing", "min_value": 0.8}
]
},
"training_examples": [
{
"name": "file_abc123",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_abc123", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"calibration_examples": null,
"validation_examples": [
{
"name": "file_def456",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "completed",
"progress": {
"pending": 0,
"running": 0,
"completed": 22,
"failed": 2,
"cancelled": 0,
"infeasible": 5
},
"best_trial_id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": "2026-09-18T13:47:05Z",
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Optimizations
Get Optimization
Retrieve one optimization run and its trial-status breakdown
GET
/
agents
/
optimizations
/
{optimization_id}
curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import time
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"
while True:
response = requests.get(f"{base_url}/agents/optimizations/{optimization_id}", headers=headers)
run = response.json()
progress = run["progress"]
done = progress["completed"] + progress["failed"] + progress["cancelled"]
print(f"{run['status']}: {done}/{run['budget']['max_trials']} trials, {progress['infeasible']} infeasible")
if run["status"] in ("completed", "failed", "cancelled"):
break
time.sleep(15)
if run["best_trial_id"]:
print(f"Winner: {run['best_trial_id']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
const { completed, failed, cancelled, infeasible } = body.progress;
const done = completed + failed + cancelled;
console.log(`${body.status}: ${done}/${body.budget.max_trials} trials, ${infeasible} infeasible`);
if (body.best_trial_id) {
console.log(`Winner: ${body.best_trial_id}`);
}
} else {
console.error('Error:', body.errors);
}
{
"id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"objective": "macro_f1",
"search_space": {
"parameters": {
"window_size": {
"kind": "value",
"spec": {"type": "categorical", "values": [512, 1024, 2048]}
},
"n_neighbors": {
"kind": "fitting",
"spec": {"type": "int_range", "min": 3, "max": 25}
}
}
},
"budget": {"max_trials": 24},
"constraints": {
"min_metric": [
{"metric": "recall", "class": "fault_bearing", "min_value": 0.8}
]
},
"training_examples": [
{
"name": "file_abc123",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_abc123", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"calibration_examples": null,
"validation_examples": [
{
"name": "file_def456",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "completed",
"progress": {
"pending": 0,
"running": 0,
"completed": 22,
"failed": 2,
"cancelled": 0,
"infeasible": 5
},
"best_trial_id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": "2026-09-18T13:47:05Z",
"error": null
}
{
"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 one optimization run by itsopt_ 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.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.curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import time
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"
while True:
response = requests.get(f"{base_url}/agents/optimizations/{optimization_id}", headers=headers)
run = response.json()
progress = run["progress"]
done = progress["completed"] + progress["failed"] + progress["cancelled"]
print(f"{run['status']}: {done}/{run['budget']['max_trials']} trials, {progress['infeasible']} infeasible")
if run["status"] in ("completed", "failed", "cancelled"):
break
time.sleep(15)
if run["best_trial_id"]:
print(f"Winner: {run['best_trial_id']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
const { completed, failed, cancelled, infeasible } = body.progress;
const done = completed + failed + cancelled;
console.log(`${body.status}: ${done}/${body.budget.max_trials} trials, ${infeasible} infeasible`);
if (body.best_trial_id) {
console.log(`Winner: ${body.best_trial_id}`);
}
} else {
console.error('Error:', body.errors);
}
{
"id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"objective": "macro_f1",
"search_space": {
"parameters": {
"window_size": {
"kind": "value",
"spec": {"type": "categorical", "values": [512, 1024, 2048]}
},
"n_neighbors": {
"kind": "fitting",
"spec": {"type": "int_range", "min": 3, "max": 25}
}
}
},
"budget": {"max_trials": 24},
"constraints": {
"min_metric": [
{"metric": "recall", "class": "fault_bearing", "min_value": 0.8}
]
},
"training_examples": [
{
"name": "file_abc123",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_abc123", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"calibration_examples": null,
"validation_examples": [
{
"name": "file_def456",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "completed",
"progress": {
"pending": 0,
"running": 0,
"completed": 22,
"failed": 2,
"cancelled": 0,
"infeasible": 5
},
"best_trial_id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": "2026-09-18T13:47:05Z",
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Was this page helpful?