> ## Documentation Index
> Fetch the complete documentation index at: https://docs.halal.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Stability metrics

> Flip rate, threshold distance, and trend — how likely a compliance status is to change.

## 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:

<CardGroup cols={2}>
  <Card title="Simple — on /compliance" icon="circle-info">
    A quick read: a `rating` plus human-readable `drivers`. Enough to flag a holding for review.
  </Card>

  <Card title="Full — in the Evidence Packet" icon="magnifying-glass-chart">
    The complete picture: flip rate, quarters compliant, closest threshold, trend, and drivers.
  </Card>
</CardGroup>

## Simple signal (`/compliance`)

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

```json theme={null}
{
  "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](/concepts/evidence-packets) `stability` object adds the quantitative history behind the rating.

```json theme={null}
{
  "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.

```bash theme={null}
# 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"
```

<Note>
  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.
</Note>