> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# List Bundles

> Page through the bundles available to your organization

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.9](/release-notes/1.1.x#v1-1-9) or later of the Archetype platform.
</Callout>

## 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

<ParamField query="limit" type="integer" default="100">
  Page size. Minimum `1`, maximum `1000`.
</ParamField>

<ParamField query="after" type="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`.
</ParamField>

<ParamField query="before" type="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`.
</ParamField>

<ParamField query="query" type="string">
  Case-insensitive substring match over the bundle name and id. Omit for no search filter.
</ParamField>

<ParamField query="blueprint_id" type="string">
  Restrict to bundles pinning this blueprint (`blp_` id, exact match).
</ParamField>

<ParamField query="include_latest_runs" type="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.
</ParamField>

## Response

<ResponseField name="data" type="array" required>
  The page, newest first. Each entry is a bundle.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  True when more results exist beyond this page in the direction of travel.
</ResponseField>

<ResponseField name="next_cursor" type="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.
</ResponseField>

### Bundle object

<ResponseField name="id" type="string" required>
  TypeID-encoded bundle identifier (`bnd_` prefix).
</ResponseField>

<ResponseField name="name" type="string" required>
  Human label for the bundle.
</ResponseField>

<ResponseField name="description" type="string" required>
  Human description of the bundle.
</ResponseField>

<ResponseField name="blueprint_id" type="string" required>
  The pinned blueprint's immutable `blp_` id. Resolve its key via the blueprint registry when needed.
</ResponseField>

<ResponseField name="values" type="object" required>
  User value overrides, layered over the blueprint defaults at run time.
</ResponseField>

<ResponseField name="status" type="string" required>
  Build lifecycle of the bundle: `building`, `ready`, or `failed`.
</ResponseField>

<ResponseField name="is_canonical" type="boolean" required>
  True for a canonical (platform-authored) bundle, visible to every org.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Creation timestamp (date-time).
</ResponseField>

<ResponseField name="org_id" type="string">
  Owning org; omitted for a canonical bundle.
</ResponseField>

<ResponseField name="model" type="string">
  Model override; omitted when the bundle uses the blueprint's default.
</ResponseField>

<ResponseField name="artifacts" type="object">
  Artifact links attached to the bundle.
</ResponseField>

<ResponseField name="latest_runs" type="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.
</ResponseField>

### Run summary object (`latest_runs[]`)

<ResponseField name="id" type="string" required>
  TypeID-encoded agent identifier (`agt_` prefix).
</ResponseField>

<ResponseField name="status" type="string" required>
  Agent lifecycle status: `running`, `paused`, `completed`, `failed`, or `canceled`.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Creation timestamp (date-time).
</ResponseField>

<ResponseField name="started_at" type="string">
  When the run started; `null` before then.
</ResponseField>

<ResponseField name="completed_at" type="string">
  When the run finished; `null` while unfinished.
</ResponseField>

<ResponseField name="job_id" type="string">
  External executor's job id for this run (a JOS `job_` id). Present once the run has been dispatched.
</ResponseField>

<ResponseField name="error" type="string">
  Failure detail; `null` unless the run failed.
</ResponseField>

<RequestExample>
  ```bash cURL - First Page theme={"system"}
  curl "$ATAI_API_URL/agents/bundles?limit=20" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```bash cURL - Search, With Run History theme={"system"}
  curl "$ATAI_API_URL/agents/bundles?query=pump&include_latest_runs=true" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```bash cURL - By Pinned Blueprint theme={"system"}
  curl "$ATAI_API_URL/agents/bundles?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```python Python theme={"system"}
  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)}")
  ```

  ```javascript JavaScript theme={"system"}
  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}`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "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",
        "model": null,
        "values": {},
        "artifacts": {
          "calibration": "s3://.../knn_index"
        },
        "status": "ready",
        "is_canonical": false,
        "created_at": "2026-08-11T15:02:19Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
  ```

  ```json 200 - With include_latest_runs=true theme={"system"}
  {
    "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",
        "model": null,
        "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
  }
  ```

  ```json 200 - Empty page theme={"system"}
  {
    "data": [],
    "has_more": false,
    "next_cursor": null
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * `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.
</Note>