List leaderboard

Answers the top affiliates by lifetime accrued commission, shown by OPT-IN HANDLE with aggregate figures only, plus the caller's own exact rank.

GET /v1/affiliate/leaderboard

Affiliate → · All API references → · Get started →

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

Answers the top affiliates by lifetime accrued commission, shown by OPT-IN HANDLE with aggregate figures only, plus the caller's own exact rank.

It never discloses an org identity and never a referred org's usage. An affiliate that has set no handle still OCCUPIES its rank but is not listed — so opting out hides the name, not the position, and the visible board must not be read as a complete roster.

The caller's own row carries its exact GLOBAL rank, computed over the whole approved set rather than over the page, so it is right well outside the top of the board. Only an approved affiliate has a rank. Requires a validated principal; a signed-in non-affiliate may read the board but gets no personal row.

Request

GET /v1/affiliate/leaderboard takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	affiliate.affiliateBoard	ok
`default`	problem-details	refused

200 body — 13 fields.

Field	In	Type	Always	Description
`leaders`	body	affiliate.leaderboardRow[]	—	Leaders are the top opt-in affiliates, by handle and aggregate figures only.
`leaders[].accruedCents`	body	integer (int64)	—	AccruedCents is that affiliate's lifetime commission accrued, in cents, and what the board is ordered by.
`leaders[].handle`	body	string	—	Handle is the affiliate's self-chosen display name — the only identity the board ever carries.
`leaders[].isYou`	body	boolean	—	IsYou marks the caller's own row, so a client can highlight it without matching on a handle.
`leaders[].rank`	body	integer (int64)	—	Rank is the position in the GLOBAL approved set ordered by lifetime accrued commission, 1-based.
`leaders[].referredCount`	body	integer (int64)	—	ReferredCount is how many orgs that affiliate directly referred — a count only, never which orgs.
`total`	body	integer (int64)	—	Total is the approved population where it is known; omitted where the top page truncated and the caller has no rank to derive it from.
`you`	body	affiliate.leaderboardRow	—
`you.accruedCents`	body	integer (int64)	—	AccruedCents is that affiliate's lifetime commission accrued, in cents, and what the board is ordered by.
`you.handle`	body	string	—	Handle is the affiliate's self-chosen display name — the only identity the board ever carries.
`you.isYou`	body	boolean	—	IsYou marks the caller's own row, so a client can highlight it without matching on a handle.
`you.rank`	body	integer (int64)	—	Rank is the position in the GLOBAL approved set ordered by lifetime accrued commission, 1-based.
`you.referredCount`	body	integer (int64)	—	ReferredCount is how many orgs that affiliate directly referred — a count only, never which orgs.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo affiliate leaderboard

.ts

.py

.go

.rs

.java

import { Configuration, AffiliateApi } from 'hanzoai';

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

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AffiliateApi(client).get_affiliate_leaderboard()

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

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

use hanzo_client::apis::{configuration::Configuration, affiliate_api};

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

let result = affiliate_api::get_affiliate_leaderboard(&cfg, Default::default()).await?;

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

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AffiliateApi(client).getAffiliateLeaderboard();

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

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

Affiliate API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousReplace campaigns NextList earnings