List 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 → · All API references → · Get started →

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.

Examples

CLI

SDK

HTTP

MCP

hanzo leaderboard activity

.ts

.py

.go

.rs

.java

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 := 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
}

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

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

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

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

Leaderboard API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousResolve label NextList optin