Skip to content
AvraAvra
Esc
↑↓navigate↵open⌘Jpreview
On this page

Live predictions

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.

Before you start

Get an API key for the workspace from Settings → Workspace → API keys in the dashboard, and send it as a bearer token on every request. Keep it in an environment variable, never in code:

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.

curl https://api.avra.ai/v1/api/models \
  -H "Authorization: Bearer $AVRA_API_KEY"
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"])
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:

[
  {
    "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.

MODEL_ID="<model_id>"

curl "https://api.avra.ai/v1/api/models/$MODEL_ID/versions/production" \
  -H "Authorization: Bearer $AVRA_API_KEY"
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")
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:

{
  "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, 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:

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"}'
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"])
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.

{
  "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]
  }
}
{
  "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.

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.

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.

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.

Handle errors

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

{
  "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.

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.

# 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"}'
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"])
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. 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.

Where to go next

Was this page helpful?