Report your organisation's model: what it learned, and what it realised

State reports the caller organisation's own model: what it has learned, whether it is live or still in shadow, the threshold in force, the appetite it…

GET /v1/risk/state

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


Address	`https://api.hanzo.ai/v1/risk/state`
Method	`GET`
Operation	`riskState`
Auth	`Authorization: Bearer $HANZO_API_KEY`

State reports the caller organisation's own model: what it has learned, whether it is live or still in shadow, the threshold in force, the appetite it stated beside the share it actually realised, every refusal by reason, every feature that read blind, and how much of the organisation's own event surface has been folded in.

It covers ONE organisation. A caller cannot learn another's volumes, alert rate or behaviour from it, because the state is read out of a model that holds only its own.

Request

GET /v1/risk/state takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	riskModelState	ok

200 body — 36 fields.

Field	In	Type	Always	Description
`aggregates`	body	riskAggregates	—
`aggregates.bound`	body	integer	—	Bound is the most they can hold.
`aggregates.forgotten`	body	integer	—	Forgotten is how many of its own subjects have been dropped to stay inside that bound.
`aggregates.saturated`	body	boolean	—	Saturated is whether the bound is binding right now.
`aggregates.subjects`	body	integer	—	Subjects is how many of this organisation's subjects the aggregates hold.
`blind`	body	object	—	Blind counts, per feature, how often it took its neutral value for want of data.
`blind.*`	body	integer	—
`cut`	body	number	—	Cut is the threshold in force, derived from Stated as a quantile of the scores actually observed.
`descends`	body	string	—	Descends is the published value the working model grew out of: the newest one whose mass count it has reached or passed.
`disposed`	body	integer	—	Disposed is how many published values retention has taken.
`learned`	body	integer	—	Learned is how many events the model has learned from.
`live`	body	boolean	—	Live is false while the model is in shadow — scoring, learning and recording what it WOULD have alerted on, and changing no outcome.
`policy`	body	integer	—	Policy is the version of the decision regime this model is deciding under, from your organisation's own policy history (GET /v1/risk/policy).
`realised`	body	number	—	Realised is the share that actually was.
`refused`	body	object	—	Refused counts events the model would not score, by reason.
`refused.*`	body	integer	—
`sample`	body	number	—	Sample is the share of below-the-line events retained for review, which is how the miss rate is measured rather than assumed.
`saturated`	body	boolean	—	Saturated means no threshold can honour the stated appetite because too much of the stream scores in the top bucket, so the model is alerting on nothing — the…
`shape`	body	string	—	Shape is the model's identity, as `<family>:<digest>`: the KIND of model, and that family's own digest over the inventory in order and the detector's geometry…
`stated`	body	number	—	Stated is the share of the stream this organisation said may be examined.
`surface`	body	riskSurface	—
`surface.folded`	body	integer	—	Folded is how many buckets of the tenant's own feature surface were folded into the model when it became resident.
`surface.gap`	body	string	—	Gap says why the fold did not happen or did not complete, when that is the case.
`surface.refused`	body	integer	—	Refused is how many buckets of this organisation's own surface the fold could not fold, because a subject on them is longer than this plane's own field bound.
`surface.replayed`	body	integer	—	Replayed is how many of this organisation's own recorded observations rebuilt its sliding aggregates when the model became resident.
`surface.rolled`	body	integer	—	Rolled is how many windows of this organisation's own source planes — product events, captured failures, metered inference — were rolled up into its feature…
`surface.window`	body	string	—	Window is the lookback the fold covered.
`tenant`	body	string	—	Tenant is the qualified key the model is held under — the brand whose issuer vouched for the caller and the organisation it acts for.
`values`	body	riskModelValue[]	—	Values is your organisation's own published model values, newest first — every state it deliberately named, each addressed by its own content and immutable.
`values[].address`	body	string	—	Address names this value by its own content: the model's shape, the geometry seed, its position in the window, its threshold, its masses as IEEE-754 bits and…
`values[].at`	body	string	—	At is when it was published, RFC 3339, on the server clock.
`values[].learned`	body	integer	—	Learned is how many events are behind the masses.
`values[].sequence`	body	integer	—	Sequence is this value's place in YOUR organisation's own history, from 1 and contiguous until retention disposes of the oldest.
`values[].shape`	body	string	—	Shape NAMES the model space the masses are only meaningful against, as `<family>:<digest>` — the KIND of model, and that family's own digest over the feature…
`values[].warmed`	body	string	—	Warmed is how far your own event surface had been folded in when this value was published, RFC 3339.
`warm`	body	boolean	—	Warm is whether that is enough for the model to have an opinion at all.

Failure carries the platform error shape — see Errors.

Examples

hanzo risk state get

import { Configuration, RiskApi } from 'hanzoai';

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

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = RiskApi(client).risk_state()

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

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

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

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

let result = risk_api::risk_state(&cfg, Default::default()).await?;

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

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

var result = new RiskApi(client).riskState();

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

Tool risk, op riskState — 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": "risk",
         "arguments": {
           "op": "riskState",
           "input": {}
         }
       }
     }'

Risk API · All Hanzo APIs · Interactive reference

Report your organisation's model: what it learned, and what it realised

Request

Response

Examples

On this page