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.