curl "$ATAI_API_ENDPOINT/agents/instances?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?status=running" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?bundle_id=bnd_01jc9pd42kzq7v8n3h5m6rtx0w" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?package_id=pkg_01jcb2x7m4qv8n3h5t6rk9dzs0" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
cursor = None
while True:
params = {"limit": 100, "status": "running"}
if cursor:
params["after"] = cursor
response = requests.get(f"{base_url}/agents/instances", headers=headers, params=params)
page = response.json()
for agent in page["data"]:
print(f"{agent['id']} {agent['name']} [{agent['status']}] blueprint={agent['blueprint']}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20', status: 'running' });
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(agent => {
console.log(`${agent.id} ${agent.name} [${agent.status}] blueprint=${agent.blueprint}`);
});
{
"data": [
{
"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": "running",
"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
}
],
"has_more": true,
"next_cursor": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Instances
List Agents
Page through agent runs, filtered by status, bundle, package, or blueprint
GET
/
agents
/
instances
curl "$ATAI_API_ENDPOINT/agents/instances?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?status=running" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?bundle_id=bnd_01jc9pd42kzq7v8n3h5m6rtx0w" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?package_id=pkg_01jcb2x7m4qv8n3h5t6rk9dzs0" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
cursor = None
while True:
params = {"limit": 100, "status": "running"}
if cursor:
params["after"] = cursor
response = requests.get(f"{base_url}/agents/instances", headers=headers, params=params)
page = response.json()
for agent in page["data"]:
print(f"{agent['id']} {agent['name']} [{agent['status']}] blueprint={agent['blueprint']}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20', status: 'running' });
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(agent => {
console.log(`${agent.id} ${agent.name} [${agent.status}] blueprint=${agent.blueprint}`);
});
{
"data": [
{
"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": "running",
"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
}
],
"has_more": true,
"next_cursor": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor.",
"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 List Sessions instead. To move existing code, see Migrating from Bundles and Instances.
Overview
This endpoint returns a cursor-paginated page of agents (bundle and package runs), newest first. The page holds the runs the caller may see: their own, or every run in the organization for an org admin. An agent exists only as a run, so lifecycle status lives on the agent itself. Filter by status, by the bundle or package a run came from, or by the blueprint that bundle or package holds.Request
Forward cursor: return agents older than the one with this id. Pass the
next_cursor of the previous page to fetch the next page. Mutually exclusive with before.Backward cursor: return agents newer than the one with this id. Pass the
prev_cursor of the current page to walk back. Mutually exclusive with after.Filter to a single lifecycle status (e.g.
running). Omit for all statuses. One of running, paused, completed, failed, cancelled.Case-insensitive substring match over the agent name, id, bundle id, package id, and blueprint key. Omit for no search filter.
Restrict to runs of this package (
pkg_ id, exact match). These are the runs that keep the
package from being deleted. v2.0.0+Restrict to runs of this blueprint (
blp_ id, exact match), whether the run’s bundle pins it or its package holds it.Response
Cursor for the next page in the same direction — pass it as
after when paging forward, or as before when you supplied before. null when has_more is false.Cursor to step back the way this page was reached — pass it as
before after a forward page,
or as after after a backward one. null when the request carried no cursor.Agent object
The bundle this agent was run from (provenance). Absent for a run of a package, which carries
package_id instead.The package this agent was run from (provenance). Absent for a run of a bundle, which carries
bundle_id instead. v2.0.0+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+The I/O binding this run was started with. Absent only on runs recorded before I/O bindings
were stored.
One or more input refs; multiple files are staged on the same JOS input port. v1.1.13+
The single output ref, when the run was started with one. Omitted (the default): the runner
writes one output per input, named after the input. v1.1.13+
External executor’s job id for the current run (a JOS
job_ id). Present once the run has been dispatched; lets clients query JOS for run progress.curl "$ATAI_API_ENDPOINT/agents/instances?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?status=running" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?bundle_id=bnd_01jc9pd42kzq7v8n3h5m6rtx0w" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/instances?package_id=pkg_01jcb2x7m4qv8n3h5t6rk9dzs0" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
cursor = None
while True:
params = {"limit": 100, "status": "running"}
if cursor:
params["after"] = cursor
response = requests.get(f"{base_url}/agents/instances", headers=headers, params=params)
page = response.json()
for agent in page["data"]:
print(f"{agent['id']} {agent['name']} [{agent['status']}] blueprint={agent['blueprint']}")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const params = new URLSearchParams({ limit: '20', status: 'running' });
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(agent => {
console.log(`${agent.id} ${agent.name} [${agent.status}] blueprint=${agent.blueprint}`);
});
{
"data": [
{
"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": "running",
"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
}
],
"has_more": true,
"next_cursor": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
afterandbeforeare agent ids, and are mutually exclusive — send at most one of them. Passing both, or a malformed one, returns400.- Org admins see every run in the organization; other callers see only their own runs.
- Results are ordered newest first in both cursor directions, so render
dataas returned. querymatches the agent name, id, bundle id, and blueprint key;bundle_idandblueprint_idare exact-match filters.- A run of a package in a project is owned by the project’s creator, so other members of the organization see it only if they are org admins. v2.0.0+
Was this page helpful?