Activity returns the per-day usage series for ONE authorized subject — the…
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…
GET /v1/leaderboard/activity
| Address | https://api.hanzo.ai/v1/leaderboard/activity |
| Method | GET |
| Operation | get_leaderboard_activity |
| Auth | Authorization: Bearer $HANZO_API_KEY |
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. 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. Omitted (or "me") it is the caller themselves, or their own org. |
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 | ActivityView | ok |
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… |
days | body | 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 | — | 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 | — | Requests is the subject's request count on this day. |
days[].tokens | body | integer | — | 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,… |
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 | ActivityTotals | — | |
totals.activeDays | body | integer | — | ActiveDays counts the days with any usage at all — the streak/consistency number. |
totals.costCents | body | integer | — | CostCents is the window's spend in whole US cents, the sum of Days[].CostCents. |
totals.maxRequests | body | integer | — | 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 | — | 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 | — | Requests is the sum of Days[].Requests over the whole window. |
totals.tokens | body | integer | — | Tokens is the sum of Days[].Tokens over the whole window. |
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.getLeaderboardActivity();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()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.LeaderboardAPI.GetLeaderboardActivity(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_activity(&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).getLeaderboardActivity();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/activity \
-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"
}
}
}'How is this guide?