Answer an analytics question
Reads one of seven analytics surfaces through the same authorized query service the dashboard and the MCP query_analytics tool use: overview, one link's detail, a breakdown of one dimension (explore), a comparison of 2-5 links (change), and the analytics page's own signals, summary (KPIs, headline sentence, top movers, spike flag), trend (the chart series by hour, day or week with the previous period aligned bucket by bucket) and leaderboard (links by change, new links, active links with no taps). Requires an API key with the analytics:read or links:read scope. SDK keys are refused. Retention, the Free plan's 30-day look-back and the Free click-limit freeze apply exactly as on the dashboard. A Free range, or a comparison whose earlier period, that starts before the last 30 days is refused with 403 LOOKBACK_EXCEEDED, and details.earliest_allowed carries the first instant a Free organization may read. A Free organization at its 10,000-click limit still reads: figures stop at the moment the limit was reached, receipt.paused is { reached_at, limit }, window_effective.until is one millisecond after that moment (or at it, when another click shares that millisecond, and then the clicks in that millisecond are left out), and a warning says so. Clicks keep being stored, and a new billing period reads live again. Reports accepted_taps, unique_clicks, installs (observed_attributed_installs, or linked_installs when a filter or own_links scope narrows the view) and, on summary and trend, tap_to_install_rate and app_open_share as numerator and denominator. Days, weeks and hours are labeled in the organization's reporting time zone unless timezone is sent. metrics optionally narrows the response to a subset of a surface's own metrics. app_id filters every surface to links of one app in the org. On the overview surface the rows also carry the top countries, referrers and devices, idle links, recent clicks and the previous-period comparison row, and attempt_match_rate is reported with an additive tap_found object ({ numerator, denominator, display, status }): the match rate among new installs where a tap was found, with status healthy (80% or more), needs_attention (50% to under 80%), low (under 50%), or not_enough_installs (fewer than 50 such installs); on the link surface the tap-source split; on change the per-compared-link breakdowns. A parameter not applicable to the chosen surface, and any unrecognized query parameter, is a 400 VALIDATION_ERROR. A parameter other than filter sent more than once is also a 400 VALIDATION_ERROR, and so is org: the API key's own organization is always the one queried. On the leaderboard surface, insight.silent_through and insight.silent_state say whether silence can be claimed for the silent tab. A sparkline point that cannot be computed, such as a rate with no denominator, is null.
Request
- Base URL: https://api.warplink.app/v1
- URL: https://api.warplink.app/v1/analytics
- Auth: HTTP bearer
Query parameters
Which question to answer.
A relative window. Omit and pass from/to instead for an explicit range.
Start of an explicit window, inclusive. Required together with to when window_preset is omitted.
End of an explicit window, exclusive.
IANA timezone that labels every day, week and hour and resolves this_month/previous_month. Defaults to the organization's reporting time zone (Settings), else UTC.
Required when surface=link.
Comma-separated link ids (2-5 distinct). Required when surface=change.
Required when surface=explore, unless dimensions is sent. Exactly one dimension name. Send dimension or dimensions, not both.
Required when surface=explore, unless dimension is sent. Exactly one dimension name; the plural form is the canonical shape but only one value is accepted today. Send dimension or dimensions, not both.
Comma-separated subset of the surface's own metric list (e.g. metrics=accepted_taps,unique_clicks). Omit for every metric the surface reports. A name outside the surface's own list is a 400 VALIDATION_ERROR.
Repeatable filter, one token per value. Two spellings are accepted. Plain, dimension:value (filter=country:US): an empty value (country:) selects Unknown, repeating the parameter for one dimension matches any of its values (filter=country:US&filter=country:DE, at most 25 values per dimension), and different dimensions combine with AND. Typed, dimension:operator[:payload]: eq (filter=country:eq:US, the value after the second colon is taken exactly as given, including any further colons, commas or percent signs, e.g. filter=utm_source:eq:partner:summer keeps the whole value 'partner:summer'), is_unknown (filter=country:is_unknown, no payload) and in (a true OR of 2-5 comma-separated values, filter=utm_source:in:google,bing; a value that itself contains a comma, colon, percent sign or non-ASCII text must be percent-encoded with encodeURIComponent before joining the list, e.g. filter=utm_source:in:a%2Cb,plain for the two values 'a,b' and 'plain'; a malformed percent-escape is a 400 VALIDATION_ERROR, never silently dropped or truncated). A token whose second segment is a valid typed operator reads as typed. At most one in filter per request, and none together with compare. Accepted on explore, summary, trend and leaderboard.
Three states. Omit for every link regardless of app (unfiltered, the default). A UUID filters every surface to links of that one app in the org (404 if the app does not exist in this org). The literal string "none" selects only links with no app at all. On summary, trend and leaderboard it is the same as a filter on the app dimension, so it cannot be sent together with one.
Also read the equal-length period just before (previous, or true) or not (none, or false). Defaults to previous on summary, trend and leaderboard and to none on explore. Not accepted on overview, link and change.
summary, trend, leaderboard, and explore with row_series=true. Chart bucket size. hour needs a window of at most 7 days, week at least 14 days; day always works. A refused choice is a 400 INVALID_GRANULARITY naming the limit. Defaults to day.
trend only. The KPI the caller is asking about, echoed in the response. Every metric is returned on every row.
leaderboard only. movers lists links by change, new lists links created in the window, silent lists active links with no taps under the same filters. Defaults to movers.
explore only. Literal text matched against a row's value or app name; % and _ are ordinary characters. With limit it also sets how many named rows are listed.
explore only. Add each row's share of the scan, previous count, change and sparkline.
An opaque cursor from a prior response. Reauthorized against the current request; a stale or mismatched cursor is refused.
Page size.
Response
The query result: schema_version, the query receipt, totals/units, rows, and next_cursor
Changes
No recorded changes to this operation across all 1 revision of this API.