Terminal
Terminal/Skill
Charts GrowthBook product data, builds dashboards, manages the metric catalog, and runs ad-hoc SQL against your warehouse.
By GrowthBook
Works with
npx skills add growthbook/skills --skill analyticsDomain router for GrowthBook Product Analytics, Analytics dashboards, and the metric catalog. The workflows live in references/. Read this router, pick one, then read that file and follow it.
Analytics uses the v1 API — /api/v1/product-analytics/search, /columns, and /column-values for discovery, the metric, fact-table, data-source, and funnel /api/v1/product-analytics/*-exploration endpoints for charts, /api/v1/product-analytics/explorations/:id for polling, /dashboards for saved pages of charts (except create, which is POST /api/v2/dashboards; the v1 create is deprecated), and /fact-metrics and /fact-tables for the catalog. The API also exposes SQL explorations, but this skill does not construct or execute arbitrary SQL exploration payloads.
All API calls go through the bundled helper. Under the Claude Code plugin install, it lives at ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call (the plugin root). Under npx skills install, it lives at scripts/gb-call relative to this skill's directory. Resolve that path once and substitute it whenever a reference example says gb-call; do not assume gb-call is on PATH. It reads GB_API_KEY from the environment first, then falls back to ~/.config/growthbook/.env (written by gb-setup); environment variables take precedence.
When a workflow needs to construct a GrowthBook UI link from a root-relative path, a shell-capable runtime should call gb-call app-origin once per conversation, retain the returned trusted origin across workflow and domain handoffs, and prepend it to each path. If the origin is already in context, reuse it; do not call the command once per link. Embedded or MCP adapters that already know their trusted app origin may resolve paths directly. Never derive an app origin from GB_API_URL; if app-origin refuses because self-hosted configuration is incomplete, route to gb-setup. API-returned explorationUrl values are already complete and must be used unchanged.
| Read this | When the user wants to |
|---|---|
references/metric-search.md | Browse, find, or audit metrics and fact tables — inventory, a specific definition, or "what can I chart" triage (read-only) |
references/metric-create.md | Create a fact metric, creating its underlying fact table first when necessary (writes configuration) |
references/analytics-explore.md | Actually run a chart and report the numbers plus a deep link |
references/dashboard-create.md | Build a new dashboard — several charts saved together on one page (writes a dashboard) |
references/dashboard-edit.md | Change a dashboard that already exists: add or remove a chart, swap a metric, change the timeframe, rename it |
references/sql-query.md | Run ad-hoc SQL against the warehouse when no metric or exploration can answer the question (last resort) |
When the user names a metric you have not resolved yet, read metric-search.md first. It hands analytics-explore or metric-create a stable definition. When they already named something concrete and just want the numbers, go straight to analytics-explore.md.
One chart or several? A single question gets one chart from analytics-explore. "Track", "monitor", "reporting", or two or more things to watch together means a dashboard. Route on whether the dashboard exists: no id yet is dashboard-create, an id is dashboard-edit.
Use sql-query.md only when the question can't be answered with existing metrics or the exploration config — custom joins, unmodeled tables, or aggregations the exploration can't express.
fact__... ids work in Product Analytics; legacy met_... metrics from /api/v1/metrics are valid experiment metrics but cannot be charted. Never promise a chart for one.fact__; fact table ids default to ftb_... but can be custom, so don't filter on that prefix.@ mention — never construct one. Some are readable (fact__demo-d7-purchase-retention) and invite a guess like fact__AverageOrderValue; those resolve to nothing, and the failure surfaces late and obscurely.official: true metric over adding a duplicate with the same meaning.200 from an exploration POST is not necessarily success. Branch on exploration.status; poll running explorations by id, surface error, and note that cache=required can return exploration: null./product-analytics/search means the server predates these endpoints. On /columns, /column-values, or /explorations/:id, it can also mean the resource is missing or inaccessible. Surface the failure and stop; never probe around access checks, substitute an undocumented endpoint, or re-POST a running exploration.unit explicitly on every dataset.values[] entry — that is the only level that takes one; a unit on the config itself is rejected. For metrics, follow /columns exactly: when metrics[].needsUnit is true, choose a returned userIdTypes entry; when it is false, default to null. A unit is an identifier type, never a value format such as currency. The server does not backfill a missing unit.predefined is a closed list, everywhere one appears: today, yesterday, last7Days, last30Days, last90Days, last12Months, lastCalendarYear, customLookback, customDateRange. Any other name is rejected, so every window outside the list is customLookback with lookbackValue and lookbackUnit (hour, day, week, month).dimensionType is a closed set, and "dimension" is not in it: date, dynamic, static, slice. Only the first two are supported — a date axis is { "dimensionType": "date", "column": null, "dateGranularity": "auto" } and a breakdown by column is { "dimensionType": "dynamic", "column": "browser", "maxValues": 5 }. Naming the field after what you want to group by is the guess the validator rejects.body.message, fix exactly what it names, and send it once more. If the message does not say what a valid value would be, or the same field is rejected twice, stop there — say which field failed and what you tried, and ask the user rather than guessing a third time. Ask about that field: a validation error names the field it rejected, and a question about a different one (a column name, a metric choice) cannot resolve it, so the answer arrives and the same call fails again.chartType, so a different chart type on the same query is a cache hit. Never re-query just to restyle.config, not a result. The create and update calls run every chart server-side, so never POST an exploration first just to get an id for a tile.{ "id": "dshblk_…" } rather than copying it back in full, and list each id at most once.owner changes only when the user asks. Create on POST /api/v2/dashboards without owner, which defaults to the API key's user, unless the user names someone else. Never put owner or ownerEmail in an update body unless the user asked to reassign the dashboard. For an admin, a stray owner silently hands the dashboard to someone else.metric-search is strictly read-only. analytics-explore runs warehouse queries but changes no GrowthBook configuration — it does not create metrics, fact tables, or dashboards. sql-query is similar: it never mutates warehouse data, but it executes potentially costly queries and persists a GrowthBook exploration object from the results. metric-create writes organization-visible fact-table and fact-metric definitions, and dashboard-create / dashboard-edit write dashboards; all three must summarize the change in plain language and get confirmation before each write.
Note that explorations execute real warehouse queries, so they cost the user money and time even though they write nothing — and a dashboard write runs one per chart block. Scope them the way the reference files describe rather than fanning out speculatively.
gb-call reports a missing or invalid GB_API_KEY.