curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/pause" \
-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/pause",
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/pause`,
{
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": "paused",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not running, or is a serving agent.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Pause is not supported by the active runtime.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Instances
Pause Agent
Pause a running agent
POST
/
agents
/
instances
/
{agent_id}
/
pause
curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/pause" \
-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/pause",
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/pause`,
{
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": "paused",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not running, or is a serving agent.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Pause is not supported by the active runtime.",
"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. Run packages through deployments and sessions instead: deploy a package with Create Deployment, then open a session on it with Create Session. To move existing code, see Migrating from Bundles and Instances.
Overview
This endpoint pauses a running agent and returns the updated agent with statuspaused.
Only a running agent can be paused; anything else returns 409. A serving agent (one run with
mode: serving) also returns 409: it holds a worker for the life of its run and refuses queries
while paused, so there is nothing to hold it in place for; cancel it instead. If the active runtime cannot
hold a run in place, the request returns 501; batch runs, for example, only support cancel.
Resume it later with Resume Agent.
Request
Response
Returns the paused 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/pause" \
-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/pause",
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/pause`,
{
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": "paused",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not running, or is a serving agent.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Pause is not supported by the active runtime.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- Pause is valid only from
running. Calling it on a paused or terminal agent returns409. - A serving agent cannot be paused; calling this endpoint on one returns
409. Cancel it instead. - A paused agent can be resumed or cancelled.
- A
501means the active runtime cannot hold a run in place (batch runs, for example, only support cancel); cancel the agent instead.
Was this page helpful?