# Analytics

`GET /v1/analytics` reads one of seven surfaces through the same authorized query service behind the dashboard's Analytics page and the MCP `query_analytics` tool. A REST call and an MCP call with the same input return identical numbers. The dashboard's breakdown grid is the one exception: a filtered card keeps every value of its own dimension visible instead of narrowing it, so a chosen row never hides its siblings, and its rows can differ from the same filter sent to REST or MCP.

## Authentication and Permissions

Requires an API key with the `analytics:read` or `links:read` scope. SDK keys are refused. Retention and the Free plan limits apply exactly as they do on the dashboard. A window outside your plan's retention comes back as a named state rather than a silent zero. A Free organization reads the last 30 days: a range, or a comparison period, that starts earlier is refused with `403 LOOKBACK_EXCEEDED`, and `details.earliest_allowed` is the first instant it may read. A Free organization at its 10,000-click limit still reads, with figures that stop at the moment the limit was reached: the receipt carries `paused` as `{ 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.

## Surfaces

| `surface` | Answers |
|-----------|---------|
| `overview` | Organization-wide totals for a window |
| `link` | One link's detail (`link_id` required) |
| `explore` | A single-dimension breakdown, with optional `filter` and `compare` |
| `change` | A comparison of 2 to 5 links (`link_ids` required) |
| `summary` | The key numbers (clicks, unique clicks, installs, click to install rate, app open share) with change and sparkline, the headline sentence, the top movers, and a spike flag |
| `trend` | The chart series by `granularity` (`hour`, `day`, or `week`), with the previous period aligned bucket by bucket |
| `leaderboard` | Links by change (`tab=movers`), links created in the window (`tab=new`), or active links with no taps (`tab=silent`) |

A parameter that does not apply to the chosen surface, and any unrecognized query parameter, returns `400 VALIDATION_ERROR`.

## Query Analytics

GET /analytics: Answer an analytics question

The window is either a relative `window_preset` (`last_7_days`, `last_30_days`, `this_month`, `previous_month`) or an explicit `from`/`to` range; sending both is a `400`. `dimension` is required on `surface=explore` (`country`, `device`, `os`, `browser`, `referrer`, `utm_source`, `source`, `app`, or `ai_assistant`). `filter` is repeatable and only accepted on `surface=explore`, as `dimension:value` (an empty value, `country:`, selects Unknown). `compare=true` on `surface=explore` also reads the equal-length period immediately before the window.

`timezone` is an IANA zone (for example `America/New_York`). It labels every day, week, and hour, and resolves the calendar boundaries of `this_month` and `previous_month`. It defaults to the organization's reporting time zone, set in Settings. `filter` is repeatable (`filter=country:US&filter=country:DE`): values of one dimension match any, up to 25 per dimension, and different dimensions must all match. `compare` defaults to `previous` on `summary`, `trend`, and `leaderboard`; send `compare=none` to turn it off. Hourly buckets need a window of at most 7 days, and weekly buckets at least 14 days.

The response reports `accepted_taps`, `unique_clicks`, and installs: `observed_attributed_installs`, or `linked_installs` when a filter or a member's own-links scope narrows the view. `tap_to_install_rate` and `app_open_share` are returned as a numerator and a denominator, never as a rounded percent. A value outside retention is reported as a named state rather than a plain number, the same way the dashboard shows it.

On the `overview` surface, `attempt_match_rate` is the share of eligible attribution requests from new installs that were tied to a link. Installs from an app in [routing-only mode](https://warplink.app/docs/trust/attribution-accuracy#routing-only-mode) that were not matched are left out of the rate, because the app chose not to match them. It carries an additive `tap_found` object with `numerator`, `denominator`, `display`, and `status`: the match rate among new installs where a tap was found, with `healthy` at 80% or more, `needs_attention` from 50% to under 80%, `low` under 50%, and `not_enough_installs` while fewer than 50 such installs are counted.

## Referral Scope

`source` is a top-level parameter on the page surfaces (`summary`, `trend`, and `leaderboard`): `all` (the default) reads every link, and `referrals` reads taps from referral links only. It is separate from the `source` dimension above, which groups taps by their tap source. With `source=referrals` the response also carries a `referral` object with two fields. `funnel` holds `taps`, `installs`, and `claims`. Each step has `value`, `change` (the same `state`, `current`, `previous`, `delta`, and `ratio` as the key numbers), and `share_of_previous` (a `numerator` and `denominator` against the step before, or `null` for taps and when that step is zero). `totals` holds `referrals`, `delivered`, and `need_attention` for the same window. Taps are redirects through referral links: link opens from the installed app, replays, and tester traffic are left out of the funnel. The MCP `query_analytics` tool takes the same `source` input and returns the same fields.

## AI Assistant Traffic

The `ai_assistant` dimension groups clicks by the AI assistant that sent the visitor. A click belongs to an assistant when its referrer host matches the assistant's host, or a subdomain of it. When the referrer matches nothing, the click's `utm_source` is compared, ignoring case, with the assistant's known values. A click that no assistant matches is Unknown, shown as "Not from an AI assistant" in the dashboard. The classification runs when you read, over the same clicks and under the same retention, look-back, and click-limit rules as every other dimension, so adding an assistant never changes stored data.

| Value | Assistant | Referrer hosts |
|-------|-----------|----------------|
| `chatgpt` | ChatGPT | `chatgpt.com`, `chat.openai.com` |
| `perplexity` | Perplexity | `perplexity.ai` |
| `claude` | Claude | `claude.ai` |
| `gemini` | Gemini | `gemini.google.com`, `bard.google.com` |
| `copilot` | Copilot | `copilot.microsoft.com` |
| `meta_ai` | Meta AI | `meta.ai` |
| `grok` | Grok | `grok.com` |
| `deepseek` | DeepSeek | `chat.deepseek.com` |
| `le_chat` | Le Chat | `chat.mistral.ai` |
| `you` | You.com | `you.com` |
| `phind` | Phind | `phind.com` |

Use the value as a filter on the surfaces that take filters: `filter=ai_assistant:chatgpt`, or `filter=ai_assistant:chatgpt&filter=ai_assistant:claude` for either. `filter=ai_assistant:` with no value, or `filter=ai_assistant:is_unknown`, selects the clicks no assistant sent. A value that is not an assistant id returns `400 VALIDATION_ERROR`. The MCP `query_analytics` tool takes the same dimension and filter. To export only those clicks, send `ai_assistant` to [`POST /v1/exports`](https://warplink.app/docs/api/exports).

## Worked Example

```bash
curl "https://api.warplink.app/v1/analytics?surface=explore&window_preset=last_30_days&dimension=country&compare=true" \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY"
```

Which AI assistants sent clicks in the last 30 days:

```bash
curl "https://api.warplink.app/v1/analytics?surface=explore&window_preset=last_30_days&dimension=ai_assistant" \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY"
```

Comparing two links over the same window:

```bash
curl "https://api.warplink.app/v1/analytics?surface=change&link_ids=LINK_ID_1,LINK_ID_2&window_preset=last_7_days" \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY"
```

For a full CSV of raw click rows instead of an aggregated answer, see [Exports](https://warplink.app/docs/api/exports).
