---
title: Live predictions
description: Call a model for one record at a time through the API, addressed by model and by version or alias, with errors, retries, and tracing.
---

Live predictions answer one request at a time: your decision engine sends a record and gets its result back, from the model version you choose.

The workflow takes three calls. List the models available to your organization, read the schema of the version you'll call, then send each record's inputs to the prediction endpoint. The first two calls happen once, while you integrate. The third is the one your decision engine makes on every decision, with a correlation ID so the request can be traced later.

```mermaid
sequenceDiagram
  autonumber
  participant D as Decision engine
  participant A as Avra API
  participant M as Model version
  D->>A: POST to the production alias
  A->>A: Check key, resolve alias
  A->>M: Inputs
  M-->>A: Outputs
  alt Scored
    A-->>D: 200 with result
  else Invalid inputs
    A-->>D: 400 naming the problem
  end
  D->>D: Store result and correlation ID
```

## Before you start

Get an API key for the workspace from **Settings → Workspace → API keys** in the [dashboard](https://app.avra.ai), and send it as a bearer token on every request. Keep it in an environment variable, never in code:

```bash
export AVRA_API_KEY="<your key>"
```

To check which workspace and organization a key belongs to, call `GET /v1/api/workspace/keys/introspect`. It returns the key's `id` and `name`, and the `id` and `name` of its workspace and organization.

You also need to know which model to call. Every model available to your organization has a `model_id`. Each version has a `version_id`, returned as `model_version_id`, and can carry an alias, such as `production`.

## 1. Find the model

List the models available to your organization. The `type` field tells models apart: credit and embedding models, for example.

```bash cURL
curl https://api.avra.ai/v1/api/models \
  -H "Authorization: Bearer $AVRA_API_KEY"
```

```python Python
import os

import requests

API = "https://api.avra.ai"
headers = {"Authorization": f"Bearer {os.environ['AVRA_API_KEY']}"}

response = requests.get(f"{API}/v1/api/models", headers=headers, timeout=30)
response.raise_for_status()
for model in response.json():
    print(model["id"], model["type"], model["name"])
```

```ts TypeScript
const API = "https://api.avra.ai";
const headers = { Authorization: `Bearer ${process.env.AVRA_API_KEY}` };

const response = await fetch(`${API}/v1/api/models`, { headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
for (const model of await response.json()) {
  console.log(model.id, model.type, model.name);
}
```

The response is a list, one entry per model:

```json
[
  {
    "id": "8f14e45f-ceea-467f-a8f0-5c3f0c7a1b2d",
    "name": "Company credit risk",
    "description": "Probabilities of default for Brazilian companies",
    "type": "probability-of-default",
    "status": "available"
  }
]
```

`GET /v1/api/models/{model_id}/versions` lists a model's versions, under `versions`, next to the model itself under `model`. Each version has its `model_version_id`, its `version` number, `is_active`, the date it was trained as `trained_at`, its `status`, and its `alias` when it holds one. Only active versions serve predictions.

## 2. Read the version's schema

Read one version by its alias or its version ID. Its `schema` lists the `inputs` the model takes and the `outputs` it returns.

```bash cURL
MODEL_ID="<model_id>"

curl "https://api.avra.ai/v1/api/models/$MODEL_ID/versions/production" \
  -H "Authorization: Bearer $AVRA_API_KEY"
```

```python Python
import os

import requests

API = "https://api.avra.ai"
MODEL_ID = "<model_id>"
headers = {"Authorization": f"Bearer {os.environ['AVRA_API_KEY']}"}

response = requests.get(
    f"{API}/v1/api/models/{MODEL_ID}/versions/production", headers=headers, timeout=30
)
response.raise_for_status()
version = response.json()
print("version", version["version"], version["model_version_id"])
for field in version.get("schema", {}).get("inputs", []):
    print(field["name"], field["type"], "optional" if field["optional"] else "required")
```

```ts TypeScript
const API = "https://api.avra.ai";
const MODEL_ID = "<model_id>";
const headers = { Authorization: `Bearer ${process.env.AVRA_API_KEY}` };

const response = await fetch(`${API}/v1/api/models/${MODEL_ID}/versions/production`, { headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const version = await response.json();
console.log("version", version.version, version.model_version_id);
for (const field of version.schema?.inputs ?? []) {
  console.log(field.name, field.type, field.optional ? "optional" : "required");
}
```

For a GFM model that returns probabilities of default, the response looks like this, with the outputs shortened to two of the five horizons:

```json
{
  "model_id": "8f14e45f-ceea-467f-a8f0-5c3f0c7a1b2d",
  "model_version_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
  "version": 3,
  "is_active": true,
  "alias": "production",
  "trained_at": "2026-06-30",
  "status": "available",
  "schema": {
    "inputs": [
      { "name": "cnpj", "type": "string", "optional": false, "example": "12345678000199" }
    ],
    "outputs": [
      { "name": "pd_30d", "type": "float", "optional": false, "example": [0.004] },
      { "name": "pd_365d", "type": "float", "optional": false, "example": [0.051] }
    ]
  }
}
```

Each field in `inputs` and `outputs` has a `name`, a `type`, whether it's `optional`, and an `example`. Send every input that isn't optional, under the same name. When a version has metrics recorded, the response also includes them, under `metrics`.

The same details are on each model's page in the [dashboard](https://app.avra.ai), under **Models**, where **⋯ → Run a prediction** on a version runs one before you integrate.

## 3. Call the model

Send the inputs the version's schema declares, as a JSON object. This example calls whichever version holds the `production` alias of a GFM model, whose input is a company's CNPJ:

```bash cURL
MODEL_ID="<model_id>"

curl -X POST "https://api.avra.ai/v1/api/prediction/$MODEL_ID/production" \
  -H "Authorization: Bearer $AVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: $(uuidgen)" \
  -d '{"cnpj": "12345678000199"}'
```

```python Python
import os
import uuid

import requests

API = "https://api.avra.ai"
MODEL_ID = "<model_id>"

correlation_id = str(uuid.uuid4())
response = requests.post(
    f"{API}/v1/api/prediction/{MODEL_ID}/production",
    headers={
        "Authorization": f"Bearer {os.environ['AVRA_API_KEY']}",
        "X-Correlation-Id": correlation_id,
    },
    json={"cnpj": "12345678000199"},
    timeout=35,
)
response.raise_for_status()
prediction = response.json()
print(correlation_id, prediction["operation_id"], prediction["result"])
```

```ts TypeScript
const API = "https://api.avra.ai";
const MODEL_ID = "<model_id>";

const correlationId = crypto.randomUUID();
const response = await fetch(`${API}/v1/api/prediction/${MODEL_ID}/production`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVRA_API_KEY}`,
    "Content-Type": "application/json",
    "X-Correlation-Id": correlationId,
  },
  body: JSON.stringify({ cnpj: "12345678000199" }),
  signal: AbortSignal.timeout(35_000),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const prediction = await response.json();
