# List leaderboard

URL: https://docs.hanzo.ai/docs/openapi/affiliate/get-affiliate-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 →](https://docs.hanzo.ai/docs/openapi/affiliate) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                                 |
| ------------- | ----------------------------------------------- |
| **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](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo affiliate leaderboard
```

**SDK**

**.ts**

```ts
import { Configuration, AffiliateApi } from 'hanzoai';

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

**.py**

```python
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()
```

**.go**

```go
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
}
```

**.rs**

```rust
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?;
```

**.java**

```java
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();
```

**HTTP**

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

**MCP**

Tool `affiliate`, op `get_affiliate_leaderboard` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`.

```bash
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](https://docs.hanzo.ai/docs/openapi/affiliate) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)