Skip to main content
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

  • after and before are mutually exclusive — send at most one of them.
  • Results are ordered newest first in both cursor directions, so render data as returned.
  • query matches the agent name, id, bundle id, and blueprint key; bundle_id and blueprint_id are exact-match filters.