Hanzo
OpenapiEvent

Top returns the caller org's ranked lenses for one window, five of them at once.

Top returns the caller org's ranked lenses for one window, five of them at once.

GET /v1/event/top

Addresshttps://api.hanzo.ai/v1/event/top
MethodGET
Operationget_event_top
AuthAuthorization: Bearer $HANZO_API_KEY

Top returns the caller org's ranked lenses for one window, five of them at once. models ranks LLM models by spend and is always real; products ranks commerce orders by revenue; topPages ranks requested paths, topReferrers the external referrer domains ("(direct)" for a missing or same-origin one) and topSources the utm_source campaigns ("(none)" when absent), each by pageviews. Every lens carries each row's share of the in-window total, so a top-N honestly shows the long tail.

The four event lenses report available=false rather than fabricating zeros when the product-event table holds nothing yet. The org is the validated principal's — never a parameter. 403 without a validated bearer, 400 on an unknown range, 503 when the warehouse is unreachable.

Request

4 fields.

FieldInTypeRequiredDescription
rangequerystringRange is a relative window: a count and a unit — 24h, 7d, 90d, any <N>h or <N>d — or day, week, month, all. Default 24h.
startquerystringStart is the inclusive lower bound of a custom window, RFC3339.
endquerystringEnd is the exclusive upper bound of a custom window, RFC3339.
limitqueryintegerLimit bounds every ranked lens in the response.

Response

StatusBodyMeaning
200Topok

200 body — 51 fields.

FieldInTypeAlwaysDescription
endbodystringEnd is the window's exclusive upper bound, RFC3339 UTC.
modelsbodyTopModels
models.availablebodybooleanAvailable is true whenever the ledger answered, including with no rows.
models.itemsbodyModelRow[]Items is the ranked models, highest spend first.
models.items[].modelbodystringModel is the model id, e.g.
models.items[].pctbodynumberPct is this model's share of the window's returned spend, 0..100, one decimal.
models.items[].providerbodystringProvider is who served it.
models.items[].requestsbodyintegerRequests is how many calls went to this model.
models.items[].spendCentsbodyintegerSpendCents is what they cost, in cents.
models.items[].tokensbodyintegerTokens is prompt plus completion tokens over those calls.
models.sourcebodystringSource is the warehouse table the lens read.
productsbodyTopProducts
products.availablebodybooleanAvailable is false when the product-event table could not be read.
products.itemsbodyProductRow[]Items is the ranked products, highest revenue first.
products.items[].ordersbodyintegerOrders is how many order_completed events carried it.
products.items[].productIdbodystringProductID is the product the order events named.
products.items[].revenuebodynumberRevenue is the total they carried, in the events' own currency unit.
products.items[].unitsbodyintegerUnits is the summed quantity sold.
products.reasonbodystringReason says why the lens is unavailable.
products.sourcebodystringSource is the warehouse table the lens read.
rangebodystringRange is the window that was actually applied: 24h, 7d, 30d or custom.
scopebodyScope
scope.orgbodystringOrg is the IAM org slug the rows were read under: the validated principal's, resolved server-side.
startbodystringStart is the window's inclusive lower bound, RFC3339 UTC.
topPagesbodyBreakdown
topPages.availablebodybooleanAvailable is false when the product-event table could not be read.
topPages.itemsbodyBreakdownRow[]Items is the ranked buckets, most pageviews first.
topPages.items[].keybodystringKey is the bucket: a requested path, a referrer domain ("(direct)" for none or a same-origin one), or a utm_source ("(none)" when absent).
topPages.items[].pageviewsbodyintegerPageviews is how many $pageview events fell in this bucket.
topPages.items[].pctbodynumberPct is this bucket's share of ALL in-window pageviews, 0..100, one decimal — not of the returned rows, so a top-N shows the long tail honestly.
topPages.items[].visitorsbodyintegerVisitors is how many distinct people they came from.
topPages.reasonbodystringReason says why the lens is unavailable.
topPages.sourcebodystringSource is the warehouse table the lens read.
topReferrersbodyBreakdown
topReferrers.availablebodybooleanAvailable is false when the product-event table could not be read.
topReferrers.itemsbodyBreakdownRow[]Items is the ranked buckets, most pageviews first.
topReferrers.items[].keybodystringKey is the bucket: a requested path, a referrer domain ("(direct)" for none or a same-origin one), or a utm_source ("(none)" when absent).
topReferrers.items[].pageviewsbodyintegerPageviews is how many $pageview events fell in this bucket.
topReferrers.items[].pctbodynumberPct is this bucket's share of ALL in-window pageviews, 0..100, one decimal — not of the returned rows, so a top-N shows the long tail honestly.
topReferrers.items[].visitorsbodyintegerVisitors is how many distinct people they came from.
topReferrers.reasonbodystringReason says why the lens is unavailable.
topReferrers.sourcebodystringSource is the warehouse table the lens read.
topSourcesbodyBreakdown
topSources.availablebodybooleanAvailable is false when the product-event table could not be read.
topSources.itemsbodyBreakdownRow[]Items is the ranked buckets, most pageviews first.
topSources.items[].keybodystringKey is the bucket: a requested path, a referrer domain ("(direct)" for none or a same-origin one), or a utm_source ("(none)" when absent).
topSources.items[].pageviewsbodyintegerPageviews is how many $pageview events fell in this bucket.
topSources.items[].pctbodynumberPct is this bucket's share of ALL in-window pageviews, 0..100, one decimal — not of the returned rows, so a top-N shows the long tail honestly.
topSources.items[].visitorsbodyintegerVisitors is how many distinct people they came from.
topSources.reasonbodystringReason says why the lens is unavailable.
topSources.sourcebodystringSource is the warehouse table the lens read.

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.


Event API · All Hanzo APIs · Interactive reference

How is this guide?

On this page