Answers the top affiliates by lifetime accrued commission, shown by OPT-IN…

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 → · Six flows, four surfaces →


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`	affiliateBoard	ok

200 body — 13 fields.

Field	In	Type	Always	Description
`leaders`	body	leaderboardRow[]	—	Leaders are the top opt-in affiliates, by handle and aggregate figures only.
`leaders[].accruedCents`	body	integer	—	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	—	Rank is the position in the GLOBAL approved set ordered by lifetime accrued commission, 1-based.
`leaders[].referredCount`	body	integer	—	ReferredCount is how many orgs that affiliate directly referred — a count only, never which orgs.
`total`	body	integer	—	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	leaderboardRow	—
`you.accruedCents`	body	integer	—	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	—	Rank is the position in the GLOBAL approved set ordered by lifetime accrued commission, 1-based.
`you.referredCount`	body	integer	—	ReferredCount is how many orgs that affiliate directly referred — a count only, never which orgs.

Failure carries the platform error shape — see Errors.

Examples

hanzo affiliates leaderboard

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 := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

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

use hanzo_cloud::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.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

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

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

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

Affiliate API · All Hanzo APIs · Interactive reference

Answers the top affiliates by lifetime accrued commission, shown by OPT-IN…

Request

Response

Examples

On this page