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

> Page through one optimization run's trials, optionally filtered by status

<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 a cursor-paginated list of one run's trials. Trials are listed newest first — highest
`trial_number` first — regardless of which direction you're paging through them.

A trial records the point it sampled from the parent's search space, what that point scored, and
whether it satisfied the run's feasibility constraints. A trial's state moves independently from
the parent: a failed trial does not fail the run.

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 from one
another.

## Request

<ParamField path="optimization_id" type="string" required>
  Parent optimization `opt_` id.
</ParamField>

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

<ParamField query="after" type="string">
  Forward cursor: return trials with a lower `trial_number` than this one. Pass the `next_cursor` of the previous page to fetch the next page. Mutually exclusive with `before`.
</ParamField>

<ParamField query="before" type="string">
  Backward cursor: return trials with a higher `trial_number` than this one. Pass the `prev_cursor` of the current page to walk back. Mutually exclusive with `after`.
</ParamField>

<ParamField query="status" type="string">
  Filter to a single lifecycle status. Omit for all statuses. One of `pending`, `running`, `completed`, `failed`, `cancelled`.
</ParamField>

## Response

<ResponseField name="data" type="array" required>
  The page, newest trial first (highest `trial_number`).
</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 to continue in the direction of travel: pass as `after` on a forward page, as `before` when the request used `before`. `null` when `has_more` is false.
</ResponseField>

<ResponseField name="prev_cursor" type="string">
  Cursor to step back the way the page was reached. `null` when the request carried no cursor.
</ResponseField>

### Trial object

Fields beyond the always-present ones fill in as the trial advances: `started_at` when it
dispatches, `metrics_report` / `objective_value` / `feasible` / `completed_at` on success,
`error` on failure.

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

<ResponseField name="optimization_id" type="string" required>
  The parent run's `opt_` id.
</ResponseField>

<ResponseField name="trial_number" type="integer" required>
  1-based ordinal within the parent run. Dense and deterministic.
</ResponseField>

<ResponseField name="trial_values" type="object" required>
  The sampled point in the parent's search space, as `{parameter_name: value}`. Opaque shape —
  the value's type varies per parameter and is defined by the parent's `search_space`.
</ResponseField>

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

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

<ResponseField name="objective_value" type="number">
  Convenience projection of `metrics_report`'s objective value. `null` until the trial has
  scored.
</ResponseField>

<ResponseField name="feasible" type="boolean">
  Feasibility against the parent's `constraints`. `null` while pending; only `true` trials
  qualify for the parent's `best_trial_id`.

  <Note>
    Only trials for which `feasible` is `true` qualify to be selected as the
    `best_trial_id`. However, you *can* promote infeasible trials. Whether or not that's a good
    idea is your decision.
  </Note>
</ResponseField>

<ResponseField name="metrics_report" type="object">
  The trial's scored metrics report, in the same shape an eval returns. `null` until the trial
  has scored.
</ResponseField>

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

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

<ResponseField name="error" type="string">
  Failure details if the trial failed; otherwise `null`.
</ResponseField>

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

  ```bash cURL - Completed Only theme={"system"}
  curl "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?status=completed" \
    -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"]
  headers = {"Authorization": f"Bearer {api_key}"}

  optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"

  cursor = None
  while True:
      params = {"limit": 100, "status": "completed"}
      if cursor:
          params["after"] = cursor

      response = requests.get(
          f"{base_url}/agents/optimizations/{optimization_id}/trials",
          headers=headers,
          params=params,
      )
      page = response.json()

      for trial in page["data"]:
          mark = "" if trial["feasible"] else "  (infeasible)"
          print(f"#{trial['trial_number']:>3} {trial['objective_value']} {trial['trial_values']}{mark}")

      if not page["has_more"]:
          break
      cursor = page["next_cursor"]
  ```

  ```javascript JavaScript theme={"system"}
  const params = new URLSearchParams({ limit: '20', status: 'completed' });

  const response = await fetch(
    `${process.env.ATAI_API_URL}/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
      }
    }
  );

  const page = await response.json();

  page.data.forEach(trial => {
    const mark = trial.feasible ? '' : '  (infeasible)';
    console.log(`#${trial.trial_number} ${trial.objective_value} ${JSON.stringify(trial.trial_values)}${mark}`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "data": [
      {
        "id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
        "optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
        "trial_number": 24,
        "trial_values": {"window_size": 1024, "n_neighbors": 11},
        "status": "completed",
        "objective_value": 0.89,
        "feasible": true,
        "metrics_report": {
          "schema_version": "v1",
          "primary": {"target": "state", "name": "macro_f1", "value": 0.89},
          "targets": {
            "state": {
              "type": "category",
              "aggregate": {"macro_f1": 0.89, "accuracy": 0.93},
              "class_names": ["running", "idle", "fault_bearing"],
              "per_class": {
                "precision": [0.94, 0.9, 0.79],
                "recall": [0.97, 0.87, 0.82],
                "f1": [0.95, 0.88, 0.8],
                "support": [4120, 1880, 260]
              },
              "confusion_matrix": [
                [3996, 106, 18],
                [199, 1636, 45],
                [31, 16, 213]
              ]
            }
          }
        },
        "created_at": "2026-09-18T13:38:12Z",
        "started_at": "2026-09-18T13:38:20Z",
        "completed_at": "2026-09-18T13:47:01Z",
        "error": null
      },
      {
        "id": "otr_01jcb2t4k9r2wq6nv8h3mdzx5p",
        "optimization_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
        "trial_number": 23,
        "trial_values": {"window_size": 512, "n_neighbors": 4},
        "status": "completed",
        "objective_value": 0.84,
        "feasible": false,
        "metrics_report": null,
        "created_at": "2026-09-18T13:29:44Z",
        "started_at": "2026-09-18T13:29:51Z",
        "completed_at": "2026-09-18T13:37:58Z",
        "error": null
      }
    ],
    "has_more": true,
    "next_cursor": "<cursor>",
    "prev_cursor": null
  }
  ```

  ```json 400 - Invalid query parameter theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Invalid query parameter.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

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