---
name: badgerlytics-reports
description: Answer analytics questions with the Badgerlytics Reports MCP server (traffic, pages, events, funnels, revenue, SaaS metrics, A/B tests). Use when the user asks about website or product performance, conversions, experiments, or anything tracked in Badgerlytics.
---

# Badgerlytics Reports

The `badgerlytics-reports` MCP server is read-only. It returns summary reports for the properties (websites/apps) in one Badgerlytics organization.

## Never handle the API key

- The key is already configured in the MCP client. Never ask the user for it, never print it, never pass it as a tool argument (calls containing a key are rejected).
- If tools fail with an authentication error, tell the user to check the `BADGERLYTICS_API_KEY` environment variable and restart their tool. See https://badgerlytics.com/docs#mcp.
- If the server replies that the key isn't allowed on it, the key is missing the **Reports (MCP)** scope. Scopes are fixed when a key is created, so the user needs a new key from Settings → API Keys.

## Find the organization and property first

1. The connection instructions list the organization ID and its properties. If you don't have them, call `whoami` and `list_properties` (both are lookups, which have a looser rate limit).
2. Every other tool needs **both** `organizationId` and `propertyId` (short IDs like `Xq7aB2kLmP`). Reuse them; don't call discovery tools repeatedly.
3. If the user names a site, match it against property names and domains. If more than one could match, ask which one.
4. Prefer the production property unless the user asks about a test or dev environment.

## Pick the right report

| Question | Tool |
| --- | --- |
| Overall traffic, sessions, conversion, revenue | `website_performance` |
| Last 24 hours, hour by hour | `website_performance` with `granularity: "hourly"` |
| Top pages, landing pages, exit pages | `page_performance`, `exit_pages` |
| Where visitors come from | `referrer_utm_performance`, `country_performance`, `location_performance` |
| Devices, browsers, operating systems | `device_performance_comprehensive`, `browser_usage`, `os_usage` |
| A custom event (sign-ups, clicks, form submits) | `list_custom_events`, then `custom_events` with `event_name` |
| A funnel's step-by-step drop-off | `list_funnels`, then `conversion_funnel` with `funnel_name` |
| What's costing conversions (errors, rage clicks, slow pages) | `impact_quantification` |
| Revenue, products, categories, carts | `revenue_comprehensive`, `product_performance`, `category_revenue_performance`, `product_view_performance`, `cart_abandonment` |
| SaaS: MRR, usage revenue, retention, churn | `mrr_performance`, `usage_revenue`, `cohort_retention`, `subscription_lifecycle`, `cancellation_reasons` (SaaS properties only) |
| A/B test results | `list_feature_flags`, then `test_summary`, `variant_enrollment_vs_exposure`, `focus_page_analysis` |

`list_feature_flags` returns **running** flags only unless you ask for more: pass `status: "draft"` or `"stopped"` for one other state, `status: "all"` for every unarchived flag, `test_token` for a single flag, or `include_archived: true` to include archived ones.

Read each tool's description for its exact arguments before calling it.

## Limits (plan around them)

- **Summaries only.** Reports return totals for the date range. The only time series is `website_performance` hourly (last 24 hours).
- **Dates:** `startDate`/`endDate` as `YYYY-MM-DD`, at most 90 days. Default is the last 30 days. Dates are in the property's reporting time zone.
- **Rows:** 25 by default, `limit` up to 50. Use `sort_by` for a top-N list or `page` to go further; don't combine them.
- **`impact_quantification`** uses `lookback_days` of `"7"` or `"30"`.
- **`test_summary`** takes test tokens, or covers all running tests when none are given.
- **Rate limit:** per organization, per server, per minute — 20 report calls and 50 lookups (`whoami`, `list_*`). Shared by everyone on the team, so plan your calls and don't loop over many properties or dates. If you're told to wait, wait the seconds given before retrying.
- **Each call gets 15 seconds.** If one times out, narrow the date range or lower `limit` rather than retrying it unchanged.
- To compare periods, run the same report twice (current and previous range) rather than one long range.

## Answering well

- State the property, date range and time zone you used.
- Lead with the answer, then the supporting numbers. Note small sample sizes.
- Distinguish correlation from causation, especially for A/B tests that are still running.
- If a report errors, read the message. It says what to change (missing argument, range too long, SaaS-only report, and so on). Fix it and retry once.