How much of the window has matured, and how much of that is judged

Reports how much of a window has matured and how much of that is judged, per source. It is the gate on training.

GET /v1/label/coverage

Label → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/label/coverage`
Method	`GET`
Operation	`riskLabelCoverage`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Reports how much of a window has matured and how much of that is judged, per source.

It is the gate on training. A supervised fit over a window whose judged count is near zero produces a number, and the number is meaningless; this op is what lets that be stated before the fit rather than discovered after it.

It reads the RECORD plane and folds every assertion at that event's OWN as-of, so the counts obey exactly the leakage rule a materialisation would. It counts only what was ASSERTED: what share of the whole event STREAM carries a label is a question about the feature plane's denominator and is not answerable here.

Request

3 fields.

Field	In	Type	Required	Description
`from`	query	string	—	From and To bound the EVENT window, half-open, RFC 3339. Unstated, the window is the 90 days ENDING where maturity begins — `to` is the horizon ago, not now.
`to`	query	string	—
`horizon`	query	integer	—	Horizon is the maturity horizon in days the coverage is measured under.

Response

Status	Body	Meaning
`200`	riskLabelCoverage	ok

200 body — 18 fields.

Field	In	Type	Always	Description
`contested`	body	integer	—	Contested is how many matured events have two visible assertions that disagree.
`events`	body	integer	—	Events is how many DISTINCT judged events those assertions name, keyed on (kind, subject, at).
`explore`	body	number	—	Explore is the share of judged events whose winning assertion came from the below-the-line sample.
`facts`	body	integer	—	Facts is how many assertions the window holds; Events is how many distinct judged events they cover.
`from`	body	string	—	From is the INCLUSIVE start of the EVENT window these counts were folded over, RFC 3339, echoed with the defaults filled in — the caller's, or 90 days before…
`horizon`	body	integer	—	Horizon is the maturity horizon these counts were measured under, IN DAYS — the caller's, or 120.
`judged`	body	integer	—	Judged is how many MATURED events resolve, at their own as-of, to something other than unjudged.
`matured`	body	integer	—	Matured is how many of those events have aged past the horizon and may therefore be admitted to a supervised set at all.
`pending`	body	integer	—	Pending is how many of this tenant's assertions the DERIVED columnar copy is not known to hold yet.
`productive`	body	integer	—	Productive is how many matured events resolve, at their own as-of, to a WINNING assertion of `productive` — the event led somewhere: escalated, reported,…
`sources`	body	riskSourceCoverage[]	—	Sources breaks the judged events down by the source that WON, so a plane that looks labelled because one noisy source dominates is visible as such.
`sources[].facts`	body	integer	—	Facts is how many assertions this source filed; Won is how many judged events it was the assertion in force for.
`sources[].source`	body	string	—	Source is the asserter these two counts are for — chargeoff, dispute, case, refund, review or sample.
`sources[].won`	body	integer	—	Won is how many JUDGED events this source's assertion was the one IN FORCE for, at that event's own as-of — it beat every other visible claim under the…
`to`	body	string	—	To is the EXCLUSIVE end of that window (at < To).
`unlabelled`	body	integer	—	Unlabelled is how many MATURED events had no assertion knowable by their own as-of — including every assertion that arrived after that instant.
`unmatured`	body	integer	—	Unmatured is how many events in the window have NOT aged past the horizon.
`unproductive`	body	integer	—	Unproductive is every OTHER judged event: the winner claimed `unproductive`, judged not suspicious.

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

import { Configuration, LabelApi } from 'hanzoai';

const api = new LabelApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskLabelCoverage();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import LabelApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = LabelApi(client).risk_label_coverage()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.LabelAPI.RiskLabelCoverage(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, label_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = label_api::risk_label_coverage(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.LabelApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new LabelApi(client).riskLabelCoverage();

curl https://api.hanzo.ai/v1/label/coverage \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool label, op riskLabelCoverage — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "label",
         "arguments": {
           "op": "riskLabelCoverage",
           "input": {}
         }
       }
     }'

Label API · All Hanzo APIs · Interactive reference

How much of the window has matured, and how much of that is judged

Request

Response

Examples

On this page