# List activity URL: https://docs.hanzo.ai/docs/openapi/leaderboard/get-leaderboard-activity > Returns the per-day usage series for ONE authorized subject — the points a contribution heatmap and a timeline are drawn from, gap-filled so every day in the range is present. `GET /v1/leaderboard/activity` > [Leaderboard →](https://docs.hanzo.ai/docs/openapi/leaderboard) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | ---------------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/leaderboard/activity` | | **Method** | `GET` | | **Operation** | `get_leaderboard_activity` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Returns the per-day usage series for ONE authorized subject — the points a contribution heatmap and a timeline are drawn from, gap-filled so every day in the range is present. Authorization is resolved server-side from the validated principal, so a caller can never widen the subject past what they are entitled to: a non-admin reads only themselves and their own org. subject=project answers empty with a note, because the usage ledger records no project column yet. When the warehouse is not connected the series answers empty with available=false rather than fabricated days. ## Request 4 fields. | Field | In | Type | Required | Description | | --------- | ----- | ------ | -------- | -------------------------------------------------------------------------- | | `subject` | query | string | — | Subject is what the series is about: "user" (default), "org" or "project". | | `id` | query | string | — | ID names the subject within what the caller is entitled to see. | | `from` | query | string | — | From is the first day of the range, "2006-01-02". | | `to` | query | string | — | To is the last day of the range, "2006-01-02". | ## Response | Status | Body | Meaning | | --------- | ------------------------ | ------- | | `200` | leaderboard.ActivityView | ok | | `default` | problem-details | refused | `200` body — 19 fields. | Field | In | Type | Always | Description | | -------------------- | ---- | ---------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `available` | body | boolean | — | Available is false when nothing could be read: the warehouse is not connected, the rollup is not ready, or the subject is one the ledger cannot attribute (see Note). | | `days` | body | leaderboard.ActivityPoint\[] | — | Days is the gap-filled series, one point per calendar day from From up to (not including) To, in ascending order, zero-valued days included. | | `days[].costCents` | body | integer (int64) | — | CostCents is the day's spend in whole US cents. | | `days[].day` | body | string | — | Day is the UTC calendar day this point covers, "2006-01-02". | | `days[].requests` | body | integer (int64) | — | Requests is the subject's request count on this day. | | `days[].tokens` | body | integer (int64) | — | Tokens is prompt+completion tokens on this day — normally the heatmap's intensity, scaled against ActivityTotals.MaxTokens. | | `from` | body | string | — | From is the first day in Days, "2006-01-02" inclusive. | | `id` | body | string | — | ID is the subject the server actually read, after resolving "me"/empty to the caller and bounding it to what they may see — a ledger "owner/name" for a user, an org id for an org. | | `note` | body | string | — | Note explains an empty-but-not-broken answer in plain words — today only subject=project, which the usage ledger records no column for. | | `source` | body | string | — | Source names the table the series was aggregated from (the derived daily rollup, hanzo.usage\_rollup\_daily). | | `subject` | body | string | — | Subject echoes what the series is about: user\|org\|project. | | `to` | body | string | — | To is the EXCLUSIVE upper bound, "2006-01-02" — the day AFTER the last point in Days. | | `totals` | body | leaderboard.ActivityTotals | — | | | `totals.activeDays` | body | integer (int64) | — | ActiveDays counts the days with any usage at all — the streak/consistency number. | | `totals.costCents` | body | integer (int64) | — | CostCents is the window's spend in whole US cents, the sum of Days\[].CostCents. | | `totals.maxRequests` | body | integer (int64) | — | MaxRequests is the same ceiling for a request-based heatmap — the busiest single day's request count, 0 for an idle window. | | `totals.maxTokens` | body | integer (int64) | — | MaxTokens is the busiest single day's token count: the ceiling to normalize a token heatmap against, so the darkest cell is that day. | | `totals.requests` | body | integer (int64) | — | Requests is the sum of Days\[].Requests over the whole window. | | `totals.tokens` | body | integer (int64) | — | Tokens is the sum of Days\[].Tokens over the whole window. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo leaderboard activity ``` **SDK** **.ts** ```ts import { Configuration, LeaderboardApi } from 'hanzoai'; const api = new LeaderboardApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getLeaderboardActivity(); ``` **.py** ```python 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_activity() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.LeaderboardAPI.GetLeaderboardActivity(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::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_activity(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.LeaderboardApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new LeaderboardApi(client).getLeaderboardActivity(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/leaderboard/activity \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** Tool `leaderboard`, op `get_leaderboard_activity` — 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": "leaderboard", "arguments": { "op": "get_leaderboard_activity", "input": {} } } }' ``` --- [Leaderboard API](https://docs.hanzo.ai/docs/openapi/leaderboard) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)