curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
run = response.json()
print(f"{run['id']} is now {run['status']}")
elif response.status_code == 409:
print("Optimization already terminal")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`${body.id} is now ${body.status}`);
} else if (response.status === 409) {
console.error('Optimization already terminal');
} 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]}
}
}
},
"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": "cancelled",
"progress": {
"pending": 0,
"running": 0,
"completed": 12,
"failed": 0,
"cancelled": 12,
"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
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization already terminal.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Optimizations
Cancel Optimization
Cancel a pending or running optimization run
POST
/
agents
/
optimizations
/
{optimization_id}
/
cancel
curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
run = response.json()
print(f"{run['id']} is now {run['status']}")
elif response.status_code == 409:
print("Optimization already terminal")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`${body.id} is now ${body.status}`);
} else if (response.status === 409) {
console.error('Optimization already terminal');
} 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]}
}
}
},
"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": "cancelled",
"progress": {
"pending": 0,
"running": 0,
"completed": 12,
"failed": 0,
"cancelled": 12,
"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
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization already terminal.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.12 or later of the Archetype platform.
Overview
This endpoint cancels a pending or running optimization and returns it in itscancelled state.
It also cancels any non-terminal trials, so the trial list does not leave a stale row behind.
Trials that had already completed keep their results and stay counted in progress.completed.
A run that is already terminal — that is, one whose status is one of completed, failed, or
cancelled — has nothing to cancel and returns HTTP status code 409.
One use case for this endpoint is to cancel a running optimization prior to deleting it using
Delete Optimization, since deleting
an optimization will fail with a
409 HTTP status code if its state is non-terminal.Request
string
required
Optimization
opt_ id.Response
Returns the cancelled run, in the same format returned by Get Optimization.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 that was being maximized.
object
required
The parameter space the run sampled from.
object
required
The run’s budget knobs —
max_trials.array
required
The scoring examples as resolved.
string
required
Optimization lifecycle status;
cancelled after a successful cancel.object
required
Per-status trial counts. Trials that were still pending or running move to
cancelled.string
required
Subject id (
usr_... or key_...) that created this run.string
required
Creation timestamp (date-time).
string
The trial the run picked as its winner. Set by the promotion step on successful completion, so
it is
null on a cancelled run.string
When the run started;
null if it never did.string
When the run finished;
null while unfinished.string
Failure detail;
null unless the run failed.curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
run = response.json()
print(f"{run['id']} is now {run['status']}")
elif response.status_code == 409:
print("Optimization already terminal")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`${body.id} is now ${body.status}`);
} else if (response.status === 409) {
console.error('Optimization already terminal');
} 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]}
}
}
},
"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": "cancelled",
"progress": {
"pending": 0,
"running": 0,
"completed": 12,
"failed": 0,
"cancelled": 12,
"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
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization already terminal.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Was this page helpful?