curl "$ATAI_API_URL/agents/optimizations?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations?status=running" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-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}"}
cursor = None
while True:
params = {"limit": 100}
if cursor:
params["after"] = cursor
response = requests.get(f"{base_url}/agents/optimizations", headers=headers, params=params)
page = response.json()
for run in page["data"]:
progress = run["progress"]
done = progress["completed"] + progress["failed"] + progress["cancelled"]
print(f"{run['id']} {run['name']} [{run['status']}] {done}/{run['budget']['max_trials']}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(run => {
const { completed, failed, cancelled } = run.progress;
const done = completed + failed + cancelled;
console.log(`${run.id} ${run.name} [${run.status}] ${done}/${run.budget.max_trials}`);
});
{
"data": [
{
"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]}
}
}
},
"budget": {"max_trials": 24},
"constraints": null,
"training_examples": null,
"calibration_examples": null,
"validation_examples": [
{
"name": "file_def456",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "running",
"progress": {
"pending": 9,
"running": 3,
"completed": 12,
"failed": 0,
"cancelled": 0,
"infeasible": 2
},
"best_trial_id": null,
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": null,
"error": null
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid query parameter.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Optimizations
List Optimizations
Page through optimization runs, optionally filtered by status, name, and/or blueprint
GET
/
agents
/
optimizations
curl "$ATAI_API_URL/agents/optimizations?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations?status=running" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-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}"}
cursor = None
while True:
params = {"limit": 100}
if cursor:
params["after"] = cursor
response = requests.get(f"{base_url}/agents/optimizations", headers=headers, params=params)
page = response.json()
for run in page["data"]:
progress = run["progress"]
done = progress["completed"] + progress["failed"] + progress["cancelled"]
print(f"{run['id']} {run['name']} [{run['status']}] {done}/{run['budget']['max_trials']}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(run => {
const { completed, failed, cancelled } = run.progress;
const done = completed + failed + cancelled;
console.log(`${run.id} ${run.name} [${run.status}] ${done}/${run.budget.max_trials}`);
});
{
"data": [
{
"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]}
}
}
},
"budget": {"max_trials": 24},
"constraints": null,
"training_examples": null,
"calibration_examples": null,
"validation_examples": [
{
"name": "file_def456",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "running",
"progress": {
"pending": 9,
"running": 3,
"completed": 12,
"failed": 0,
"cancelled": 0,
"infeasible": 2
},
"best_trial_id": null,
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": null,
"error": null
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid query parameter.",
"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 the caller’s optimization runs, newest first. Each row carries the same trial-status breakdown asGET /agents/optimizations/{optimization_id} —
the platform aggregates the whole page in a single query rather than fanning out per row, so a
listing can render a progress bar per run without a read each.
Request
integer
default:"100"
Page size. Minimum
1, maximum 1000.string
Forward cursor: return runs older than the one with this ID. Pass the
next_cursor of the
previous page to fetch the next page. Mutually exclusive with before.This parameter is mutually exclusive with
before; using both results in an error.string
Backward cursor: return runs newer than the one with this ID. Pass the
prev_cursor of the
current page to walk back. Mutually exclusive with after.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.Response
array
required
The page, ordered newest first. Each entry is an optimization run, in the same format
Get Optimization returns. Pages are
always sorted newest-first, 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.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.curl "$ATAI_API_URL/agents/optimizations?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations?status=running" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/optimizations?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-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}"}
cursor = None
while True:
params = {"limit": 100}
if cursor:
params["after"] = cursor
response = requests.get(f"{base_url}/agents/optimizations", headers=headers, params=params)
page = response.json()
for run in page["data"]:
progress = run["progress"]
done = progress["completed"] + progress["failed"] + progress["cancelled"]
print(f"{run['id']} {run['name']} [{run['status']}] {done}/{run['budget']['max_trials']}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(run => {
const { completed, failed, cancelled } = run.progress;
const done = completed + failed + cancelled;
console.log(`${run.id} ${run.name} [${run.status}] ${done}/${run.budget.max_trials}`);
});
{
"data": [
{
"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]}
}
}
},
"budget": {"max_trials": 24},
"constraints": null,
"training_examples": null,
"calibration_examples": null,
"validation_examples": [
{
"name": "file_def456",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "running",
"progress": {
"pending": 9,
"running": 3,
"completed": 12,
"failed": 0,
"cancelled": 0,
"infeasible": 2
},
"best_trial_id": null,
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": null,
"error": null
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid query parameter.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Was this page helpful?