Stability metrics

Overview

A stock’s compliance status can change when new filings land or market cap shifts. Stability metrics help portfolio managers assess rebalancing risk — how likely a holding is to flip status in the near future. The signal comes in two forms, depending on where you read it:

Simple — on /compliance

A quick read: a rating plus human-readable drivers. Enough to flag a holding for review.

Full — in the Evidence Packet

The complete picture: flip rate, quarters compliant, closest threshold, trend, and drivers.

Simple signal (`/compliance`)

The /compliance response carries a compact stability object — a rating and the drivers behind it.

{
  "stability": {
    "rating": "stable",
    "drivers": [
      {
        "code": "COMFORTABLE_BUFFERS",
        "message": "All financial ratios are well within limits",
        "severity": "info"
      }
    ]
  }
}

Field	Values
`rating`	`stable`, `watch`, or `borderline` (or `null` when there’s no history).
`drivers[].code`	Machine-readable reason code.
`drivers[].message`	Human-readable explanation.
`drivers[].severity`	`info`, `warning`, or `critical`.

Full signal (Evidence Packet)

The Evidence Packet stability object adds the quantitative history behind the rating.

{
  "stability": {
    "quarters_compliant": 7,
    "quarters_total": 8,
    "flip_rate": 0.125,
    "closest_threshold": {
      "screen": "prohibited_revenue",
      "current_distance": 0.041,
      "trend": "narrowing"
    },
    "stability_rating": "watch",
    "stability_drivers": [
      {
        "code": "APPROACHING_THRESHOLD",
        "message": "Prohibited revenue is narrowing toward the 5% limit",
        "severity": "warning"
      }
    ]
  }
}

Flip rate

flip_rate is how often the stock has changed compliance status across its analysis history, alongside quarters_compliant and quarters_total. A flip_rate of 0.0 means it has never changed status; 0.5 means it flips every other quarter.

Closest threshold

closest_threshold identifies the screen the stock is nearest to breaching. Its screen is one of the four canonical screen names — business_activity, debt_to_market_cap, cash_to_market_cap, or prohibited_revenue — and for the financial screens, current_distance is the gap to the threshold as a decimal (0.041 is 4.1 percentage points away). A small distance means the stock is close to flipping.

Trend

trend is the direction the closest ratio is moving relative to its threshold:

`trend`	Meaning
`stable`	Distance to the threshold is holding steady.
`narrowing`	Closing in on the threshold — higher risk.
`widening`	Pulling away from the threshold — lower risk.

Stability rating

stability_rating is the summary classification derived from flip rate and threshold distance:

`stability_rating`	Read
`stable`	Low flip rate, comfortable distance from every threshold.
`watch`	Moderate proximity to a threshold, or occasional flips.
`borderline`	Very close to a threshold, or frequent status changes.

stability_drivers carries the same code / message / severity shape as the simple signal, explaining what drove the rating.

Using stability for portfolio construction

Read the simple stability.rating straight off each /compliance response to triage a watchlist, then pull the full Evidence Packet for any holding rated watch or borderline to see which screen is narrowing and by how much.

# 1. Check status and stability for a holding
curl https://api.halal.sh/v1/instruments/NVDA/compliance \
  -H "X-API-Key: hsh_sandbox_your_key"

# 2. For anything flagged watch/borderline, pull the full signal
curl https://api.halal.sh/v1/instruments/NVDA/evidence \
  -H "X-API-Key: hsh_sandbox_your_key"

Stability is informational — it describes how a determination has behaved, not a forward guarantee. A stable rating can still flip on a materially different filing.

Getting Started

Core Concepts

Guides

Overview

Simple — on /compliance

Full — in the Evidence Packet

Simple signal (`/compliance`)

Full signal (Evidence Packet)

Flip rate

Closest threshold

Trend

Stability rating

Using stability for portfolio construction

​Overview

Simple — on /compliance

Full — in the Evidence Packet

​Simple signal (/compliance)

​Full signal (Evidence Packet)

​Flip rate

​Closest threshold

​Trend

​Stability rating

​Using stability for portfolio construction

Overview

Simple signal (`/compliance`)

Full signal (Evidence Packet)

Flip rate

Closest threshold

Trend

Stability rating

Using stability for portfolio construction