List overview

Returns the caller org's analytics KPIs for one time window.

GET /v1/event/overview

Event → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/event/overview`
Method	`GET`
Operation	`get_event_overview`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Returns the caller org's analytics KPIs for one time window. Three lenses over one warehouse: llm is the live per-org LLM usage ledger (requests, tokens, spend, models, providers, errors) and is always real; web (pageviews, visitors, sessions) and commerce (orders, revenue, AOV) read the product-event table and report available=false rather than fabricating zeros when it holds nothing yet.

The org is the validated principal's — never a parameter — so a caller can only ever read its own tenant. 401 without a validated bearer, 400 on an unknown range, 503 when the warehouse is unreachable.

Request

3 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.
`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.

Response

Status	Body	Meaning
`200`	event.Overview	ok
`default`	problem-details	refused

200 body — 32 fields.

Field	In	Type	Always	Description
`commerce`	body	event.CommerceOverview	—
`commerce.aov`	body	number (double)	—	AOV is average order value — Revenue/Orders, rounded to two places.
`commerce.available`	body	boolean	—	Available is false when the product-event table could not be read — the lens is reported missing rather than as zeros that look like no sales.
`commerce.orders`	body	integer (int64)	—	Orders is how many order_completed events landed in the window.
`commerce.reason`	body	string	—	Reason says why the lens is unavailable.
`commerce.revenue`	body	number (double)	—	Revenue is the total those orders carried, in the events' own currency unit.
`commerce.source`	body	string	—	Source is the warehouse table the lens read.
`end`	body	string	—	End is the window's exclusive upper bound, RFC3339 UTC.
`interval`	body	string	—	Interval is the bucket width the window implies: hour or day.
`llm`	body	event.LLMOverview	—
`llm.available`	body	boolean	—	Available is true whenever the ledger answered — including with no usage in the window, which is honest zeros rather than a missing lens.
`llm.completionTokens`	body	integer (int64)	—	CompletionTokens is the output half of Tokens.
`llm.errorRate`	body	number (double)	—	ErrorRate is Errors/Requests, 0..1, rounded to three places.
`llm.errors`	body	integer (int64)	—	Errors is how many of Requests failed.
`llm.models`	body	integer (int64)	—	Models is how many distinct models the org called.
`llm.promptTokens`	body	integer (int64)	—	PromptTokens is the input half of Tokens.
`llm.providers`	body	integer (int64)	—	Providers is how many distinct providers served them.
`llm.requests`	body	integer (int64)	—	Requests is how many LLM calls the org made in the window.
`llm.source`	body	string	—	Source is the warehouse table the lens read.
`llm.spendCents`	body	integer (int64)	—	SpendCents is what those calls cost, in cents.
`llm.tokens`	body	integer (int64)	—	Tokens is prompt plus completion tokens over those calls.
`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.
`web`	body	event.WebOverview	—
`web.available`	body	boolean	—	Available is false when the product-event table could not be read — the lens is reported missing rather than as zeros that look like real traffic.
`web.pageviews`	body	integer (int64)	—	Pageviews is how many $pageview events landed in the window.
`web.reason`	body	string	—	Reason says why the lens is unavailable.
`web.sessions`	body	integer (int64)	—	Sessions is how many distinct visits they span.
`web.source`	body	string	—	Source is the warehouse table the lens read.
`web.visitors`	body	integer (int64)	—	Visitors is how many distinct people those pageviews came from.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo event overview

.ts

.py

.go

.rs

.java

import { Configuration, EventApi } from 'hanzoai';

const api = new EventApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getEventOverview();

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

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.EventAPI.GetEventOverview(context.Background()).Execute()
if err != nil {
	return err
}

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_overview(&cfg, Default::default()).await?;

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

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

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

Event API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList health — GET /v1/event/insights/health NextGet pixel