Skip to content
IForevents Docs
IForevents Docs
HomeDashboardGitHubPrivacyTermsSecurityIntroduction
Support and SLA

A bucketed metric over a window, optionally broken down by a property

POST
/v1/analytics/insights

Buckets created_at by hour, day, week (Monday-start) or month of the local calendar of timezone (an IANA name, default UTC; a day can last 23 or 25 hours); each point's t is its bucket start as a UTC instant. Points are filled for every bucket in the range (max 1000). Interval total skips the buckets: each series has its whole-window total and an empty points list, which suits rankings (breakdown_limit up to 1000). Metrics: total, unique_users (exact), per_user, and sum, avg, min or max of the event property named by property. A numeric metric reads a value only when the whole string parses as a finite number; anything else (missing, empty, text, nan, inf) is left out and counted in non_numeric_values. Values are IEEE doubles. A bucket with no numeric value has sum 0 and avg, min and max null (unknown, never 0). Without a breakdown there is one series keyed "$all"; with one, the top breakdown_limit values ranked by the metric (keys without a value last, ties by key), an absent property reported as key "", and the rest as one Other series ("$other", other: true).

Authorization

AuthorizationBearer <token>

Session token issued by the accounts service (or the legacy /v1/auth routes).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/analytics/insights" \  -H "Content-Type: application/json" \  -d '{    "breakdown": {      "property": "plan",      "scope": "event"    },    "breakdown_limit": 10,    "end": "2026-09-13T12:30:45Z",    "filters": [      {        "operator": "eq",        "property": "plan",        "scope": "event",        "values": [          "pro",          "growth"        ]      }    ],    "interval": "day",    "match": "all",    "metric": "total",    "start": "2026-09-01T00:00:00Z"  }'
{  "interval": "day",  "series": [    {      "key": "$all",      "points": [        {          "t": "2026-09-01T00:00:00Z",          "v": 12        }      ],      "total": 1234    }  ],  "timezone": "UTC"}
breakdown?
breakdown_limit?integer

Values listed before the rest are summed into one Other series (key $other); 1 to 25, default 10. With interval total, 1 to 1000.

compare?
end?string
Formatdate-time
event?string
filters?array<>
groups?array<>
interval?string

hour, day (default), week (Monday-start) or month buckets of the local calendar of timezone; total has no buckets: every series carries only its whole-window total and points is empty.

match?string
metric?string
property?string
start?string
Formatdate-time
timezone?string