Is your org's AI overview board over a window: totals (generations, prompt and…

Is your org's AI overview board over a window: totals (generations, prompt and completion tokens, cost in cents, errors, success rate, distinct models and…

GET /v1/eval/metrics

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


Address	`https://api.hanzo.ai/v1/eval/metrics`
Method	`GET`
Operation	`get_eval_metrics`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Is your org's AI overview board over a window: totals (generations, prompt and completion tokens, cost in cents, errors, success rate, distinct models and users), a gap-filled time series, a per-model breakdown with the long tail folded into "other", and latency percentiles read from the GenAI spans.

The window the answer was actually computed over is echoed back, so a client never has to infer it. A platform admin sees the board across ALL orgs; everyone else sees their own.

The board is HONEST-EMPTY where it cannot be computed: with no datastore wired, or under a named project scope the usage ledger does not yet carry, it answers a valid board with zero totals and a flat series rather than a fabricated number or a 500. Requires a validated principal; 403 without one.

Request

2 fields.

Field	In	Type	Required	Description
`range`	query	string	—	Range is 24h (the default), 7d or 30d.
`interval`	query	string	—	Interval overrides the bucket the series is grouped into: "hour" or "day".

Response

Status	Body	Meaning
`200`	Board	ok

200 body — 60 fields.

Field	In	Type	Always	Description
`byModel`	body	ModelStat[]	—	the top models by spend
`byModel[].completionTokens`	body	integer	—	tokens it answered with
`byModel[].costCents`	body	integer	—	what this model cost, in cents
`byModel[].costPct`	body	number	—	share of total spend, 0..100
`byModel[].errorRate`	body	number	—	share of its calls that failed, 0..1
`byModel[].errors`	body	integer	—	calls to it that did not succeed
`byModel[].model`	body	string	—	the model this row is about, or "other" for the fold
`byModel[].modelCount`	body	integer	—	>0 only on the "other" fold
`byModel[].p50Ms`	body	number	—	median latency, null when no spans carry it
`byModel[].p95Ms`	body	number	—	95th-percentile latency, null when unknown
`byModel[].p99Ms`	body	number	—	99th-percentile latency, null when unknown
`byModel[].promptTokens`	body	integer	—	tokens sent to it
`byModel[].provider`	body	string	—	who serves it
`byModel[].requests`	body	integer	—	calls to this model in the window
`byModel[].totalTokens`	body	integer	—	prompt plus completion
`latency`	body	LatencyStat	—
`latency.available`	body	boolean	—	false when no GenAI spans carry timing; the percentiles are then null
`latency.p50Ms`	body	number	—	median latency over the window
`latency.p95Ms`	body	number	—	95th-percentile latency
`latency.p99Ms`	body	number	—	99th-percentile latency
`other`	body	ModelStat	—
`other.completionTokens`	body	integer	—	tokens it answered with
`other.costCents`	body	integer	—	what this model cost, in cents
`other.costPct`	body	number	—	share of total spend, 0..100
`other.errorRate`	body	number	—	share of its calls that failed, 0..1
`other.errors`	body	integer	—	calls to it that did not succeed
`other.model`	body	string	—	the model this row is about, or "other" for the fold
`other.modelCount`	body	integer	—	>0 only on the "other" fold
`other.p50Ms`	body	number	—	median latency, null when no spans carry it
`other.p95Ms`	body	number	—	95th-percentile latency, null when unknown
`other.p99Ms`	body	number	—	99th-percentile latency, null when unknown
`other.promptTokens`	body	integer	—	tokens sent to it
`other.provider`	body	string	—	who serves it
`other.requests`	body	integer	—	calls to this model in the window
`other.totalTokens`	body	integer	—	prompt plus completion
`range`	body	BoardRange	—
`range.end`	body	string	—	RFC3339 (UTC)
`range.interval`	body	string	—	hour \| day
`range.range`	body	string	—	echoed label (24h \| 7d \| 30d \| custom)
`range.start`	body	string	—	RFC3339 (UTC)
`scope`	body	BoardScope	—
`scope.allOrgs`	body	boolean	—	true when a platform admin is seeing every org at once
`scope.org`	body	string	—	the org the board covers; "" when it covers all of them
`scope.project`	body	string	—	the sub-scope within the org; "" is the whole org
`series`	body	BoardPoint[]	—	one gap-filled bucket per interval, so a chart never breaks
`series[].costCents`	body	integer	—	what this bucket cost, in cents
`series[].errors`	body	integer	—	calls in this bucket that did not succeed
`series[].generations`	body	integer	—	model calls in this bucket
`series[].t`	body	string	—	RFC3339 (UTC) bucket start
`series[].totalTokens`	body	integer	—	tokens in this bucket
`totals`	body	BoardTotals	—
`totals.completionTokens`	body	integer	—	tokens the models answered with
`totals.costCents`	body	integer	—	what the window cost, in cents
`totals.errors`	body	integer	—	calls that did not succeed
`totals.generations`	body	integer	—	how many model calls the window holds
`totals.models`	body	integer	—	how many distinct models were called
`totals.promptTokens`	body	integer	—	tokens sent to the models
`totals.successRate`	body	number	—	share of calls that succeeded, 0..1
`totals.totalTokens`	body	integer	—	prompt plus completion
`totals.users`	body	integer	—	how many distinct users called them

Failure carries the platform error shape — see Errors.

Examples

hanzo evals metrics

import { Configuration, EvalApi } from 'hanzoai';

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

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = EvalApi(client).get_eval_metrics()

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

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

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

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

let result = eval_api::get_eval_metrics(&cfg, Default::default()).await?;

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

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

var result = new EvalApi(client).getEvalMetrics();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

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

The door reaches eval through the evals tool, which names its 16 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:

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

Eval API · All Hanzo APIs · Interactive reference

Is your org's AI overview board over a window: totals (generations, prompt and…

Request

Response

Examples

On this page