Three scopes
Endpoints are named for what they cover, and the prefix tells you which.
Within each scope the same four shapes recur:
KPIs
get_org_kpis, get_campaign_kpis — headline totals plus change against the preceding period.Breakdowns
*_metrics_aggregation — clicks grouped by one dimension, paginated. See Metrics.Time series
*_clicks_users_over_time, *_clicks_by_hour — clicks per bucket.Reports
download_*_analytics_report* — the same data as a file. See Reports.A first call
date_from and date_to are YYYY-MM-DD. Most endpoints require both; a few time-series endpoints default to the last thirty days if you omit them.
Things that will surprise you otherwise
Your date range may be moved forward
Your date range may be moved forward
Plans have a retention window. Ask for more history than yours allows and the range is silently clamped to the floor — the response tells you when this happened. See Retention.
Some breakdowns come back locked
Some breakdowns come back locked
City, region, device, browser, operating system and the UTM dimensions are plan-gated. On a plan without them you get sample rows and
"locked": true rather than an error. See Metrics.Filters change which engine answers
Filters change which engine answers
Simple queries are served from pre-aggregated rollups and are fast. Certain filters force a raw scan, and one endpoint —
get_org_metrics_batch — refuses them outright. See Filtering.Numbers move for a few minutes
Numbers move for a few minutes
Rollups are not instantaneous. A click you just generated may not appear immediately, so do not write a test that creates a link, clicks it, and asserts a count in the same breath.
Time zones
Passtimezone — an IANA name such as America/New_York — and day boundaries are computed there. Omit it and you get UTC. Worth setting explicitly: “yesterday” in UTC is not yesterday for most of your customers, and a daily series bucketed in the wrong zone shifts every peak.