console.log(correlationId, prediction.operation_id, prediction.result);
```

## Read the result

A successful prediction returns `200` with `status` set to `completed`. `result` holds the outputs the version's schema declares, under the names the schema gives them.

```json Probabilities of default
{
  "operation_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
  "status": "completed",
  "result": {
    "pd_30d": [0.004],
    "pd_60d": [0.006],
    "pd_90d": [0.011],
    "pd_180d": [0.024],
    "pd_365d": [0.051]
  }
}
```

```json Embedding
{
  "operation_id": "6fa459ea-ee8a-4ca4-894e-db77e160355e",
  "status": "completed",
  "result": {
    "embedding": [[0.0213, -0.0087, 0.0441, 0.0129]]
  }
}
```

The embedding is shortened here: `result["embedding"][0]` holds the full 1024 numbers. See the [embeddings technical guide](/gfm/embeddings/technical-implementation).

| Field | Type | Description |
|---|---|---|
| `operation_id` | string | A unique ID for this prediction |
| `status` | string | `completed` for a successful prediction |
| `result` | object | The outputs the version's schema declares |

## Trace every call

Send an `X-Correlation-Id` header with a UUID on each request, and store it with your decision. Avra logs it, links it to the request's audit events, and returns it in the response headers, so support can find the request later. If you don't send one, Avra generates it.

Every prediction also appears in the workspace's usage log, under **Observability → Usage**, with its status, the API key that made it, and the model. See [Audit and usage logs](/dashboard/audit-logs).

## Pin or follow

Follow an alias, such as `production`, to pick up promotions without changing code. Pin a `version_id` when you need determinism: backtests, audit replays, or staged rollouts. See [Model versioning](/core/model-versioning).

The response doesn't name the version that answered. If you follow an alias and must record the exact version behind each decision, pin it instead: read the alias's `model_version_id` once, then call that version ID. See [Pin a version or follow an alias](/core/model-versioning#pin-a-version-or-follow-an-alias).

## Handle errors

Branch on the status code. Most error bodies are JSON with a numeric `code` and a human-readable `message`:

```json
{
  "code": 404,
  "message": "model alias not found"
}
```

| Status | `message` | What it means | What to do |
|---|---|---|---|
| `400` | `invalid request body` | The body isn't a JSON object, or it's sent without `Content-Type: application/json` | Send the inputs as a JSON object, with that header |
| `400` | Names the problem, with details such as `missing_inputs` | Inputs are missing or don't match the schema | Send every required input, with the schema's types |
| `400` | `model version is not active` | The version, or the one behind the alias, doesn't serve predictions | Call an active version, or reassign the alias |
| `401` | `unauthorized` | The API key is missing or invalid | Check the key and the `Authorization` header |
| `403` | `forbidden` | Your organization has no access to the model | Check the `model_id`, or ask your Avra team |
| `403` | `workspace is not active` | The key's workspace is archived | Use a key from an active workspace |
| `404` | `model version not found` or `model alias not found` | The version or alias doesn't exist | Check the version ID and the alias name |
| `404` | `no results for the provided references` | The model has no result for the record you sent, such as a company it has no data for | Don't retry the same record |
| `429` | `Too many requests. Please retry later.` | Over the rate limit | Wait at least 10 seconds, then retry |
| `500` | `prediction timed out` | The model didn't answer within 30 seconds | Retry with backoff |
| `500` | `failed to perform prediction` | The prediction failed on Avra's side | Retry with backoff, then contact support with the correlation ID |

Two bodies differ from the rest. A missing or invalid key returns `{"error": "unauthorized", "message": "unauthorized"}`, and the rate limit returns `{"code": "429", "error": "rate_limited", "message": "Too many requests. Please retry later."}`. The full list of statuses is in the [API reference](/api-reference).

### Retry with backoff

Retry `429` and `5xx` responses, and network timeouts. Wait at least 10 seconds after a `429`, or the `Retry-After` value when there is one, and back off exponentially with a little random jitter, so your clients don't all retry at the same instant. Don't retry any other `4xx`: the request itself needs fixing.

```bash cURL
# curl retries timeouts and 408, 429, 500, 502, 503, and 504 responses, 10 seconds apart.
MODEL_ID="<model_id>"

