> The full index of these docs is at [llms.txt](https://u22a8.ai/llms.txt).

# Horizons

A horizon is the timestamp that names a fitted version of your model, and pinning one holds its verdicts still.

*Applies to a8-1. Last reviewed 2026-10-22.*

A **horizon** identifies the supervision a model was fitted over: a timestamp that reads “this model reflects everything you taught up to here”. Every fit of what you [teach](https://u22a8.ai/docs/a8-teaching.md) mints one. The alias `a8` answers from your latest ready horizon, and a request that names a horizon holds the model still.

## 1 Reading a horizon

A horizon is a compact UTC timestamp. `20260715t140322z` is 2026-07-15, 14:03:22 UTC: the moment of the newest change to what the model learned from. It tells you exactly which of your teaches a model holds.

Teaching and retracting both change what the model learned from, so either one moves the horizon. The earlier horizon stays as it was and stays pinnable, so pinning it is a second way to undo a retraction.

Horizons sort as strings, oldest first. A horizon belongs to the version that fitted it, and a request names it in the `model` field after an `@`:

```jsonc
// annotated: the model field in a request
// your organization's model, moving as you teach
"model": "a8"

// one horizon of it, held still
"model": "a8-1-1@20260715t140322z"
```

## 2 Listing your horizons

`GET /models` lists the models your key can call: the alias `a8`, every horizon your organization has fitted, newest first, then the reference model of the newest version. The reference model of an earlier version stays pinnable by its identifier.

**curl**

```bash
curl https://api.u22a8.ai/eval/v1/models \
  -H "Authorization: Bearer $U22A8_API_KEY"
```

**Python**

```python
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.u22a8.ai/eval/v1",
    api_key=os.environ["U22A8_API_KEY"],
)

for model in client.models.list():
    extra = model.model_extra or {}
    print(model.id, extra.get("status"), extra.get("active"))
```

**TypeScript**

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.u22a8.ai/eval/v1",
  apiKey: process.env.U22A8_API_KEY,
});

for await (const model of client.models.list()) {
  const { status, active } = model as typeof model & {
    status: string;
    active: boolean;
  };
  console.log(model.id, status, active);
}
```

The list while a fit is pending:

```jsonc
// annotated, trimmed: each entry also carries created, owned_by,
// lifecycle and shutdown_date
{
  "object": "list",
  "data": [
    {
      "id": "a8", // the alias, answering from the active horizon
      "object": "model"
    },
    {
      "id": "a8-1-1@20260716t091140z",
      "object": "model",
      "status": "provisional", // 14 teaches recorded, fit to follow
      "active": false
    },
    {
      "id": "a8-1-1@20260715t140322z",
      "object": "model",
      "status": "ready", // what a8 answers from
      "active": true
    },
    {
      "id": "a8-1-1@20260711t082915z",
      "object": "model",
      "status": "ready", // last week's model, still pinnable
      "active": false
    },
    {
      "id": "a8-1-1@reference",
      "object": "model",
      "status": "ready", // the reference model alone
      "active": false
    }
  ]
}
```

Two fields tell you when a model is in service, and two more when it retires:

| Field           | Value         | Meaning                                                                                                              |
| --------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `status`        | `ready`       | Fitted and stored, ready to pin                                                                                      |
| `status`        | `provisional` | The horizon the next fit mints from what you taught so far. See [the provisional horizon](#the-provisional-horizon). |
| `active`        | `true`        | The horizon the alias `a8` answers from                                                                              |
| `active`        | `false`       | Pinnable by its identifier                                                                                           |
| `lifecycle`     | `preview`     | The version’s lifecycle status. See [Deprecations](https://u22a8.ai/docs/deprecations.md).                           |
| `shutdown_date` | `null`        | A date once the version is deprecated. See [Deprecations](https://u22a8.ai/docs/deprecations.md).                    |

*Table 1.* The fields `GET /models` adds to each entry; a standard client reads the list as it reads any models list.

## 3 Pinning

A pin holds a verdict still. A pinned horizon answers from the exact reference model it was fitted over, so later teaching and later releases move the alias `a8` and leave the pin where it was.

| You ask for               | You get                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `a8`                      | Your latest ready horizon, which moves when you teach and when we publish a new reference model |
| `a8-1-1@20260715t140322z` | Your data at that moment, held; `a8@20260715t140322z` resolves to the same model                |

*Table 2.* Pinned and live identifiers; use each exactly as a response or the models list gave it.

A pin holds what the model learned, and the software that serves it stays current. A correction we ship reaches pinned callers too. The [system fingerprint](https://u22a8.ai/docs/a8-reproducibility.md) tells you when that happened. See [Model identifiers](https://u22a8.ai/docs/a8-model-identifiers.md#holding-still).

### 3.1 Every response names its horizon

Every response’s `model` field carries the exact identifier that answered, including when the request asked for `a8`. Send that value back as `model`, and the same request returns the same verdict:

```jsonc
// annotated
// the request asked for
"model": "a8"

