Skip to main content
POST
Run a widget aggregation

Authorizations

Authorization
string
header
required

Bearer token authentication via Auth0. Users authenticate through Auth0 Universal Login. Include the access token in the Authorization header: Authorization: Bearer <token>

Headers

X-Active-Brand
string<uuid>
X-Active-Catalog
string<uuid>

Optional catalog scope for the aggregation

Path Parameters

workspaceId
string
required

The workspace ID

Pattern: ^ws_[a-z0-9]+$

Query Parameters

brand_id
string<uuid>

Body

application/json
event_types
string[] | null
required

Filter by event types (canonical or custom). null/empty = all events.

Maximum array length: 50
Pattern: ^[a-z][a-z0-9_]{1,62}$
group_by
string
required

One of: none, event_type, session, day, hour, product_id; OR metadata. where key matches /^[a-z_][a-z0-9_]{0,62}$/

aggregation
enum<string>
required
Available options:
count,
count_distinct,
sum,
avg
time_window_days
integer
required
Required range: 1 <= x <= 365
value_field
enum<string>

Required when aggregation is sum or avg; ignored for count/count_distinct

Available options:
value,
amount,
price,
quantity,
duration_ms,
score,
rating,
session_id,
product_id,
agent_id,
customer_id
limit
integer
default:100
Required range: 1 <= x <= 1000

Response

Aggregation result rows

rows
object[]
required
generated_at
string<date-time>
required
cache_hit
boolean
required
Last modified on April 25, 2026