Show where a version's rows came from, and whether that can still be…
Shows where a version's rows came from and whether that can still be demonstrated.
GET /v1/dataset/{name}/lineage
| Address | https://api.hanzo.ai/v1/dataset/{name}/lineage |
| Method | GET |
| Operation | riskDatasetLineage |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Shows where a version's rows came from and whether that can still be demonstrated.
The answer is MEASURED, not recalled: the plane asks the source the same bounded question again and compares it to the fingerprint taken when the version was built. Anything but exact agreement is reported as drift — the source is fed by a rollup that runs behind the events, so "it holds more now" is the ordinary case and it means re-running the spec would not reproduce this version. An admitted gap is actionable; an unfalsifiable claim is not.
IT IS A PRICED, BOUNDED READ, because it is the same statement a materialisation is charged for: an exact distinct-count over up to 400 days of this org's feature surface. It takes the org's ONE source-scan slot, so a tenant looping it spends one scan and not a thousand; it counts against the plane's ceiling, so the fleet's warehouse is bounded too; and it runs under this plane's own deadline rather than the caller's patience.
Request
2 fields.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | Name is the dataset, from the path. |
version | query | integer | — | Version is the version to trace. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | riskLineage | ok |
200 body — 14 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
dataset | body | string | — | Dataset is the dataset traced. |
digest | body | string | — | Digest is the version's fingerprint, repeated here so a lineage answer is self-contained. |
from | body | string | — | From is where the window actually read opens, RFC 3339. |
holds | body | integer | — | Holds is what the source holds for the same window NOW. |
oversize | body | integer | — | Oversize is how many subjects the window held that were too large to represent when this version was built. |
refusal | body | string | — | Refusal says which way it failed — the window expired, or the source now holds a different count. |
reproducible | body | boolean | — | Reproducible is true when the source still holds what this version was built from — measured by asking it again, not recalled. |
retention | body | string | — | Retention is the source's own expiry rule as the store reports it, read at materialisation time rather than assumed. |
rows | body | integer | — | Rows is how many rows the source held for that window at materialisation time. |
share | body | integer | — | Share is the fraction of subjects admitted, in thousandths. |
source | body | string | — | Source is the plane the rows were derived from. |
subjects | body | integer | — | Subjects is how many distinct subjects those rows belonged to. |
to | body | string | — | To is where it ends: the spec's own end pulled BACK by the maturity horizon, so it is usually earlier than the spec says. |
version | body | integer | — | Version is the version traced — the one asked for, or the newest published one when the request named none. |
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, DatasetApi } from 'hanzoai';
const api = new DatasetApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskDatasetLineage({ name: 'name' });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import DatasetApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = DatasetApi(client).risk_dataset_lineage(name='name')cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.DatasetAPI.RiskDatasetLineage(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, dataset_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = dataset_api::risk_dataset_lineage(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.DatasetApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new DatasetApi(client).riskDatasetLineage();curl https://api.hanzo.ai/v1/dataset/<name>/lineage \
-H "Authorization: Bearer $HANZO_API_KEY"Tool dataset, op riskDatasetLineage — 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": "dataset",
"arguments": {
"op": "riskDatasetLineage",
"input": {
"name": "<name>"
}
}
}
}'How is this guide?