// the response answered as; keep this beside the verdict
"model": "a8-1-1@20260715t140322z"
```

Keep the response’s `model` beside anything you need to re-derive. Before your first fit, the reference model answers, and the field names it.

### 3.2 When to pin up front

- **A regression suite or a published benchmark.** Pin, so a re-run measures your system as it stood.
- **A scored result you stand behind later.** Pin, and record the identifier beside the result.
- **Production judging that keeps improving.** Stay on `a8`, and watch the [system fingerprint](https://u22a8.ai/docs/a8-reproducibility.md) to learn when the model moved.

## 4 The reference model

Beside your organization’s model, you always have the **reference model**: A8 as we publish it. A new organization starts on it, and it stays available however much you teach.

```jsonc
// annotated
// your organization's model: everything you taught
"model": "a8"

// the reference model: A8 as we publish it
"model": "a8-1-1@reference"
```

`reference` sits at zero on the horizon axis. A horizon names the supervision a model was fitted over, and this one names ours alone, so it is a word, dated by the version it belongs to.

The reference model serves three uses:

- **Measuring what your teaching changed.** Run the same test against both models. The difference is your teaching, isolated.
- **A fallback.** Where teaching has taken your model off course, the reference model answers as published.
- **A second opinion** on a case where your own conventions decide the verdict.

Each reference model keeps its name. An improved reference model is a new minor version: `a8-1-2@reference` names it, and `a8-1-1@reference` keeps naming the earlier one. Everything you pinned on the earlier minor answers as it did.

Your organization’s model moves forward on its own. We refit your teaching on the new reference model once it is published, and the alias `a8` moves to the new minor when that fit completes. Until then it answers from the model you have, with every teach in it. The new horizon appears in `GET /models`, and the system fingerprint changes with it.

## 5 The provisional horizon

After you teach, the models list shows the identifier the next fit mints, with `status: "provisional"`. It confirms the teach was recorded, and it gives you the identifier to ask for once the fit completes.

A request for a provisional identifier returns `503` with `Retry-After: 30` until the fit completes. The OpenAI and Anthropic SDKs retry a `503` on their own, so a pinned request waits for its own model.

> **Pin ready horizons.** Teaching again before the fit moves the provisional horizon forward, and a request for the earlier provisional identifier returns `404`. A `ready` horizon stays fixed, so pin ready horizons.

## 6 Errors

| Status | `code`              | Condition                                                                                                   |
| ------ | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `503`  | `horizon_fitting`   | The identifier is your provisional horizon, whose fit is in progress; retry                                 |
| `404`  | `horizon_not_found` | The identifier sits outside your stored horizons: a typo, or a provisional horizon a later teach moved past |
| `400`  | `unknown_model`     | The `model` is outside A8’s identifiers, or names a version we have yet to publish                          |

*Table 3.* The errors a horizon produces; every other status is on [Errors](https://u22a8.ai/docs/errors.md).

## 7 Related concepts

- [Model identifiers](https://u22a8.ai/docs/a8-model-identifiers.md): the parts of an identifier and what moves each
- [Teaching](https://u22a8.ai/docs/a8-teaching.md): what moves the horizon
- [Reproducibility](https://u22a8.ai/docs/a8-reproducibility.md): the response field that says something moved

## Next steps

- [Reproducibility](https://u22a8.ai/docs/a8-reproducibility.md): The system fingerprint tells you when anything behind a verdict moved, and the model identifier reproduces a verdict.
- [Model identifiers](https://u22a8.ai/docs/a8-model-identifiers.md): A model identifier names a family, a version, a minimum accuracy and a horizon, and each part moves for its own reason.
- [Teaching](https://u22a8.ai/docs/a8-teaching.md): How to teach and retract through MCP, when a teach lands in your organization’s model and what it changes.