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

# Get Optimization

> Retrieve one optimization run and its trial-status breakdown

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

## Overview

This endpoint returns one optimization run by its `opt_` ID, with a trial-status breakdown so a
caller can render a progress bar without listing trials.

Poll it to follow a run from `pending` through `running` to `completed`, `failed`, or `cancelled`,
and to read `best_trial_id` once the run has picked a winner.

<Note>
  The winning trial is *not* automatically promoted into a blueprint. To promote the winning
  trial once the run is complete, use the [Promote
  Trial](/api-reference/agents/optimizations/promote-trial) endpoint to promote the trial whose
  ID is found in `best_trial_id`.
</Note>

Returns a `404` HTTP status code both when the specified optimization ID is unknown and when it
belongs to another organization. These two cases are intentionally indistinguishable.

## Request

<ParamField path="optimization_id" type="string" required>
  Optimization `opt_` ID.
</ParamField>

## Response

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

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

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

<ResponseField name="blueprint_id" type="string" required>
  The blueprint being searched.
</ResponseField>

<ResponseField name="objective" type="string" required>
  The primary metric name being maximized.
</ResponseField>

<ResponseField name="search_space" type="object" required>
  The parameter space the run samples from: `parameters`, a map of parameter name to an entry
  carrying a `kind` (`value`, `model`, or `fitting`) and a `spec` domain.
</ResponseField>

<ResponseField name="budget" type="object" required>
  The run's budget knobs — `max_trials`.
</ResponseField>

<ResponseField name="validation_examples" type="array" required>
  The scoring examples as resolved: named, their inputs pinned with the CRC32C of the bytes used,
  and their ground-truth declarations filled in from the blueprint's defaults.
</ResponseField>

<ResponseField name="status" type="string" required>
  Optimization lifecycle status: `pending`, `running`, `completed`, `failed`, or `cancelled`.
</ResponseField>

<ResponseField name="progress" type="object" required>
  Per-status trial counts, so a caller can render a progress bar without listing trials. All zero
  on a fresh run.

  <Note>
    For the per-trial details behind `progress`, page the results from the [List Optimization
    Trials](/api-reference/agents/optimizations/list-optimization-trials) endpoint.
  </Note>
</ResponseField>

<ResponseField name="created_by" type="string" required>
  Subject id (`usr_...` or `key_...`) that created this run.
</ResponseField>

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

<ResponseField name="best_trial_id" type="string">
  Set upon successful completion to indicate the feasible trial the run picked as its winner.
  This value is `null` for non-terminal optimization runs.

  <Note>
    The trial specified by `best_trial_id` is *not* automatically promoted into a blueprint. To
    do so, you must explicitly send the value of `best_trial_id` to the [Promote
    Trial](/api-reference/agents/optimizations/promote-trial) endpoint as the value of its
    `trial_id` parameter.
  </Note>
</ResponseField>

<ResponseField name="training_examples" type="array">
  The fit examples as resolved; `null` when the run supplied none.
</ResponseField>

<ResponseField name="calibration_examples" type="array">
  The calibration examples as resolved; `null` when the run supplied none.
</ResponseField>

<ResponseField name="constraints" type="object">
  The per-trial feasibility constraints; `null` when the run supplied none.
</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>

### Progress object (`progress`)

Every trial ever created for the run is counted; a completed trial stays in `completed` after
the run itself moves on.

<Note>
  To get the total number of trials created for the run, calculate `pending + running +
      completed + failed + cancelled`. Do not add `infeasible` as part of this calculation;
  infeasible trials are included in `completed`.
</Note>

<ResponseField name="pending" type="integer" required>
  The number of trials created but not yet dispatched.
</ResponseField>

<ResponseField name="running" type="integer" required>
  The number of trials currently running.
</ResponseField>

<ResponseField name="completed" type="integer" required>
  The number of trials that finished successfully.
</ResponseField>

<ResponseField name="failed" type="integer" required>
  The number of trials that failed.
</ResponseField>

<ResponseField name="cancelled" type="integer" required>
  The number of trials that were cancelled.
</ResponseField>

<ResponseField name="infeasible" type="integer" required>
  The number of trials that reached `completed` but violated the run's feasibility constraints.
  Not eligible to  win. This bucket overlaps `completed` — such a trial is counted in both. No
  other bucket overlaps.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

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

  import requests

  base_url = os.environ["ATAI_API_URL"]
  api_key = os.environ["ATAI_API_KEY"]
  headers = {"Authorization": f"Bearer {api_key}"}

  optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"

  while True:
      response = requests.get(f"{base_url}/agents/optimizations/{optimization_id}", headers=headers)
      run = response.json()
      progress = run["progress"]
      done = progress["completed"] + progress["failed"] + progress["cancelled"]
      print(f"{run['status']}: {done}/{run['budget']['max_trials']} trials, {progress['infeasible']} infeasible")

      if run["status"] in ("completed", "failed", "cancelled"):
          break
      time.sleep(15)

  if run["best_trial_id"]:
      print(f"Winner: {run['best_trial_id']}")
  ```

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

  const body = await response.json();

  if (response.ok) {
    const { completed, failed, cancelled, infeasible } = body.progress;
    const done = completed + failed + cancelled;
    console.log(`${body.status}: ${done}/${body.budget.max_trials} trials, ${infeasible} infeasible`);
    if (body.best_trial_id) {
      console.log(`Winner: ${body.best_trial_id}`);
    }
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Completed theme={"system"}
  {
    "id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
    "name": "Window size sweep",
    "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
    "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
    "objective": "macro_f1",
    "search_space": {
      "parameters": {
        "window_size": {
          "kind": "value",
          "spec": {"type": "categorical", "values": [512, 1024, 2048]}
        },
        "n_neighbors": {
          "kind": "fitting",
          "spec": {"type": "int_range", "min": 3, "max": 25}
        }
      }
    },
    "budget": {"max_trials": 24},
    "constraints": {
      "min_metric": [
        {"metric": "recall", "class": "fault_bearing", "min_value": 0.8}
      ]
    },
    "training_examples": [
      {
        "name": "file_abc123",
        "ordinal": 1,
        "inputs": [
          {"type": "file", "id": "file_abc123", "format": "csv", "crc32c": "AAAAAA=="}
        ]
      }
    ],
    "calibration_examples": null,
    "validation_examples": [
      {
        "name": "file_def456",
        "ordinal": 1,
        "inputs": [
          {"type": "file", "id": "file_def456", "format": "csv", "crc32c": "AAAAAA=="}
        ]
      }
    ],
    "status": "completed",
    "progress": {
      "pending": 0,
      "running": 0,
      "completed": 22,
      "failed": 2,
      "cancelled": 0,
      "infeasible": 5
    },
    "best_trial_id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
    "created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
    "created_at": "2026-09-18T12:02:44Z",
    "started_at": "2026-09-18T12:02:51Z",
    "completed_at": "2026-09-18T13:47:05Z",
    "error": null
  }
  ```

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


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