Skip to main content
A breakdown groups clicks by one dimension and returns them ranked. The dimension is the metric parameter:

Dimensions

The campaign-scoped time-series endpoints use a different, longer naming — clicks_by_country, clicks_by_device, by_time_of_the_day and so on. The error message lists the accepted values for whichever endpoint rejected you, so read it rather than assuming the two sets match.

Several at once

metrics is comma-separated. One query instead of four, which is the difference between a dashboard that loads and one that staggers.

Locked breakdowns

Location detail, technology and the UTM dimensions are plan features. On a plan without them you do not get an error — you get a well-formed response carrying sample data and a lock flag:
This is deliberate: a gated widget still has a shape to render behind a blur, and the server stays the source of truth for what is gated.
The rows alongside "locked": true are sample data, not your traffic. Always check the flag before displaying or storing figures. The flag appears on both the payload and the nested analytics object, because callers commonly keep only the inner one.
Batch calls partition rather than refuse: allowed dimensions come back with real numbers, gated ones come back locked, in the same response.

Paginating a breakdown

current_page and per_page, with per_page defaulting low — 5 on most breakdown endpoints. Raise it deliberately:

Time series

granularity accepts minute, hour, day, month and year, though not every endpoint accepts all five — the campaign endpoints are narrower. Omit it and one is chosen from the width of your range, which is usually what you wanted. get_org_clicks_by_hour is a different question: clicks by hour of day, aggregated across the range, for finding when your audience is active rather than how traffic trended.

Beyond clicks

  • get_org_routing_analytics, get_campaign_routing_analytics, get_shortlink_routing_analytics — how routing rules resolved, and which rules are doing nothing
  • get_shortlink_password_attempts — attempts against a password-protected link, successful and not