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

# Run Bundle

> Start a run of a bundle by binding its inputs and outputs

<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 starts a run of a bundle and returns the created agent.

The request supplies only the run's I/O binding — parameters and model come from the bundle. Each run is a separate agent: to re-run, call this endpoint again.

## Request

<ParamField path="bundle_id" type="string" required>
  Bundle `bnd_` id to run.
</ParamField>

<ParamField body="connectors" type="object" required>
  Source/sink connectors binding this run's I/O. Bound at run time — I/O stays external to the agent ("build once, run anywhere").
</ParamField>

<ParamField body="connectors.source" type="array" required>
  One or more input refs; multiple files are staged on the same JOS input port. Each entry is a data ref.
</ParamField>

<ParamField body="connectors.sink" type="object">
  Optional output ref. Omitted (the default): the runner writes one output per input, named after the input. Provided: all output goes to this single file. Passed to the runner as the `output_ref` job-config key.
</ParamField>

### Data ref

<ParamField body="type" type="string" required>
  Storage kind, e.g. `file` or `dataset`.
</ParamField>

<ParamField body="id" type="string" required>
  Identifier within that storage kind, e.g. `file_abc123`.
</ParamField>

<ParamField body="format" type="string">
  Optional format hint, e.g. `csv`.
</ParamField>

## Response

Returns `202 Accepted` with the created agent.

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

<ResponseField name="name" type="string" required>
  Name of the agent (a run's name is its bundle's name).
</ResponseField>

<ResponseField name="org_id" type="string" required>
  Organization identifier the agent belongs to.
</ResponseField>

<ResponseField name="bundle_id" type="string" required>
  The bundle this agent was run from (provenance).
</ResponseField>

<ResponseField name="blueprint" type="string" required>
  Human-readable pinned blueprint reference (its key), e.g. `osm`.
</ResponseField>

<ResponseField name="blueprint_id" type="string" required>
  Immutable blueprint id the bundle pinned.
</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="connectors" type="object">
  The I/O binding this run was started with; `null` when none is recorded.
</ResponseField>

<ResponseField name="job_id" type="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.
</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="error" type="string">
  Failure detail; `null` unless the run failed.
</ResponseField>

<RequestExample>
  ```bash cURL - One Input theme={"system"}
  curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "connectors": {
        "source": [
          {"type": "file", "id": "file_abc123", "format": "csv"}
        ]
      }
    }'
  ```

  ```bash cURL - Multiple Inputs, Single Output theme={"system"}
  curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "connectors": {
        "source": [
          {"type": "file", "id": "file_abc123", "format": "csv"},
          {"type": "file", "id": "file_def456", "format": "csv"}
        ],
        "sink": {"type": "file", "id": "file_ghi789"}
      }
    }'
  ```

  ```python Python theme={"system"}
  import os
  import requests

  base_url = os.environ["ATAI_API_URL"]
  api_key = os.environ["ATAI_API_KEY"]

  response = requests.post(
      f"{base_url}/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json",
      },
      json={
          "connectors": {
              "source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
          }
      },
  )

  if response.status_code == 202:
      agent = response.json()
      print(f"Run accepted: {agent['id']} (status {agent['status']})")
  else:
      print(f"Error: {response.json()['errors']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    `${process.env.ATAI_API_URL}/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        connectors: {
          source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
        }
      })
    }
  );

  const body = await response.json();

  if (response.status === 202) {
    console.log(`Run accepted: ${body.id} (status ${body.status})`);
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 202 - Run accepted theme={"system"}
  {
    "id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
    "name": "Pump A monitor",
    "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
    "bundle_id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
    "blueprint": "osm",
    "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
    "connectors": {
      "source": [
        {"type": "file", "id": "file_abc123", "format": "csv"}
      ],
      "sink": null
    },
    "status": "running",
    "job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
    "created_at": "2026-08-11T15:10:00Z",
    "started_at": null,
    "completed_at": null,
    "error": null
  }
  ```

  ```json 404 - Bundle not found theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Bundle not found.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * Parameters and model come from the bundle, not the run request — the body carries only connectors.
  * Omit `sink` to get one output per input, named after the input; provide it to funnel all output into a single file.
  * Each run is a new agent. To re-run, call this endpoint again rather than restarting an existing agent.
  * Track progress with `GET /agents/instances/{agent_id}`, its `/events` and `/logs` pages, and `/results` for outputs.
</Note>