Agents API
List Agents
Page through agent runs, filtered by status, bundle, or blueprint
GET
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint returns a cursor-paginated page of agents (bundle runs), newest first. An agent exists only as a run, so lifecycle status lives on the agent itself. Filter by status, by the bundle a run came from, or by the blueprint that bundle pinned.Request
integer
default:"100"
Page size. Minimum
1, maximum 1000.string
Forward cursor: return agents older than the one with this id. Pass the
next_cursor of the previous page (or the id of its last agent) to fetch the next page. Mutually exclusive with before.string
Backward cursor: return agents newer than the one with this id. Pass the id of the first agent of the current page to walk back. Mutually exclusive with
after.string
Filter to a single lifecycle status (e.g.
running). Omit for all statuses. One of running, paused, completed, failed, canceled.string
Case-insensitive substring match over the agent name, id, bundle id, and blueprint key. Omit for no search filter.
string
Restrict to runs of this bundle (
bnd_ id, exact match).string
Restrict to runs whose bundle pins this blueprint (
blp_ id, exact match).Response
array
required
The page, newest first. Each entry is an agent.
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.Agent object
string
required
TypeID-encoded agent identifier (
agt_ prefix).string
required
Name of the agent (a run’s name is its bundle’s name).
string
required
Organization identifier the agent belongs to.
string
required
The bundle this agent was run from (provenance).
string
required
Human-readable pinned blueprint reference (its key), e.g.
osm.string
required
Immutable blueprint id the bundle pinned.
string
required
Agent lifecycle status:
running, paused, completed, failed, or canceled.string
required
Creation timestamp (date-time).
object
The I/O binding this run was started with;
null when none is recorded.string
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.string
When the run started;
null before then.string
When the run finished;
null while unfinished.string
Failure detail;
null unless the run failed.Important Notes
afterandbeforeare mutually exclusive — send at most one of them.- 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.