metric-search

metric-search

Search, list, and audit GrowthBook metrics and fact tables. Three jobs share this skill: inventory ("what do we have?"), lookup ("find the revenue metric and show me its definition"), and chartability triage ("what can I actually explore?"). It is the discovery front door for analytics-explore and experiment-design.

Read-only — this skill never writes.

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. It expects GB_API_KEY in env.

Workflow

Pick the path that matches the user's request.

Path A — Inventory ("what metrics / fact tables do we have?")

There is no search endpoint; list and filter client-side.

gb-call GET '/api/v1/fact-metrics?limit=100'
gb-call GET '/api/v1/fact-tables?limit=100'

Both paginate with limit/offset (loop while hasMore is true) and accept datasourceId and projectId filters; /fact-metrics also accepts factTableId. Scope to a datasource when the user is heading toward charting — explorations are datasource-scoped.

Present the inventory grouped by fact table (metrics hang off their numerator.factTableId), with each metric's metricType and a one-line description. Flag managedBy: "admin" entries as official — vetted definitions the org manages centrally; prefer them when several similar metrics exist.

For completeness on older orgs, legacy metrics live at:

gb-call GET '/api/v1/metrics?limit=100'

List them separately and label them: legacy metrics work in experiments but cannot be charted in Product Analytics — only fact metrics can.

Path B — Lookup and detail ("find the revenue metric", "what's in the orders fact table?")

Fetch the list (Path A) and match client-side by name — matching is on your side, so try substrings and synonyms before declaring a miss ("purchase" for "order", "signup" for "registration").

Then pull the full definition:

gb-call GET /api/v1/fact-metrics/fact__abc123
gb-call GET /api/v1/fact-tables/ftb_abc123

Surface for a metric: metricType (mean, proportion, retention, dailyParticipation, ratio, quantile), numerator (fact table, column, aggregation, row filters), denominator (ratio metrics), inverse, and window/capping settings when they change interpretation. For a fact table: userIdTypes, sql, and columns[] — each column has column, datatype, deleted, and for string columns topValues (the observed values, refreshed by a background job).

Path C — Chartability triage ("what can I chart?", pre-analytics audit)

Answer three questions per candidate:

1. Is it a fact metric? Only fact__... IDs chart in Product Analytics. Legacy met_... metrics don't.
2. Is its datasource a SQL warehouse? Cross-check datasource against GET /api/v1/data-sources — Mixpanel and Google Analytics datasources can't run explorations.
3. Does mixing work? On one chart, ratio metrics can't mix with non-ratio metrics, and quantile metrics can't mix with anything. All other types mix freely.

Report the chartable set and hand off to analytics-explore to actually run one.

Guardrails

• Read-only. Never POST, PUT, or DELETE from this skill. Route chart-running to analytics-explore and metric creation to the GrowthBook UI.
• There is no server-side search. /fact-metrics and /fact-tables have no name/query param — fetch and filter client-side. On large orgs paginate the full set first (100 per page), and mind the 60 rpm rate limit.
• "Official" is managedBy: "admin". There is no official field on the API response — the Official badge in the GrowthBook UI corresponds to managedBy: "admin". "api" means managed by API automation; "" means anyone can edit it in the UI.
• Legacy metrics are not chartable. /api/v1/metrics entries work as experiment metrics but Product Analytics explorations only accept fact metrics. Don't promise a chart for one.
• Ignore deleted: true columns on fact tables — they're soft-deleted leftovers from schema refreshes and can't be used in values, filters, or dimensions.
• topValues can be stale or absent. It's populated by a background job for string columns only. Treat it as a hint at what values exist, not a complete or current enumeration.
• IDs are stable handles; names aren't unique. When handing off to analytics-explore or experiment-design, pass the id, not the display name. Fact metric IDs always start fact__; fact table IDs default to ftb_... but can be custom (API-created tables often are), so don't filter by prefix.

Endpoints used

• GET /api/v1/fact-metrics — paginated fact metric list (datasourceId, factTableId, projectId, limit, offset)
• GET /api/v1/fact-metrics/:id — full metric definition
• GET /api/v1/fact-tables — paginated fact table list (datasourceId, projectId, limit, offset)
• GET /api/v1/fact-tables/:id — columns, userIdTypes, topValues, SQL
• GET /api/v1/metrics — legacy metrics, listed for completeness only
• GET /api/v1/data-sources — datasource types for chartability triage
• GET /api/v1/projects — resolve project name to ID for project-scoped listings

Handoffs

• analytics-explore — to chart a metric or fact table found here
• experiment-design — to pick goal/guardrail metrics for a new experiment
• experiment-analyze — when the user's question is about an experiment's metric results, not the metric catalog