Return candidate probabilities

When Struct chooses from a set of candidates, you can request the probability of each one alongside its selected answer. Use these values to inspect close decisions or compare preferences across representative inputs.

Request probabilities

Set "probabilities": true in the choice field's x-runtime object. This is a Struct extension to JSON Schema; it requests extra response metadata without changing the output's shape.

probabilities.schema.json

Download JSON Schema

{
  "type": "object",
  "properties": {
    "choice": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C"
      ],
      "description": "Choose the response that correctly answers input.question. Return its key from input.responses.",
      "x-runtime": {
        "probabilities": true
      }
    }
  },
  "required": [
    "choice"
  ],
  "additionalProperties": false
}

Save the schema as probabilities.schema.json. The example below supplies three possible answers to a question and reads the response's probabilities:

Before you run this example

Call https://api.blatent.ai from your server. Set your API key in the same terminal where you run the example:

export BLATENT_API_KEY='YOUR_SERVICE_KEY'

Python requires Python 3.10+ and HTTPX:

python -m pip install "httpx>=0.28,<1"

TypeScript requires Node.js 24+ and uses its built-in fetch. The cURL examples require curl and jq.

Save the displayed files and the selected client in one directory. Run the client there with python example.py, node example.ts or bash example.sh. Downloads use the example's name in place of example.

Download Python

Python

import json
import os
from pathlib import Path
import httpx

request = {
    "input": {
        "question": "A recipe needs 250 g of flour per loaf. How much flour is needed for 3 loaves?",
        "responses": {
            "A": "750 g, because 3 × 250 g = 750 g.",
            "B": "500 g, because 250 g + 250 g = 500 g.",
            "C": "0.75 kg, because 3 × 0.25 kg = 0.75 kg.",
        },
    },
    "schema": json.loads(Path("probabilities.schema.json").read_text(encoding="utf-8")),
}
with httpx.Client(
    base_url="https://api.blatent.ai",
    headers={"Authorization": f"Bearer {os.environ['BLATENT_API_KEY']}"},
    timeout=195,
) as client:
    response = client.post("/v1/resolve", json=request)
    response.raise_for_status()
    print(json.dumps(response.json()["probabilities"]))

TypeScript

import { readFileSync } from "node:fs";

const request = {
    "input": {
        "question": "A recipe needs 250 g of flour per loaf. How much flour is needed for 3 loaves?",
        "responses": {
            "A": "750 g, because 3 × 250 g = 750 g.",
            "B": "500 g, because 250 g + 250 g = 500 g.",
            "C": "0.75 kg, because 3 × 0.25 kg = 0.75 kg.",
        },
    },
    "schema": JSON.parse(readFileSync("probabilities.schema.json", "utf8")),
};
const response = await fetch(
  "https://api.blatent.ai" + "/v1/resolve",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BLATENT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(request),
    signal: AbortSignal.timeout(195_000),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(JSON.stringify((await response.json()).probabilities));

cURL

set -eu

body=$(jq -n --argjson body '{"input":{"question":"A recipe needs 250 g of flour per loaf. How much flour is needed for 3 loaves?","responses":{"A":"750 g, because 3 × 250 g = 750 g.","B":"500 g, because 250 g + 250 g = 500 g.","C":"0.75 kg, because 3 × 0.25 kg = 0.75 kg."}}}' \
  --slurpfile f0 'probabilities.schema.json' \
  '$body | setpath(["schema"]; $f0[0])')
curl --fail-with-body --silent --show-error \
  "https://api.blatent.ai/v1/resolve" \
  -H "Authorization: Bearer $BLATENT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary "$body"

Read the response

The selected answer is still in output, for example {"choice":"A"}. The separate probabilities object is keyed by the output field's JSON Pointer: /choice in this example.

Observed for this request on 27 October 2026:

value	probability	log_probability
A	0.9522	−0.0490
B	0.0004	−7.7365
C	0.0474	−3.0490

Values are rounded here. Results can differ between runs and releases.

Each candidate has three values:

Field	Meaning
value	A candidate from the field's enum.
probability	Its probability within the allowed candidates. The values sum to one.
log_probability	The natural logarithm of that probability.

Omit the annotation or set "probabilities": false when you only need the answer. Collecting probabilities can add work because Struct also evaluates alternatives to the selected answer.

Interpret the numbers

These are relative candidate preferences, not calibrated confidence that an answer is correct. In this example, both A and C give the correct quantity in different units; their probabilities need not be equal.

Probability collection preserves the normal token-by-token choice. For candidates spanning multiple tokens, the selected answer need not have the highest complete-candidate probability.

If you use a threshold to send close decisions for human review, evaluate it on representative inputs first.