Leaderboard ranks AI usage over a window, either the users of the caller's own…

Leaderboard ranks AI usage over a window, either the users of the caller's own org or organizations against each other, and always reports the caller's…

GET /v1/leaderboard

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


Address	`https://api.hanzo.ai/v1/leaderboard`
Method	`GET`
Operation	`get_leaderboard`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Leaderboard ranks AI usage over a window, either the users of the caller's own org or organizations against each other, and always reports the caller's own standing even when it falls outside the returned page. Identities are private by default: a caller sees themselves, plus the peers or orgs that opted into public listing, and only an admin sees their own org's members named. Cross-org spend is restricted to platform admins. When the warehouse is not connected the board answers empty with available=false rather than a fabricated rank.

Request

4 fields.

Field	In	Type	Required	Description
`scope`	query	string	—	Scope picks the board: "personal" (default) ranks the caller among their own org's users, "org" is that same org board named for an admin, "global" ranks…
`metric`	query	string	—	Metric is the value ranked: tokens (default), requests, or cost.
`period`	query	string	—	Period is the window ranked: day, week, month (default) or all.
`limit`	query	integer	—	Limit caps the rows returned, clamped to 100.

Response

Status	Body	Meaning
`200`	LeaderboardView	ok

200 body — 28 fields.

Field	In	Type	Always	Description
`available`	body	boolean	—	Available is false when the usage warehouse is not connected or its rollup is not ready.
`end`	body	string	—	End is the EXCLUSIVE upper bound of the window, "2006-01-02" — the day after the last one counted.
`metric`	body	string	—	Metric echoes the value ranked: tokens\|requests\|cost.
`period`	body	string	—	Period is the window's canonical label: day\|week\|month\|all.
`rows`	body	LeaderboardRow[]	—	Rows are the ranked subjects, best first, at most the requested limit of them.
`rows[].anonymous`	body	boolean	—	Anonymous is true when this subject's identity was withheld and Handle is the "Anonymous" placeholder: the metric is real, the name is not.
`rows[].costCents`	body	integer	—	CostCents is this subject's spend in whole US cents (not dollars, not millicents).
`rows[].handle`	body	string	—	Handle is the display identity to render: the peer's chosen handle if they opted into public listing, their username if the viewer is an admin of their org,…
`rows[].metric`	body	integer	—	Metric is the value the board was ranked by, copied from Requests, Tokens or CostCents according to the request's metric.
`rows[].rank`	body	integer	—	Rank is this subject's 1-based standing in the window, 1 being the top.
`rows[].requests`	body	integer	—	Requests is how many AI requests this subject made in the window.
`rows[].self`	body	boolean	—	Self marks the caller's own row so a client can highlight it in place.
`rows[].tokens`	body	integer	—	Tokens is prompt+completion tokens this subject spent in the window.
`scope`	body	string	—	Scope echoes the board that was served: personal\|org\|global.
`self`	body	SelfRank	—
`self.costCents`	body	integer	—	CostCents is the caller's own spend in whole US cents.
`self.handle`	body	string	—	Handle is how the caller appears on this board: their chosen handle, falling back to their username, on a user board; their org id on the global board.
`self.listed`	body	boolean	—	Listed says whether the caller is publicly visible on this board: opted in on a user board, org opted in (or the viewer is a platform admin) on the global one.
`self.metric`	body	integer	—	Metric is whichever of the three values above the board was ranked by, so a client can compare the caller against the rows without re-reading the request.
`self.ofTotal`	body	integer	—	OfTotal is the size of the universe Rank is out of — "rank N of OfTotal".
`self.rank`	body	integer	—	Rank is the caller's 1-based standing, computed as (subjects whose windowed metric strictly exceeds the caller's) + 1.
`self.ranked`	body	boolean	—	Ranked is false when the caller holds no position: they had no usage in the window, or (on the global board) their org has not opted into public listing and so…
`self.requests`	body	integer	—	Requests is the caller's own request count in the window, 0 if they were idle.
`self.tokens`	body	integer	—	Tokens is the caller's own prompt+completion tokens in the window.
`source`	body	string	—	Source names the table these numbers were aggregated from (the derived daily rollup, hanzo.usage_rollup_daily), so an operator can tell exactly what was read.
`start`	body	string	—	Start is the first day counted, "2006-01-02" inclusive.
`subject`	body	string	—	Subject is what the rows stand for — "user" on a personal or org board, "org" on the global one.
`total`	body	integer	—	Total is how many subjects were ranked in the window — the org's active users, or the active/opted-in orgs on the global board.

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, LeaderboardApi } from 'hanzoai';

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

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = LeaderboardApi(client).get_leaderboard()

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

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

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

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

let result = leaderboard_api::get_leaderboard(&cfg, Default::default()).await?;

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

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

var result = new LeaderboardApi(client).getLeaderboard();

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/leaderboard \
  -H "Authorization: Bearer $HANZO_API_KEY"

The door reaches leaderboard through the leaderboard tool, which names its 6 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": "get_usage_activity"
         }
       }
     }'

Leaderboard API · All Hanzo APIs · Interactive reference

Leaderboard ranks AI usage over a window, either the users of the caller's own…

Request

Response

Examples

On this page