Stats API

Your key

It uses the same keys as your agent. Create one at Agent access → My client can't sign in → use a token instead → Create a token. A key limited to some apps only sees those apps; revoke it there and it stops working right away.

curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats?app=yourapp.com&range=7d"

Totals

GET /api/v1/stats: visitors, visits, pageviews, bounce rate and visit time for the range, next to the previous period of the same length, plus revenue from your connected payment provider.

curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats?app=yourapp.com&range=30d"

{
  "app": "yourapp-com",
  "period": { "from": "2026-10-04T…", "to": "2026-11-03T…", "range": "30d", "label": "Last 30 days", "bucket": "day" },
  "filters": {},
  "results": { "visitors": 6685, "visits": 8120, "pageviews": 14211, "bounce_rate": 0.4312, "visit_duration_seconds": 96, "views_per_visit": 1.75 },
  "previous": { "period": { … }, "results": { "visitors": 2731, … } },
  "revenue": { "amounts": { "usd": 1240 }, "customers": 31, "payments": 38, "attributed_only": false }
}

Time series

GET /api/v1/stats/timeseries: visitors and pageviews per hour (24 hours and shorter), per day, or per month (over 6 months), in your timezone. Quiet periods come back as zero.

curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats/timeseries?app=yourapp.com&range=7d"

{ "results": [ { "period": "2026-10-28", "visitors": 412, "pageviews": 731 }, … ], "timezone": "Europe/Paris", … }

Breakdowns

GET /api/v1/stats/breakdown?by=…: the top rows of one report, with visitors and their share of all visitors.

• by: page, entry, exit, source, channel, campaign, country, region, city, device, browser, os, language, goal, outbound.
• limit: 1 to 1000, default 20.

curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats/breakdown?app=yourapp.com&by=source&range=30d&limit=5"

{ "by": "source", "results": [ { "source": "news.ycombinator.com", "visitors": 1820, "visits": 1904, "share": 0.2722 }, … ] }

Ranges and filters

• range: today, 24h, 7d (default), 30d, 90d, 6m, 12m, 2y, or range=custom&from=2026-09-01&to=2026-09-30 (whole days, up to about 2 years). Ranges stop at what your plan keeps: 6 months on Starter, 1 year on Builder, 2 years on Pro.
• Filters: any report as a filter, the same as on the dashboard: country=DE, source=news.ycombinator.com, page=/pricing, device=mobile, goal=signup… Filters work on the last 90 days: a filtered range that starts earlier is shortened to 90 days, and period in the response shows the dates used.
• tz: an IANA timezone like America/New_York. Defaults to yours.

curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats/breakdown?app=yourapp.com&by=page&country=DE&device=mobile"

Errors and limits

Errors come back as JSON with an error in plain words and often a hint: 401 for a missing or revoked key, 404 for an app the key can't see, 400 for an unknown range or report.

Up to 120 requests a minute per key; above that you get 429 with how long to wait. Numbers are the same ones the dashboard shows, bots already left out.

CSV and history

Every report also downloads as CSV: Export on an app's analytics dashboard, for the range and filters on screen.

Coming from Plausible or Umami? Bring your history on the same page. The export is read in your browser, and only daily totals are kept; those days show up before your BugOtter data starts, never on top of it.

Common questions

I get 401

The Authorization header is missing, the key is mistyped, or it was revoked. Send Authorization: Bearer bo_… with a key from Agent access.

I get 404 for my app

The key is limited to other apps, or the app name doesn't match. Use the app's domain (yourapp.com) or its slug from the app page address.

My filtered numbers only cover 90 days

Filters need single visits, which are kept 90 days. Unfiltered totals go back as far as your plan keeps.