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
| Address | https://api.hanzo.ai/v1/event/top |
| Method | GET |
| Operation | get_event_top |
| Auth | Authorization: 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.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
range | query | string | — | Range 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. |
start | query | string | — | Start is the inclusive lower bound of a custom window, RFC3339. |
end | query | string | — | End is the exclusive upper bound of a custom window, RFC3339. |
limit | query | integer | — | Limit bounds every ranked lens in the response. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | Top | ok |
200 body — 51 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
end | body | string | — | End is the window's exclusive upper bound, RFC3339 UTC. |
models | body | TopModels | — | |
models.available | body | boolean | — | Available is true whenever the ledger answered, including with no rows. |
models.items | body | ModelRow[] | — | Items is the ranked models, highest spend first. |
models.items[].model | body | string | — | Model is the model id, e.g. |
models.items[].pct | body | number | — | Pct is this model's share of the window's returned spend, 0..100, one decimal. |
models.items[].provider | body | string | — | Provider is who served it. |
models.items[].requests | body | integer | — | Requests is how many calls went to this model. |
models.items[].spendCents | body | integer | — | SpendCents is what they cost, in cents. |
models.items[].tokens | body | integer | — | Tokens is prompt plus completion tokens over those calls. |
models.source | body | string | — | Source is the warehouse table the lens read. |
products | body | TopProducts | — | |
products.available | body | boolean | — | Available is false when the product-event table could not be read. |
products.items | body | ProductRow[] | — | Items is the ranked products, highest revenue first. |
products.items[].orders | body | integer | — | Orders is how many order_completed events carried it. |
products.items[].productId | body | string | — | ProductID is the product the order events named. |
products.items[].revenue | body | number | — | Revenue is the total they carried, in the events' own currency unit. |
products.items[].units | body | integer | — | Units is the summed quantity sold. |
products.reason | body | string | — | Reason says why the lens is unavailable. |
products.source | body | string | — | Source is the warehouse table the lens read. |
range | body | string | — | Range is the window that was actually applied: 24h, 7d, 30d or custom. |
scope | body | Scope | — | |
scope.org | body | string | — | Org is the IAM org slug the rows were read under: the validated principal's, resolved server-side. |
start | body | string | — | Start is the window's inclusive lower bound, RFC3339 UTC. |
topPages | body | Breakdown | — | |
topPages.available | body | boolean | — | Available is false when the product-event table could not be read. |
topPages.items | body | BreakdownRow[] | — | Items is the ranked buckets, most pageviews first. |
topPages.items[].key | body | string | — | Key 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[].pageviews | body | integer | — | Pageviews is how many $pageview events fell in this bucket. |
topPages.items[].pct | body | number | — | Pct 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[].visitors | body | integer | — | Visitors is how many distinct people they came from. |
topPages.reason | body | string | — | Reason says why the lens is unavailable. |
topPages.source | body | string | — | Source is the warehouse table the lens read. |
topReferrers | body | Breakdown | — | |
topReferrers.available | body | boolean | — | Available is false when the product-event table could not be read. |
topReferrers.items | body | BreakdownRow[] | — | Items is the ranked buckets, most pageviews first. |
topReferrers.items[].key | body | string | — | Key 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[].pageviews | body | integer | — | Pageviews is how many $pageview events fell in this bucket. |
topReferrers.items[].pct | body | number | — | Pct 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[].visitors | body | integer | — | Visitors is how many distinct people they came from. |
topReferrers.reason | body | string | — | Reason says why the lens is unavailable. |
topReferrers.source | body | string | — | Source is the warehouse table the lens read. |
topSources | body | Breakdown | — | |
topSources.available | body | boolean | — | Available is false when the product-event table could not be read. |
topSources.items | body | BreakdownRow[] | — | Items is the ranked buckets, most pageviews first. |
topSources.items[].key | body | string | — | Key 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[].pageviews | body | integer | — | Pageviews is how many $pageview events fell in this bucket. |
topSources.items[].pct | body | number | — | Pct 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[].visitors | body | integer | — | Visitors is how many distinct people they came from. |
topSources.reason | body | string | — | Reason says why the lens is unavailable. |
topSources.source | body | string | — | Source 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.
import { Configuration, EventApi } from 'hanzoai';
const api = new EventApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getEventTop();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import EventApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = EventApi(client).get_event_top()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.EventAPI.GetEventTop(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, event_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = event_api::get_event_top(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.EventApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new EventApi(client).getEventTop();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/event/top \
-H "Authorization: Bearer $HANZO_API_KEY"The door declares no tool for event — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.
How is this guide?