analytics scope.
Pick a window
Every endpoint takes an optionalrange, and an optional IANA timezone (default UTC) that decides where each day starts:
range you asked for is echoed back, so a stored response is self-describing.
The shape of a response
Each endpoint returns one or more panels. A panel is either a set of summary cards or a time series, and the response always names the range it covers.On the campaigns, dialer and enrichment endpoints a panel can come back
null. Each one is computed independently, so a slow or unavailable source degrades that panel rather than failing the whole call. Treat null as “not available for this window”, not as zero. The website intent and agents endpoints have no per-panel null: if their source fails, the whole call fails, and website intent answers 404 WEBSITE_TRACKING_NOT_SET_UP until tracking is set up.Buckets in a time series
Series are bucketed by the window: daily for7d, and ISO weeks for 30d and 90d. Every point is zero-filled and carries two dates:
date is a display label for the start of the bucket, and isoDate is the same date as YYYY-MM-DD. Use isoDate for date math. The enrichment panels also name the bucket in mode, daily or weekly.
Totals are exact figures for the whole window, so derive rates from the totals rather than by adding up the series. The responses carry no comparison against a previous window.
Putting it in a dashboard
1
Fetch the areas you show, in parallel
The five endpoints are independent; nothing needs to be called in order.
2
Handle null panels per panel
One unavailable source should blank one card, not the page.
3
Format dates from isoDate
The bucket size changes with the range, and
date is only a label.4
Cache for the window you display
These are roll-ups over days; polling them frequently spends rate limit for numbers that barely move.