curl --retry 4 --retry-delay 10 \
  -X POST "https://api.avra.ai/v1/api/prediction/$MODEL_ID/production" \
  -H "Authorization: Bearer $AVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: $(uuidgen)" \
  -d '{"cnpj": "12345678000199"}'
```

```python Python
import os
import random
import time
import uuid

import requests

API = "https://api.avra.ai"
MODEL_ID = "<model_id>"
RETRYABLE = {429, 500, 502, 503, 504}


def predict(inputs: dict, version: str = "production", attempts: int = 5) -> dict:
    url = f"{API}/v1/api/prediction/{MODEL_ID}/{version}"
    headers = {
        "Authorization": f"Bearer {os.environ['AVRA_API_KEY']}",
        "X-Correlation-Id": str(uuid.uuid4()),  # one ID for every attempt
    }
    for attempt in range(1, attempts + 1):
        response = None
        try:
            response = requests.post(url, headers=headers, json=inputs, timeout=35)
            if response.status_code not in RETRYABLE:
                response.raise_for_status()  # any other 4xx: fix the request instead
                return response.json()
        except (requests.ConnectionError, requests.Timeout):
            pass
        if attempt == attempts:
            break
        delay = min(2**attempt, 30) + random.random()  # exponential backoff with jitter
        if response is not None and response.status_code == 429:
            retry_after = response.headers.get("Retry-After", "")
            delay = max(delay, 10, int(retry_after) if retry_after.isdigit() else 0)
        time.sleep(delay)
    if response is not None:
        response.raise_for_status()
    raise RuntimeError(f"no response after {attempts} attempts")


