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

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 to fetch the next page. Mutually exclusive with before.
string
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.
string
Filter to a single lifecycle status (e.g. running). Omit for all statuses. One of running, paused, completed, failed, cancelled.
string
Filter by project. Omitted: the runs outside projects and those of every project you can see. A project’s prj_ id: that project’s runs only (404 when it does not exist or you cannot see it). none to list runs outside any project. v2.0.0+
string
Case-insensitive substring match over the agent name, id, bundle id, package id, and blueprint key. Omit for no search filter.
string
Restrict to runs of this bundle (bnd_ id, exact match).
string
Restrict to runs of this package (pkg_ id, exact match). These are the runs that keep the package from being deleted. v2.0.0+
string
Restrict to runs of this blueprint (blp_ id, exact match), whether the run’s bundle pins it or its package holds it.

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.
string
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

string
required
TypeID-encoded agent identifier (agt_ prefix).
string
required
Name of the agent: its bundle’s name, or for a run of a package, the package’s name.
string
required
Organization identifier the agent belongs to.
string
The bundle this agent was run from (provenance). Absent for a run of a package, which carries package_id instead.
string
The package this agent was run from (provenance). Absent for a run of a bundle, which carries bundle_id instead. v2.0.0+
string
required
Human-readable pinned blueprint reference (its key), e.g. osm.
string
required
Immutable blueprint id the bundle pinned.
string
The project the run is in: its package’s. This value is null outside any project, including every run of a bundle. v2.0.0+
string
required
Agent lifecycle status: running, paused, completed, failed, or cancelled.
string
required
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+
string
required
Creation timestamp (date-time).
object
The I/O binding this run was started with. Absent only on runs recorded before I/O bindings were stored.
array
required
One or more input refs; multiple files are staged on the same JOS input port. v1.1.13+
object
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+
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 began executing. Absent until it has been dispatched.
string
When the run reached a terminal status. Absent while it is running or paused.
string
Why the run failed. Present only when status is failed.

Important Notes

  • after and before are agent ids, and are mutually exclusive — send at most one of them. Passing both, or a malformed one, returns 400.
  • 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 data as returned.
  • query matches the agent name, id, bundle id, and blueprint key; bundle_id and blueprint_id are 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+