> ## 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 /api/lens/query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# List Packages

> Page through your organization's packages, sorted by build, last run or name, searched, and filtered by blueprint or project

Requires [version 2.0.0](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0) or later of the Archetype platform.

## Overview

This endpoint returns a cursor-paginated page of your organization's packages. By default the
page is newest built first.

By default the page holds the packages outside projects and those of every project you can see.
Narrow it to one project, or to the packages outside any project, with `project_id`. Narrow it to
the packages holding one blueprint with `blueprint_id`: those are the packages that keep the
blueprint from being deleted. Search by name, description or id with `query`.

Set `include_latest_runs=true` to attach each package's most recent runs, so run history can be
rendered without a second call to `/api/agents/instances`.

Choose a different ordering with the `sort` and `order` parameters.

## Request

**limit** `integer` (default: 100)

Page size. Minimum `1`, maximum `1000`.

**after** `string`

Forward cursor: return the packages ranked after it in the current sort order. Pass the
`next_cursor` of the previous page to fetch the next page. The cursor is opaque: never build it
from package fields. Mutually exclusive with `before`.

**before** `string`

Backward cursor: return the packages ranked before it in the current sort order. Pass the
`prev_cursor` of the current page to walk back. The cursor is opaque: never build it from
package fields. Mutually exclusive with `after`.

**sort** `string` (default: created\_at)

Sort field: `created_at` (default) ranks packages by when they were built, `last_run_at` by the
newest of their runs you may see, with never-run packages last under `desc`, and `name` alphabetically, ignoring case. A cursor is only
valid under the sort it was minted for. Replaying it with a different `sort` is rejected with
HTTP status code `400`.

**order** `string`

Sort direction: `asc` or `desc`. Defaults per field: `desc` for `created_at` and `last_run_at`,
`asc` for `name`. Keep it constant while paging with a cursor: a cursor replayed
under the other order is accepted but pages the other way from it.

**query** `string`

Case-insensitive substring match over the package name, description and id. Omit for no search
filter.

**include\_latest\_runs** `boolean` (default: false)

Include each package's most recent runs as `latest_runs`. Off by default because it costs an
extra query per page.

**blueprint\_id** `string`

Restrict to packages holding this blueprint (`blp_` id, exact match).

**project\_id** `string`

Filter by project. Omitted: the packages outside projects and those of every project you can
see. A project's `prj_` id: that project's packages only (`404` when it does not exist or you
cannot see it). `none`: the packages outside any project.

## Response

**data** `array` *required*

The page, in the requested `sort` and `order` (by default newest built first) in both cursor
directions. Each entry is a package, with the same fields as [Get
Package](https://docs.archetypeai.app/api-reference/agents/packages/get-package.md) returns, including `latest_runs` when you
set `include_latest_runs=true`.

**has\_more** `boolean` *required*

True when more results exist beyond this page in the direction of travel.

**next\_cursor** `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.

**prev\_cursor** `string`

Cursor to step back the way this page was reached. Pass it as `before` after paging forward, or
as `after` after paging backward. `null` on a request that carried no cursor.

```bash cURL theme={"system"}
curl "$ATAI_API_URL/api/agents/packages?limit=20" \
  -H "Authorization: Bearer $ATAI_API_KEY"
```

```bash cURL - Packages Holding a Blueprint theme={"system"}
curl "$ATAI_API_URL/api/agents/packages?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
  -H "Authorization: Bearer $ATAI_API_KEY"
```

```bash cURL - Most Recently Run, With Run History theme={"system"}
curl "$ATAI_API_URL/api/agents/packages?sort=last_run_at&include_latest_runs=true" \
  -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}/api/agents/packages",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"limit": 20},
)

if response.status_code == 200:
    page = response.json()
    for package in page["data"]:
        print(package["id"], package["status"])
else:
    print(f"Error: {response.json()['errors']}")
```

```javascript JavaScript theme={"system"}
const response = await fetch(
  `${process.env.ATAI_API_URL}/api/agents/packages?limit=20`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
    }
  }
);

const body = await response.json();

if (response.ok) {
  body.data.forEach((pkg) => console.log(pkg.id, pkg.status));
} else {
  console.error('Error:', body.errors);
}
```

```json 200 - Page of packages theme={"system"}
{
  "data": [
    {
      "id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
      "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
      "name": "Pump line 3",
      "description": "Pump A monitor",
      "created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
      "target": {"kind": "platform"},
      "status": "ready",
      "blueprints": [
        {
          "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
          "resolved_models": {
            "embedder": "mdl_01jc7k2p9xq4vm8n3t5rbh6dzw"
          }
        }
      ],
      "project_id": null,
      "created_at": "2026-10-21T15:10:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "prev_cursor": null
}
```

```json 400 - Invalid request theme={"system"}
{
  "errors": [
    {
      "code": "<error_code>",
      "message": "Invalid cursor or `blueprint_id`, or both `after` and `before`.",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

## Important Notes

> [!NOTE]
>
> * Passing both `after` and `before` returns `400`, as does a malformed `blueprint_id`, a repeated parameter, or a parameter of the wrong type.
> * A malformed cursor, or a cursor replayed under a different `sort`, returns `400`.
> * A `project_id` that does not exist or that you cannot see returns `404`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.