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 bundles, newest first. 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.

Request

integer
default:"100"
Page size. Minimum 1, maximum 1000.
string
Forward cursor: return bundles older than the one with this id. Pass the next_cursor of the previous page (or the id of its last bundle) to fetch the next page. Mutually exclusive with before.
string
Backward cursor: return bundles newer than the one with this id. Pass the id of the first bundle of the current page to walk back. Mutually exclusive with after.
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, newest first. Each entry is a bundle.
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.

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 org.
string
required
Creation timestamp (date-time).
string
Owning org; omitted for a canonical bundle.
string
Model override; omitted when the bundle uses the blueprint’s default.
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 canceled.
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.

Important Notes

  • after and before are mutually exclusive — send at most one of them.
  • include_latest_runs=true costs an extra join per bundle in the page; leave it off for plain listings.
  • latest_runs is 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 status is normally ready; building/failed exist for the eventual image-build path.