> ## 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 Inference API's Direct Query endpoint (POST /api/inference/query) with the newton-c-2.6 or newton-fusion-1.0 model (text, image, and video reasoning) or the omega-embedding 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.

# Migrating Omega from the Direct Query API

> Move Omega embedding calls from `OmegaEncoder::omega_embeddings_1_4` on `/lens/query` to `omega-embedding` (Newton Omega 1.5) on the Inference API, set the window length with a session, and rebuild what depends on the old embeddings.

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

On the [Direct Query API](https://docs.archetypeai.app/api-reference/query.md) (`POST /lens/query`), you embedded sensor
windows with Newton Omega 1.4, `OmegaEncoder::omega_embeddings_1_4`. On the [Inference
API](https://docs.archetypeai.app/api-reference/inference/about), the encoder is Newton Omega 1.5, named `omega-embedding`
(also `newton-omega-1.5`). For text, image, and video models, see [Migrating from the Direct Query
API](https://docs.archetypeai.app/api-reference/inference/migrate-from-direct-query.md).

The Direct Query API is still available and still serves Omega 1.4. Each API serves one version:
Omega 1.4 only on the Direct Query API, Omega 1.5 only on the Inference API. Moving means moving to
Omega 1.5 and rebuilding what you built on Omega 1.4; see [Current
Limitations](#current-limitations) for when to wait.

The request body is the one you know, a `data.numeric_array` event, but three things change:

* **The embeddings are new.** Omega 1.5 vectors aren't comparable with Omega 1.4 vectors, so every
  library, threshold, and model built on Omega 1.4 embeddings has to be rebuilt.
* **The window length is set by a session.** Without one, every window is 1024 timesteps. To
  embed shorter windows, open a session with the `window_size` you want.
* **All channels go in one request.** The answer is one row per window, with each channel's
  768 values in order.

## What Changed

| | Direct Query API | Inference API |
| - | - | - |
| Endpoint | `POST /lens/query` | `POST /inference/query`, or `POST /inference/sessions/{id}/query` for a session |
| Model | `OmegaEncoder::omega_embeddings_1_4` (Newton Omega 1.4) | `omega-embedding` (Newton Omega 1.5). The old identifier returns `404` |
| Window length | 16 to 1024 timesteps per request. Shorter input was padded and masked; longer input kept its last 1024 timesteps | 1024 without a session. Any length from 16 to 1024 in a session, set once with `window_size` |
| Input not exactly one window | Accepted, with a warning | Shorter input returns `success: false` with no message. Longer input is cut into back-to-back windows, one row each, and the rest is dropped |
| Channels | One request per channel was the safe pattern | All channels in one request, up to 2 MiB per body |
| Answer | One 768-value vector per channel | One row per window: `channels × 768` values, channel by channel |
| `normalize_input` | Applied per window when `true` | Accepted and ignored. The model normalizes every window itself |
| Embeddings | Omega 1.4 | Omega 1.5, not comparable with Omega 1.4 |

## Current Limitations

> [!WARNING]
>
> As of November 15, 2026, on the production platform. This section will be updated as these
> limitations change.

Omega 1.5 on the Inference API was faster than Omega 1.4 on the Direct Query API on each demo we
moved. On held-out data, drilling-state accuracy rose from 89% to 95%, water-treatment attack
detection stayed about the same with no false alarms, and the wind-turbine demo lost its false
alarm but flagged the fault later (see [What Changed in Practice](#what-changed-in-practice)).
These are the cases where the Direct Query API still fits better:

| You need | On the Inference API today | Stay on the Direct Query API if |
| - | - | - |
| **Omega 1.4 embeddings** | Not served. Only Omega 1.5, whose vectors aren't comparable with Omega 1.4's | You can't rebuild a library, threshold, or model built on Omega 1.4 yet |
| **A different window length per request** | The length is fixed per session. Each length needs its own session, and without one every window is 1024 timesteps | You mix window lengths and can't group requests by length |
| **Many window lengths or clients at once** | An organization can keep 16 sessions open per model; the 17th returns `429` | You need more than 16 open sessions at a time |
| **Input that isn't exactly one window** | Shorter input returns `success: false` with no message; longer input is cut into windows and the remainder dropped. The Direct Query API padded or kept the last 1024 timesteps, with a warning | You can't control window length before you send |
| **Stateless calls only** | Window lengths other than 1024 need a session, which can end at any time (for example, during a release) and return `409 session_not_running`. Your client must reopen it and resend | You can't add session handling to your client |
| **Very wide windows** | A body over 2 MiB returns `413`: about 95 channels of 1024 timesteps | |
| **`normalize_input: true`** | Accepted and ignored: every window is standardized by the model, with its original scale passed alongside. The old per-window z-normalization that discarded amplitude can't be reproduced | You relied on amplitude being discarded |

## Moving a Script

**1. Change the URL and the model**

Send the same `data.numeric_array` body to `/inference/query` with `"model":
        "omega-embedding"`. Without a session, each channel needs exactly 1024 timesteps per window.

**2. Open a session if your windows aren't 1024 timesteps**

Create a session with `window_size` and `step_size` set to your window length, send each
window to the session, and cancel the session when you're done. See [Setting the Window
Length](#setting-the-window-length).

**3. Send all channels in one request**

Put every channel of a window in `contents`, channel first, and split the channels across
requests only if the body would pass 2 MiB. Channels are encoded independently, so splitting
them gives the same vectors.

**4. Read the new answer**

Each window is one row at `response.response`. Slice it into 768 values per channel, in the
order you sent the channels. Check `response.success`: it's `false` when the input is shorter
than the window.

**5. Rebuild everything built on Omega 1.4 embeddings**

Re-embed your reference libraries, recompute thresholds, and retrain any model that reads the
vectors. Then compare a few window lengths again; the best one can change. See [What Changed
in Practice](#what-changed-in-practice).

## The Request

On the Direct Query API, a typical client sent one request per channel:

```json Before theme={"system"}
{
  "model": "OmegaEncoder::omega_embeddings_1_4",
  "query": "",
  "normalize_input": false,
  "events": [
    {"type": "data.numeric_array", "event_data": {"contents": [[0.12, 0.08, -0.03, ...]]}}
  ]
}
```

On the Inference API, send every channel of the window together:

```json After theme={"system"}
{
  "model": "omega-embedding",
  "query": "",
  "events": [
    {
      "type": "data.numeric_array",
      "event_data": {
        "contents": [
          [0.12, 0.08, -0.03, ...],
          [0.44, 0.41, 0.39, ...],
          [-0.27, -0.25, -0.31, ...],
          [0.05, 0.02, 0.07, ...]
        ]
      }
    }
  ]
}
```

`contents` is channel first: one list per sensor, each with the same number of timesteps. Leave
timestamps out; a timestamp column sent as a channel is embedded like any other signal.

The answer keeps the Direct Query shape, with one row per window at `response.response`:

```json theme={"system"}
{
  "query_id": "...",
  "status": "...",
  "response": {
    "success": true,
    "response": [[0.0312, -0.1187, ...]]
  }
}
```

With four channels, the row has 3072 values: channel 1 is `row[0:768]`, channel 2 is
`row[768:1536]`, and so on.

## Setting the Window Length

Without a session, `omega-embedding` cuts its input into 1024-timestep windows. To embed a
different length, open a session on the model with `window_size` and `step_size`:

| Request | Purpose |
| - | - |
| [`POST /inference/sessions`](https://docs.archetypeai.app/api-reference/inference/sessions/create-session) | Open a session. The body names the model and the window: `{"model": "omega-embedding", "values": {"window_size": 256, "step_size": 256}}`. Returns `201` with the session's `id` |
| [`POST /inference/sessions/{id}/query`](https://docs.archetypeai.app/api-reference/inference/sessions/query-session) | Embed with the session's window. Same body as `/inference/query`, including `model` |
| [`POST /inference/sessions/{id}/cancel`](https://docs.archetypeai.app/api-reference/inference/sessions/cancel-session) | Close the session, with an empty body |

`window_size` can be from 16 to 1024. Windows shorter than 1024 are padded and masked inside the
model, so the padding isn't read as signal. Set `step_size` to the same value, so that one slice
of `window_size` timesteps is exactly one window.

This script embeds the first three 256-timestep windows of a CSV, one row per timestep with a
column per sensor:

```python embed_windows.py theme={"system"}
import csv
import os
import sys

import requests

MODEL = "omega-embedding"
WINDOW = 256  # timesteps per window, from 16 to 1024

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

with open(sys.argv[1], newline="") as f:
    rows = list(csv.DictReader(f))
names = [name for name in rows[0] if name != "timestamp"]
channels = [[float(row[name]) for row in rows] for name in names]

session = requests.post(
    f"{base_url}/inference/sessions",
    headers=headers,
    json={"model": MODEL, "values": {"window_size": WINDOW, "step_size": WINDOW}},
    timeout=60,
)
session.raise_for_status()
session_url = f"{base_url}/inference/sessions/{session.json()['id']}"

try:
    for start in range(0, 3 * WINDOW, WINDOW):
        window = [channel[start:start + WINDOW] for channel in channels]
        response = requests.post(
            f"{session_url}/query",
            headers=headers,
            json={
                "model": MODEL,
                "query": "",
                "events": [{"type": "data.numeric_array", "event_data": {"contents": window}}],
            },
            timeout=60,
        )
        response.raise_for_status()
        answer = response.json()["response"]
        if not answer["success"]:
            raise RuntimeError(f"no embedding for the window at {start}: is it {WINDOW} timesteps?")
        row = answer["response"][0]
        vectors = {name: row[i * 768:(i + 1) * 768] for i, name in enumerate(names)}
        print(start, {name: [round(v, 3) for v in vector[:3]] for name, vector in vectors.items()})
finally:
    requests.post(f"{session_url}/cancel", headers=headers, timeout=60)
```

Run it on the bearing sample from the [quickstart](https://docs.archetypeai.app/introduction/getting-started.md):

```bash theme={"system"}
curl -sLO "https://raw.githubusercontent.com/archetypeai/agent-skills/main/skills/atai-newton-omega-model/references/sample_data/bearing_healthy.csv"
python embed_windows.py bearing_healthy.csv
```

It prints the first three values of each sensor's vector for each window.

### Session Lifecycle

* **Close sessions you're done with.** An organization can keep up to 16 sessions open on a
  model. Opening another returns `429` with the code `session_limit_reached`. A session that
  isn't cancelled stays open until it ends on its own.
* **Reopen a session that has ended.** A session ends when it expires, when it's cancelled, or
  when the copy of the model serving it is replaced, for example during a release. Its queries
  then return `409` with the code `session_not_running`. Open a new session and resend the
  window.
* **Use one window length per session.** To compare lengths, open one session per length.

## Normalization

`normalize_input` is accepted and has no effect: the answer is the same with `true` or `false`.
Omega 1.5 standardizes each window itself and passes the window's original scale to the encoder
alongside it, so a quiet window and a loud window with the same shape still embed differently.

Keep the scaler you used with Omega 1.4: fit one mean and standard deviation per channel on your
reference data and apply it to every window before you send it. On the single-channel quickstart,
the shared scaler still added 7 to 10 points of accuracy at windows of 64 and 256 timesteps.

## What Changed in Practice

These notes come from moving our Omega agent skills, the quickstart, and a wind-turbine
monitoring demo to the Inference API.

### Rebuild, Then Re-Measure

For the same four-channel window, the Omega 1.4 and Omega 1.5 vectors had a cosine similarity
between -0.03 and 0.02: unrelated. A library built with one version gives wrong answers on vectors from the other,
without any error. Rebuild first, then measure again, because results move:

| Window | Omega 1.4 accuracy | Omega 1.5 accuracy |
| - | - | - |
| 16 | 0.671 | 0.734 |
| 64 | 0.916 | 0.954 |
| 256 | 0.973 | 0.970 |
| 1024 | 0.944 | 0.998 |

That is the bearing sample from the [Omega agent
skill](https://github.com/archetypeai/agent-skills/tree/main/skills/atai-newton-omega-model): a
3-nearest-neighbour classifier over four channels, scored on 1000 held-out windows at each
length, with the same scaler for both versions. With Omega
1.4, 256 timesteps did best; with Omega 1.5, 1024 did. With one channel instead of four, 64 did
best (see the [quickstart](https://docs.archetypeai.app/introduction/getting-started.md)). Compare a few window lengths on your
own data rather than keeping the one you had.

On the wind-turbine demo, Omega 1.5 raised no alert on the healthy turbine, where Omega 1.4 had
raised one, but flagged the faulty turbine about 1.8 days later. Replay a known event before you
rely on new alerts.

### Speed

One four-channel window of 1024 timesteps took about 2 seconds as four parallel Direct Query
calls and about half a second as one Inference API call. A 128-timestep window in a session took
about 0.4 seconds.

### Errors

Errors use the standard envelope; see the [Inference API errors](https://docs.archetypeai.app/api-reference/inference/about#errors).
The ones you are most likely to meet while migrating:

| Status | Message or code | What to do |
| - | - | - |
| `200` with `success: false` | | The input is shorter than the window. Send exactly `window_size` timesteps per channel |
| `400` | `missing or empty model field` | Include `model` in every query, including queries to a session |
| `404` | `model 'OmegaEncoder::omega_embeddings_1_4' is not available` | Use `omega-embedding` |
| `409` | `session_not_running` | The session has ended. Open a new one and resend the window |
| `413` | | The body is over 2 MiB, about 95 channels of 1024 timesteps. Split the channels across requests |
| `422` | `invalid_session_values` | Use `window_size` and `step_size` in the session's `values` |
| `429` | `session_limit_reached` | Your organization has 16 sessions open on the model. Cancel one you're done with |


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