# List top URL: https://docs.hanzo.ai/docs/openapi/event/get-event-top > Returns the caller org's ranked lenses for one window, five of them at once. `GET /v1/event/top` > [Event →](https://docs.hanzo.ai/docs/openapi/event) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/event/top` | | **Method** | `GET` | | **Operation** | `get_event_top` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | 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. 401 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 \h or \d — or day, week, month, all. | | `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` | event.Top | ok | | `default` | problem-details | refused | `200` body — 51 fields. | Field | In | Type | Always | Description | | -------------------------------- | ---- | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `end` | body | string | — | End is the window's exclusive upper bound, RFC3339 UTC. | | `models` | body | event.TopModels | — | | | `models.available` | body | boolean | — | Available is true whenever the ledger answered, including with no rows. | | `models.items` | body | event.ModelRow\[] | — | Items is the ranked models, highest spend first. | | `models.items[].model` | body | string | — | Model is the model id, e.g. zen5-coder. | | `models.items[].pct` | body | number (double) | — | 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 (int64) | — | Requests is how many calls went to this model. | | `models.items[].spendCents` | body | integer (int64) | — | SpendCents is what they cost, in cents. | | `models.items[].tokens` | body | integer (int64) | — | Tokens is prompt plus completion tokens over those calls. | | `models.source` | body | string | — | Source is the warehouse table the lens read. | | `products` | body | event.TopProducts | — | | | `products.available` | body | boolean | — | Available is false when the product-event table could not be read. | | `products.items` | body | event.ProductRow\[] | — | Items is the ranked products, highest revenue first. | | `products.items[].orders` | body | integer (int64) | — | 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 (double) | — | Revenue is the total they carried, in the events' own currency unit. | | `products.items[].units` | body | integer (int64) | — | 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 | event.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 | event.Breakdown | — | | | `topPages.available` | body | boolean | — | Available is false when the product-event table could not be read. | | `topPages.items` | body | event.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 (int64) | — | Pageviews is how many $pageview events fell in this bucket. | | `topPages.items[].pct` | body | number (double) | — | 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 (int64) | — | 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 | event.Breakdown | — | | | `topReferrers.available` | body | boolean | — | Available is false when the product-event table could not be read. | | `topReferrers.items` | body | event.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 (int64) | — | Pageviews is how many $pageview events fell in this bucket. | | `topReferrers.items[].pct` | body | number (double) | — | 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 (int64) | — | 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 | event.Breakdown | — | | | `topSources.available` | body | boolean | — | Available is false when the product-event table could not be read. | | `topSources.items` | body | event.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 (int64) | — | Pageviews is how many $pageview events fell in this bucket. | | `topSources.items[].pct` | body | number (double) | — | 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 (int64) | — | 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](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo event top ``` **SDK** **.ts** ```ts import { Configuration, EventApi } from 'hanzoai'; const api = new EventApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getEventTop(); ``` **.py** ```python 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() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.EventAPI.GetEventTop(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::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?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.EventApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new EventApi(client).getEventTop(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/event/top \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** Tool `event`, op `get_event_top` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash 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": "event", "arguments": { "op": "get_event_top", "input": {} } } }' ``` --- [Event API](https://docs.hanzo.ai/docs/openapi/event) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)