Hanzo
OpenapiLeaderboard

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

Addresshttps://api.hanzo.ai/v1/leaderboard/activity
MethodGET
Operationget_leaderboard_activity
AuthAuthorization: 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.

FieldInTypeRequiredDescription
subjectquerystringSubject is what the series is about: "user" (default), "org" or "project".
idquerystringID names the subject within what the caller is entitled to see. Omitted (or "me") it is the caller themselves, or their own org.
fromquerystringFrom is the first day of the range, "2006-01-02".
toquerystringTo is the last day of the range, "2006-01-02".

Response

StatusBodyMeaning
200ActivityViewok

200 body — 19 fields.

FieldInTypeAlwaysDescription
availablebodybooleanAvailable 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…
daysbodyActivityPoint[]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[].costCentsbodyintegerCostCents is the day's spend in whole US cents.
days[].daybodystringDay is the UTC calendar day this point covers, "2006-01-02".
days[].requestsbodyintegerRequests is the subject's request count on this day.
days[].tokensbodyintegerTokens is prompt+completion tokens on this day — normally the heatmap's intensity, scaled against ActivityTotals.MaxTokens.
frombodystringFrom is the first day in Days, "2006-01-02" inclusive.
idbodystringID 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,…
notebodystringNote explains an empty-but-not-broken answer in plain words — today only subject=project, which the usage ledger records no column for.
sourcebodystringSource names the table the series was aggregated from (the derived daily rollup, hanzo.usage_rollup_daily).
subjectbodystringSubject echoes what the series is about: user|org|project.
tobodystringTo is the EXCLUSIVE upper bound, "2006-01-02" — the day AFTER the last point in Days.
totalsbodyActivityTotals
totals.activeDaysbodyintegerActiveDays counts the days with any usage at all — the streak/consistency number.
totals.costCentsbodyintegerCostCents is the window's spend in whole US cents, the sum of Days[].CostCents.
totals.maxRequestsbodyintegerMaxRequests is the same ceiling for a request-based heatmap — the busiest single day's request count, 0 for an idle window.
totals.maxTokensbodyintegerMaxTokens is the busiest single day's token count: the ceiling to normalize a token heatmap against, so the darkest cell is that day.
totals.requestsbodyintegerRequests is the sum of Days[].Requests over the whole window.
totals.tokensbodyintegerTokens 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.


Leaderboard API · All Hanzo APIs · Interactive reference

How is this guide?

On this page