curl "$ATAI_API_URL/agents/bundles?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?query=pump&include_latest_runs=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?sort=name" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?sort=created_at&order=asc" \
-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.get(
f"{base_url}/agents/bundles",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 20, "include_latest_runs": "true"},
)
page = response.json()
for bundle in page["data"]:
runs = bundle.get("latest_runs") or []
print(f"{bundle['name']} ({bundle['id']}) status={bundle['status']} runs={len(runs)}")
const params = new URLSearchParams({ limit: '20', include_latest_runs: 'true' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/bundles?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(bundle => {
const runs = bundle.latest_runs ?? [];
console.log(`${bundle.name} (${bundle.id}) status=${bundle.status} runs=${runs.length}`);
});
{
"data": [
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z",
"latest_runs": [
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"status": "completed",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": "2026-08-11T15:18:41Z",
"error": null
}
]
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
Bundles
List Bundles
Page through the bundles available to your organization
GET
/
agents
/
bundles
curl "$ATAI_API_URL/agents/bundles?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?query=pump&include_latest_runs=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?sort=name" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?sort=created_at&order=asc" \
-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.get(
f"{base_url}/agents/bundles",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 20, "include_latest_runs": "true"},
)
page = response.json()
for bundle in page["data"]:
runs = bundle.get("latest_runs") or []
print(f"{bundle['name']} ({bundle['id']}) status={bundle['status']} runs={len(runs)}")
const params = new URLSearchParams({ limit: '20', include_latest_runs: 'true' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/bundles?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(bundle => {
const runs = bundle.latest_runs ?? [];
console.log(`${bundle.name} (${bundle.id}) status=${bundle.status} runs=${runs.length}`);
});
{
"data": [
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z",
"latest_runs": [
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"status": "completed",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": "2026-08-11T15:18:41Z",
"error": null
}
]
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint returns a cursor-paginated page of bundles. By default the page is most recently run first, with never-run bundles last. Filter by pinned blueprint, search by name or id, and optionally include each bundle’s most recent runs so run history can be rendered without a second call to/agents/instances.
Choose a different ordering with the sort and order parameters.
Request
integer
default:"100"
Page size. Minimum
1, maximum 1000.string
Forward cursor: return the bundles that follow this one in the current sort order. Pass the
next_cursor of the previous page to fetch the next page. Mutually exclusive with before. Valid only under the sort it was minted for. v1.1.11+string
Backward cursor: return the bundles that precede this one in the current sort order. Mutually exclusive with
after. Valid only under the sort it was minted for. v1.1.11+string
default:"last_run_at"
Sort field:
last_run_at (default) ranks bundles by their newest visible run, created_at by
creation, name alphabetically. A cursor is only valid under the sort it was minted for;
replaying it with a different sort is rejected with HTTP status code 400. v1.1.11+string
Sort direction:
asc or desc. Defaults per field — desc for last_run_at and
created_at, asc for name. Keep it constant while paging with a cursor. v1.1.11+string
Case-insensitive substring match over the bundle name and id. Omit for no search filter.
string
Restrict to bundles pinning this blueprint (
blp_ id, exact match).boolean
default:"false"
Include each bundle’s most recent runs as
latest_runs. Off by default — it costs an extra join per bundle in the page.Response
array
required
The page, in the requested
sort and order — in both cursor directions, so render it as
returned. Each entry is a bundle. The default (sort omitted) is most recently run first:
ordered by each bundle’s newest visible run, with never-run bundles last (newest created first
within either group). Run recency is scoped like latest_runs — to the caller’s org and own
runs — so that order is per-viewer. v1.1.11+boolean
required
True when more results exist beyond this page in the direction of travel.
string
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.string
Cursor to step back the way this page was reached — pass it as
before after paging forward,
or as after after paging backward. null on a request that carried no cursor: the newest
page has nothing to step back to. Provided because the cursor is opaque, so a client cannot
mint the backward anchor from a row itself. v1.1.12+Bundle object
string
required
TypeID-encoded bundle identifier (
bnd_ prefix).string
required
Human label for the bundle.
string
required
Human description of the bundle.
string
required
The pinned blueprint’s immutable
blp_ id. Resolve its key via the blueprint registry when needed.object
required
User value overrides, layered over the blueprint defaults at run time.
string
required
Build lifecycle of the bundle:
building, ready, or failed.boolean
required
true for a canonical (platform-authored) bundle, visible to every organization.string
required
Creation timestamp (date-time).
string
Owning org; omitted for a canonical bundle.
object
required
Per-slot model overrides: slot name to registry tag. If this object is empty, the bundle uses
the blueprint’s default for every slot.
object
Artifact links attached to the bundle.
array
The bundle’s five most recent runs, newest first. Present only when the read asked for it via
include_latest_runs=true; an empty array means the bundle has never been run. Runs are scoped to the caller’s org, so a canonical bundle shows only the caller’s own runs of it.Run summary object (latest_runs[])
string
required
TypeID-encoded agent identifier (
agt_ prefix).string
required
Agent lifecycle status:
running, paused, completed, failed, or cancelled.string
required
Creation timestamp (date-time).
string
When the run started;
null before then.string
When the run finished;
null while unfinished.string
External executor’s job id for this run (a JOS
job_ id). Present once the run has been dispatched.string
Failure detail;
null unless the run failed.curl "$ATAI_API_URL/agents/bundles?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?query=pump&include_latest_runs=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?sort=name" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/bundles?sort=created_at&order=asc" \
-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.get(
f"{base_url}/agents/bundles",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 20, "include_latest_runs": "true"},
)
page = response.json()
for bundle in page["data"]:
runs = bundle.get("latest_runs") or []
print(f"{bundle['name']} ({bundle['id']}) status={bundle['status']} runs={len(runs)}")
const params = new URLSearchParams({ limit: '20', include_latest_runs: 'true' });
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/bundles?${params}`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(bundle => {
const runs = bundle.latest_runs ?? [];
console.log(`${bundle.name} (${bundle.id}) status=${bundle.status} runs=${runs.length}`);
});
{
"data": [
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z",
"latest_runs": [
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"status": "completed",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": "2026-08-11T15:10:04Z",
"completed_at": "2026-08-11T15:18:41Z",
"error": null
}
]
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
Important Notes
afterandbeforeare mutually exclusive — send at most one of them.- A cursor snapshots the edge row’s sort key, so it is only valid under the
sortit was minted for. Keepsortandorderconstant while paging; replaying a cursor under a differentsortreturns400rather than a wrong or empty page. v1.1.11+ - Every sort resolves to a full keyset ending in
id. Because TypeIDs are random UUIDv4,idis only the final tiebreak, never a sort key of its own. v1.1.11+ include_latest_runs=truecosts an extra join per bundle in the page; leave it off for plain listings.latest_runsis capped at the five most recent runs and is scoped to the caller’s org.- A bundle in Phase 1 is built on create, so
statusis normallyready;building/failedexist for the eventual image-build path.
Was this page helpful?