curl -X POST "$ATAI_API_ENDPOINT/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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",
"primary": "state.macro_f1",
"objective": "macro_f1",
"search_space": {
"parameters": {
"window_size": {
"kind": "value",
"spec": {"type": "categorical", "values": [512, 1024, 2048]}
}
}
},
"overrides": {"values": {}, "models": {}},
"budget": {"max_trials": 24},
"validation_examples": [
{
"name": "pump-a-validate",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "cancelled",
"progress": {
"pending": 0,
"running": 0,
"completed": 0,
"failed": 0,
"cancelled": 3,
"infeasible": 0,
"unjudged": 0
},
"best_trial": null,
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": "2026-09-18T12:05:10Z"
}
{
"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_ENDPOINT/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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",
"primary": "state.macro_f1",
"objective": "macro_f1",
"search_space": {
"parameters": {
"window_size": {
"kind": "value",
"spec": {"type": "categorical", "values": [512, 1024, 2048]}
}
}
},
"overrides": {"values": {}, "models": {}},
"budget": {"max_trials": 24},
"validation_examples": [
{
"name": "pump-a-validate",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "cancelled",
"progress": {
"pending": 0,
"running": 0,
"completed": 0,
"failed": 0,
"cancelled": 3,
"infeasible": 0,
"unjudged": 0
},
"best_trial": null,
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": "2026-09-18T12:05:10Z"
}
{
"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 cancelled run still picks a winner: if any feasible trial completed, the best of them is set as
best_trial_id.
For a run in a project, you get 403 when you can see the
project but not modify it, and 404 when you cannot see the project. v2.0.0+
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
Response
Returns the cancelled run, in the same format returned by Get Optimization.The overrides given on create, applied to every trial (both maps empty when none were given).
The trial the run picked as its winner: the highest-scoring feasible trial that completed. Set
once the run ends — including when it is cancelled — and absent when no trial qualifies.
The winning trial, inlined.
null when no trial qualifies. See Get
Optimization.curl -X POST "$ATAI_API_ENDPOINT/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/cancel" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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",
"primary": "state.macro_f1",
"objective": "macro_f1",
"search_space": {
"parameters": {
"window_size": {
"kind": "value",
"spec": {"type": "categorical", "values": [512, 1024, 2048]}
}
}
},
"overrides": {"values": {}, "models": {}},
"budget": {"max_trials": 24},
"validation_examples": [
{
"name": "pump-a-validate",
"ordinal": 1,
"inputs": [
{"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
]
}
],
"status": "cancelled",
"progress": {
"pending": 0,
"running": 0,
"completed": 0,
"failed": 0,
"cancelled": 3,
"infeasible": 0,
"unjudged": 0
},
"best_trial": null,
"created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
"created_at": "2026-09-18T12:02:44Z",
"started_at": "2026-09-18T12:02:51Z",
"completed_at": "2026-09-18T12:05:10Z"
}
{
"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?