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

# Get Package

> Retrieve one package by id, with its build status and the model each slot resolved to

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 one package by its `pkg_` id.

Poll it after [Create Package](https://docs.archetypeai.app/api-reference/agents/packages/create-package.md) until `status` is
`ready` or `failed`. Run a `ready` package with [Create
Agent](https://docs.archetypeai.app/api-reference/agents/instances/create-agent.md).

Set `include_latest_runs=true` to attach the package's most recent runs, so a package detail view
can show run history without a second call to `/api/agents/instances`. [v2.0.0+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0)

## Request

**package\_id** `string` *required*

Package `pkg_` id.

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

Include the package's most recent runs as `latest_runs`. Off by default because it costs an
extra query. [v2.0.0+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0)

## Response

**id** `string` *required*

TypeID-encoded package identifier (`pkg_` prefix).

**org\_id** `string` *required*

Organization the package belongs to.

**name** `string` *required*

Human label given on create, or the blueprint's name when none was given. Also the name of every
run of the package.

**description** `string` *required*

Human description given on create. Empty when none was given.

**created\_by** `string` *required*

Subject id (`usr_...` or `key_...`) that created the package.

**target** `object` *required*

Where the package is meant to run, as `{"kind": "platform"}` or `{"kind": "edge"}`.

**status** `string` *required*

Build status: `building`, `ready`, or `failed`. You can run the package once it is `ready`.

**blueprints** `array` *required*

The blueprints the package holds, in the order they were given.

**blueprints\[].blueprint\_id** `string` *required*

The blueprint's immutable `blp_` id.

**blueprints\[].resolved\_models** `object` *required*

What each model slot resolved to when the package was built: slot name to an `mdl_` id (a model
from the model registry) or an `aar_` id (an artifact an optimization trial produced, as named
in a promoted blueprint). Slots bound to an artifact the blueprint names itself are absent.
Empty when no slot named a registry entry.

**project\_id** `string`

The project the package is in, which is its blueprint's project. `null` outside any project.

**created\_at** `string` *required*

When the package was built (date-time).

**latest\_runs** `array`

The package's five most recent runs that you may see, newest first. Present only when the
request asked for it via `include_latest_runs=true`; an empty array means none of its runs are
visible to you. [v2.0.0+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0)

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

A thin slice of a run, without its name or connectors. Fetch the full run with [Get
Agent](https://docs.archetypeai.app/api-reference/agents/instances/get-agent.md).

**id** `string` *required*

TypeID-encoded agent identifier (`agt_` prefix).

**status** `string` *required*

Agent lifecycle status, for example `deploying`, `running`, `completed`, or `failed`.

**created\_at** `string` *required*

When the run was created (date-time).

**started\_at** `string`

When the run began executing. Absent until it has been dispatched.

**completed\_at** `string`

When the run reached a terminal status. Absent while it is unfinished.

**job\_id** `string`

The executor's job id for this run. Present once the run has been dispatched.

**error** `string`

Why the run failed. Present only when `status` is `failed`.

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

```bash cURL - With Run History theme={"system"}
curl "$ATAI_API_URL/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0?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/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
    headers={"Authorization": f"Bearer {api_key}"},
)

if response.status_code == 200:
    package = response.json()
    print(f"Package {package['id']} is {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/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
    }
  }
);

const body = await response.json();

if (response.ok) {
  console.log(`Package ${body.id} is ${body.status}`);
} else {
  console.error('Error:', body.errors);
}
```

```json 200 - Package theme={"system"}
{
  "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"
}
```

```json 404 - Package not found theme={"system"}
{
  "errors": [
    {
      "code": "not_found",
      "message": "Package 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0' not found",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

## Important Notes

> [!NOTE]
>
> * A `404` means the package does not exist, belongs to another organization, or is in a project you cannot see.
> * A `failed` package cannot be run. Fix the blueprint and build a new package.


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