curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/cancel",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
agent = response.json()
print(f"Agent {agent['id']} is now {agent['status']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/cancel`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`Agent ${body.id} is now ${body.status}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"name": "Pump A monitor",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"bundle_id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"blueprint": "osm",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
],
"sink": null
},
"status": "cancelled",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": "2026-08-11T15:14:02Z",
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent already terminal.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Instances
Cancel Agent
Cancel a running or paused agent run
POST
/
agents
/
instances
/
{agent_id}
/
cancel
curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/cancel",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
agent = response.json()
print(f"Agent {agent['id']} is now {agent['status']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/cancel`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`Agent ${body.id} is now ${body.status}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"name": "Pump A monitor",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"bundle_id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"blueprint": "osm",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
],
"sink": null
},
"status": "cancelled",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": "2026-08-11T15:14:02Z",
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent already terminal.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.9 or later of the Archetype platform.
Starting with version 2.0.1, this endpoint is removed from the platform. Use Cancel Session instead. To move existing code, see Migrating from Bundles and Instances.
Overview
This endpoint cancels an agent run and returns the updated agent. You can only cancel agents whose status is eitherrunning or paused. If the agent has
already reached one of the terminal states (completed, failed, or cancelled), this returns
HTTP status code 409.
Once an agent has been cancelled, it cannot be resumed or restarted. If you want to temporarily
stop an agent, pause it using the Pause Agent endpoint.
You must cancel agents which are running or paused before deleting them.
Request
Response
Returns the cancelled agent.How the agent executes:
batch, a run that finishes on its own, or serving, an agent that
stays up to answer queries. v1.1.13+External executor’s job ID for the current run (a JOS
job_ ID). Present once the run has been dispatched.curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/cancel",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
agent = response.json()
print(f"Agent {agent['id']} is now {agent['status']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/cancel`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`Agent ${body.id} is now ${body.status}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"name": "Pump A monitor",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"bundle_id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"blueprint": "osm",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
],
"sink": null
},
"status": "cancelled",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": "2026-08-11T15:14:02Z",
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent already terminal.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Was this page helpful?