Analytics API

Access consent analytics for your sites, including consent rates, daily trends, and geographic breakdowns.

Query Parameters

All analytics endpoints accept these query parameters:

Name	Type	Required	Default	Description
`period`	`string`	No	`30d`	Time range: 7d, 30d, 90d, or custom
`from`	`string`	No	-	Start date (YYYY-MM-DD). Required when period=custom
`to`	`string`	No	-	End date (YYYY-MM-DD). Required when period=custom

Endpoints

GET /api/v1/sites/:siteId/analytics Get analytics overview

Returns an aggregated overview and daily breakdown for the specified period. Rates are whole percentages (0-100), defined in How we count consent. Bot traffic is excluded from every count and reported in botEvents. The daily array contains one entry per day within the range, with raw counts.

Response

{
"period": "30d",
"overview": {
  "totalImpressions": 15420,
  "decisions": 3980,
  "lowSample": false,
  "consentRate": 72,
  "acceptAllRate": 58,
  "rejectAllRate": 28,
  "customRate": 14,
  "noChoiceRate": 74,
  "gpcAutoOptouts": 12,
  "botEvents": 2310,
  "botShare": 12,
  "categoryRates": {
    "analytics": 65,
    "marketing": 60,
    "functional": 66
  }
},
"previousPeriod": { "...": "same fields as overview" },
"liveSince": "2026-09-29",
"baseline": { "rate": 54, "source": "Cookiebot", "setAt": "2026-10-11 10:00:00" },
"daily": [
  {
    "date": "2026-01-18",
    "impressions": 512,
    "accept_all": 298,
    "reject_all": 143,
    "custom_consent": 71,
    "custom_none": 9,
    "analytics_granted": 340,
    "marketing_granted": 311,
    "functional_granted": 352,
    "gpc_auto_optout": 0,
    "bot_events": 48
  }
]
}

GET /api/v1/sites/:siteId/analytics/geo Get geographic breakdown

Returns consent metrics broken down by country (ISO 3166-1 alpha-2 codes). Up to 50 countries, sorted by impressions descending. consentRate is null when a country has fewer than 20 decisions in the period.

Response

{
"period": "30d",
"countries": [
  {
    "country": "DE",
    "impressions": 3240,
    "decisions": 812,
    "acceptAll": 470,
    "rejectAll": 243,
    "customConsent": 99,
    "consentRate": 69,
    "botEvents": 41
  },
  {
    "country": "US",
    "impressions": 2180,
    "decisions": 6,
    "acceptAll": 4,
    "rejectAll": 2,
    "customConsent": 0,
    "consentRate": null,
    "botEvents": 1390
  }
]
}

GET /api/v1/sites/:siteId/analytics/breakdown?dimension=device Consent rate by device, banner version or page

dimension is device, version (banner version, newest first) or page (top 25 normalised paths). consentRate is null under 20 decisions. Requires the Basic plan or higher; lower plans get 403 plan_limit.

Response

{
"period": "30d",
"dimension": "device",
"items": [
  { "value": "mobile", "impressions": 8120, "decisions": 2210, "consentRate": 74, "acceptAllRate": 70, "rejectAllRate": 22, "noChoiceRate": 73 },
  { "value": "desktop", "impressions": 6950, "decisions": 1690, "consentRate": 66, "acceptAllRate": 61, "rejectAllRate": 30, "noChoiceRate": 76 },
  { "value": "tablet", "impressions": 350, "decisions": 12, "consentRate": null, "acceptAllRate": 67, "rejectAllRate": 33, "noChoiceRate": 97 }
]
}

PUT /api/v1/sites/:siteId/analytics/baseline Set the consent rate of your previous CMP

Body: { "rate": 54, "source": "Cookiebot" }, where rate is 0–100 and source is 1–60 characters. It is returned as baseline in the analytics overview, next to liveSince (the first day with real banner traffic), so the dashboard can show before and after. DELETE on the same path removes it. Requires the admin or owner role.

Response

{ "baseline": { "rate": 54, "source": "Cookiebot" } }

GET /api/v1/sites/:siteId/analytics/export Export analytics as CSV

Returns daily analytics as a CSV file. The response Content-Type is text/csv with a Content-Disposition header for download.

Response

date,impressions,accept_all,reject_all,custom_consent,decisions,consent_rate,analytics_rate,marketing_rate,functional_rate,no_choice_rate,gpc_auto_optout,bot_events
2026-01-18,1200,298,143,71,512,70,66,61,69,57,0,48
2026-01-19,1130,284,136,67,487,71,66,60,70,57,0,31

Example: custom date range

curl "https://api.cookieboss.io/api/v1/sites/$SITE_ID/analytics?period=custom&from=2026-01-01&to=2026-01-31" \
  -H "Authorization: Bearer $TOKEN"

Maximum range

Custom date ranges cannot exceed 365 days. Requests with longer ranges return a 400 error.