Scoring

When a tracker runs, it produces a scored result — an evidence-based assessment you can act on.

Run Result

{
  "score": 72,                 // 0-100 integer, or null when the run reached no answer
  "insight": "...",            // What was found, and what it rests on
  "belief_status": "updated",  // updated | unchanged | abstained | degraded
  "coverage": 1.0,             // How much of what it set out to check it reached (may be null on unchanged)
  "confidence": 0.78,          // How much the published view itself is to be trusted (may be null on unchanged)
  "score_qualifiers": [],      // Caveats the number alone cannot carry
  "reason_codes": [],          // Why the run ended where it did (especially on abstain)
  "score_adjustment_factors": [
    {
      "id": 3,
      "factor": "Earnings momentum",
      "direction": "+",
      "effect_band": "decisive",
      "confidence_band": "likely",
      "changed": "new",
      "impact": 12,
      "probability": 0.7
    }
  ]
}

Older runs

Runs completed before the current scoring contract may only include score, insight, and factors with factor / impact / probability — without bands, changed, or belief_status. New runs return the full shape above.

---

Understanding Scores

Each tracker run produces a score (0–100) and an insight (what was found and what it rests on). The score is not written by the model. The agent identifies the factors that materially move the picture, states how much each one moves it and how sure it is of each, and the engine composes the number from those factors using a fixed table. There is no step at which a model can name a score directly.

Factors

A factor is one material driver of the score. Each one carries two separate judgements, and keeping them apart is the point:

Field	Question it answers
effect_band	How far does this move the score? decisive, contributing or minor
confidence_band	How sure are we this factor applies? confirmed, likely or tentative

confidence_band is confidence in the factor, never the odds of whatever your score is about. A tentative factor is one we are not certain applies at all; it says nothing about the probability of the outcome you are tracking.

Both are bands rather than free numbers, because a model asked for "how many points" produces a differently wrong number every run. Bands are stable between runs, which is what makes a change in one meaningful. impact and probability ride alongside as the bands put through that fixed table — useful for plotting or sorting, but the bands are the actual claim.

Each factor also has a stable id and a changed field, so an updated driver is distinguishable from a withdrawn one plus a new one:

changed	Meaning
new	First seen this run
effect	Same driver, moved the score by a different amount
confidence	Same driver and same effect, but we are more or less sure it applies
both	Both moved
none	Carried forward unchanged

How much a run stands behind its answer

A score on its own cannot say how thoroughly it was reached, so three fields say it explicitly:

• belief_status — what the run did. updated published a new view. unchanged re-checked the evidence the last answer rested on, found nothing had moved, and left it standing. abstained reached no defensible answer and published nothing. degraded published, but with less to stand on than usual.
• coverage — the share of what the run set out to check that it actually reached. A score built on half the intended evidence is a weaker claim than the same score built on all of it. On an unchanged short-check this may be omitted or null.
• confidence — how much the published view itself is to be trusted, derived from coverage, how well grounded the factors are, whether they conflict, how fresh the evidence is, and whether it all came from one source. It can never exceed the confidence of the factors it rests on. Likewise may be omitted or null when the run did not recompose a view.
• score_qualifiers — facts you need in order to read the number correctly, such as a category of drivers having hit its cap, or a second independent read of the evidence landing some distance away.
• reason_codes — machine-readable reasons for how the run ended, especially when it abstained.

When there is no answer

score is null when a run reached no defensible conclusion and had no previous answer to fall back on — a tracker's first run that abstained. Nothing is published, belief_status is abstained, and reason_codes says why. A number is not invented to fill the gap, and 50 is not more honest than nothing.

How Modes Affect Depth

Mode	Multiplier	Typical time	Best For
Basic	×1	< ~5 min	Quick answer — routine monitoring
Advanced	×6	< ~15 min	Think deeper — nuanced analysis
Super	×25	< ~50 min	Mission critical — highest reliability
Zen	×55	< ~60 min	Take your time — deepest research (async only, sync: false)

Higher modes invest more time and compute before producing a score. zen requires async execution — sync requests return 400.

Modes scale three things: how much of the problem gets covered, how many independent readings of it run in parallel, and how much budget there is to catch and correct a mistake mid-run.

Score Stability

Scores are designed to converge when the underlying situation is stable:

• No new information → the previous answer stands, and the run reports unchanged
• New information → the score adjusts, and the insight explains the change
• Higher modes → deeper evidence gathering before the score moves

A scheduled run begins by re-asking the specific sources the last answer rested on. If none of them moved, the run stops there and returns the previous answer unchanged — which costs a fraction of a full run, and is why a quiet tracker is cheap to keep running.

---

Score Distribution

Scores are grouped into 20-point range buckets for distribution analysis:

Score Range	Meaning
80 – 100	Strong positive with high certainty
60 – 80	Good outlook — worth acting on
40 – 60	Average, uncertain, or needs more data
20 – 40	Warning sign — pay attention
0 – 20	Critical with high certainty — immediate action needed

---

Receiving Results

There are several ways to stay informed when your trackers produce new results:

Method	Description
Console	View all results in real-time on your tracker's dashboard. Filter by score and date.
Email	Get an email when a run publishes a materially different score that crosses your alert threshold. Enable per-tracker in notification settings.
Webhooks	Receive a POST request to your endpoint with the full result payload, on the same trigger as email. Great for automating workflows.
API Polling	Use GET /api/trackers/{id}/runs to fetch results programmatically. Supports sync mode for instant results.

What triggers a notification

Every run is visible in the Console and through the API. Notifications are narrower on purpose — a threshold alone would email you nightly about a world that has not moved, because the score persists between runs. Three things must all hold:

1. The run published something. An unchanged or abstained run sends nothing.
2. The score moved. A run can publish because a factor's confidence shifted while the number stayed put; that is worth reading on the page and not worth an email.
3. The score crosses your threshold.

Setting Up Notifications

In the Console, open a tracker → Settings → Notifications to configure email alerts or webhook URLs. You can also set these via the API using notification_config when creating or updating a tracker.