print(predict({"cnpj": "12345678000199"})["result"])
```

```ts TypeScript
const API = "https://api.avra.ai";
const MODEL_ID = "<model_id>";
const RETRYABLE = new Set([429, 500, 502, 503, 504]);
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function predict(inputs: Record<string, unknown>, version = "production", attempts = 5) {
  const headers = {
    Authorization: `Bearer ${process.env.AVRA_API_KEY}`,
    "Content-Type": "application/json",
    "X-Correlation-Id": crypto.randomUUID(), // one ID for every attempt
  };
  let response: Response | undefined;
  for (let attempt = 1; attempt <= attempts; attempt++) {
    response = undefined;
    try {
      response = await fetch(`${API}/v1/api/prediction/${MODEL_ID}/${version}`, {
        method: "POST",
        headers,
        body: JSON.stringify(inputs),
        signal: AbortSignal.timeout(35_000),
      });
    } catch {
      // A network error or a timeout: retry.
    }
    if (response && !RETRYABLE.has(response.status)) {
      // Any other 4xx means the request needs fixing, not retrying.
      if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
      return response.json();
    }
    if (attempt === attempts) break;
    let delay = Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000;
    if (response?.status === 429) {
      const retryAfter = Number(response.headers.get("Retry-After")) || 0;
      delay = Math.max(delay, 10_000, retryAfter * 1000);
    }
    await sleep(delay);
  }
  throw new Error(response ? `${response.status} ${await response.text()}` : `no response after ${attempts} attempts`);
}

console.log((await predict({ cnpj: "12345678000199" })).result);
```

The samples keep one correlation ID for every attempt at the same decision, so you can give support a single ID. Their client timeout of 35 seconds leaves room for the 30 seconds Avra waits for a model.

## Limits

Predictions are limited to about 100 requests per 10 seconds per API key. The limit is enforced at Avra's network edge, so treat it as approximate. Over the limit, requests get `429 Too Many Requests` and the key is blocked for 10 seconds. Batch jobs don't count against it.

Each request scores one record. For more than a few thousand records at once, use [Batch inference](/core/batch-inference). If your production traffic needs a higher limit, contact your Avra account manager with your expected request volume and traffic pattern. Every limit in Core is in [Limits and quotas](/core/limits).

## Where to go next

**[Model versioning](/core/model-versioning)**

Pin a version, follow an alias, promote, and roll back.

**[Batch inference](/core/batch-inference)**

Score whole portfolios asynchronously.

**[Build with embeddings](/gfm/embeddings)**

Use the vectors Avra GFM returns.

**[API reference](/api-reference)**

Every endpoint, field, and status code.
