---
title: "Aggregated affiliate click statistics"
method: GET
path: "/api/admin/affiliate-stats"
tags: ["admin-affiliate"]
---

# Aggregated affiliate click statistics

`GET /api/admin/affiliate-stats`

## Request

- Base URL: `https://voltplan.app`
- URL: `https://voltplan.app/api/admin/affiliate-stats`
- Auth: HTTP bearer

Aggregates every `component_click_events` record. Bot and crawler user agents (`isBotUserAgent`; a missing or empty `user_agent` counts as a bot) are removed first; their number is returned as `botEventsFiltered`.

- `today` counts since 00:00 UTC; `last7Days` and `last30Days` are rolling windows ending now.
- Country is `resolved_country` or `unknown`; source is `source` or `unknown`; app is the first `_`-separated part of the source when it is `voltplan`, `cable`, `blog` or `calculator`, otherwise `voltplan`.
- Components are grouped by the event's `component` id, or by `search:<name>` when the event has none. Name and type come from the event, else from the `components` record, else `Unknown` / `unknown`.
- `components` is sorted by `total` descending, with `Unknown` names last. The top-level totals and `byCountry`/`bySource`/`byApp` sum over all components.

## Response `200`

Click statistics.

- AdminAffiliateStats
  - `total` integer, required: All clicks.
  - `today` integer, required: Clicks since 00:00 UTC today.
  - `last7Days` integer, required: Clicks in the rolling 7 days ending now.
  - `last30Days` integer, required: Clicks in the rolling 30 days ending now.
  - `botEventsFiltered` integer, required: Click events dropped as bot or crawler traffic, including events without a `user_agent`.
  - `byCountry` AdminAffiliateRangeCountsByKey, required: Key (country, source or app) → click counts.
  - `bySource` AdminAffiliateRangeCountsByKey, required: Key (country, source or app) → click counts.
  - `byApp` AdminAffiliateRangeCountsByKey, required: Key (country, source or app) → click counts.
  - `components` AdminAffiliateComponentStats[], required
    - `id` string, required: Id of the `components` record, or `search:<name>` for clicks without a component.
    - `name` string, required: `Unknown` when neither the event nor the component has a name.
    - `type` string, required: `unknown` when neither the event nor the component has a type.
    - `total` integer, required: All clicks.
    - `today` integer, required: Clicks since 00:00 UTC today.
    - `last7Days` integer, required: Clicks in the rolling 7 days ending now.
    - `last30Days` integer, required: Clicks in the rolling 30 days ending now.
    - `byCountry` AdminAffiliateRangeCountsByKey, required: Key (country, source or app) → click counts.
    - `bySource` AdminAffiliateRangeCountsByKey, required: Key (country, source or app) → click counts.
    - `byApp` AdminAffiliateRangeCountsByKey, required: Key (country, source or app) → click counts.
    - `targetUrls` AdminAffiliateTargetUrlStatsByUrl, required: Clicked target URL → stats.

## Other responses

- `403`: Admin access required. Returned for a missing, invalid or expired bearer token as well as for a valid token whose user lacks `is_admin=true`; admin endpoints never answer 401.
- `500`: PocketBase error or admin credentials not configured.

---

[API](https://skmtc.dev/voltplan/apis/voltplan-api.md) · [All operations](https://skmtc.dev/voltplan/apis/voltplan-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voltplan/apis/voltplan-api/revisions/575b86a7af92?raw)