/understanding-billing-usage

name: understanding-billing-usage
description: >
  Explains PostHog billing usage and spend from the customer's visible Billing
  MCP tools. Use when the user asks why usage or spend is high, which product or
  project is driving usage, what a usage type means, how to reduce usage, what
  changed over time, why they got a usage change alert, or whether a spike/drop
  alert was real or noisy. Also use before product-specific analytics skills when
  the user names a billable PostHog product metric such as events, recordings,
  feature flag requests, exceptions, survey responses, synced rows, logs, AI
  events, AI credits, or Inbox credits. Starts from Billing usage/spend tools,
  then routes to customer-visible product MCP surfaces for deeper investigation.

Understanding billing usage

Use this skill for customer-facing "what am I using and why?" Billing usage workflows. The question may come from the Billing usage dashboard, a usage alert email, an AI chat prompt, or a user who noticed high usage, spend, a spike, or a drop.

The core rule:

> Billing tools explain what changed, when, and which project drove it. Product tools > explain why it happened.

If a prompt sounds like "why are my events high?" or "why did recordings/logs/AI credits increase?" and Billing tools are available, start here rather than jumping straight to the product-specific metric skill. Once the billable usage type, project, and window are known, hand off to the relevant product tools or skill for the root-cause drilldown.

This skill is not meant for broad invoice, plan, refund, contractual credit, subscription, or contract questions. Keep it focused on usage and spend behavior.

Available tools

| Tool | Purpose | | ------------------------------ | ----------------------------------------------------------------------- | | `posthog:billing-overview-get` | Org billing context, subscribed products, team names, and usage summary | | `posthog:billing-usage-get` | Time-series usage by day, usage type, and team | | `posthog:billing-spend-get` | Optional spend context when the user asks about dollars | | Product-specific MCP tools | Follow-up investigation inside the affected product/project |

Only use this skill when the Billing read tools above are available. If the user asks about Billing usage and those tools are not available, do not continue with this workflow; briefly say that Billing usage investigation is not enabled for this organization or MCP session. If a Billing tool is available but returns a permission error, explain that the MCP session needs Billing access from an org admin or owner rather than saying the feature is unavailable.

Some clients expose PostHog MCP tools through `mcp__posthog__exec` instead of direct `posthog:*` tool names. If the direct Billing tools are not visible, search for `billing`, inspect the relevant tool schema, and call the Billing tool through the dispatcher before deciding Billing usage investigation is unavailable.

Read `references/spike-alert-mechanics.md` when the prompt comes from a usage alert email or dashboard link and you need URL parameter or weekday/weekend baseline guidance.

Read `references/usage-type-routing.md` before doing product-specific drilldown.

Inputs to look for

The best input is a Billing usage dashboard URL, but the skill should also work from a product name, usage type, project, or date in a normal user prompt. Extract whatever is available:

• `usage_types`: JSON array of billing usage type identifiers, for example `["event_count_in_period"]`
• `date_to`: the end of the chart window, or the alert day for alert links
• `date_from`: the start of the chart window
• `interval`: normally `day`
• Product or usage type names from the dashboard, email copy, or prompt
• Project/team names or IDs if the user already has a suspected project

If the usage type is missing but the user named a product, map it to the closest billing usage type and say what you inferred. If the date range is missing, use the last 30 days and say so. Only ask for more context when the prompt is too vague to choose a product or time window.

Workflow

Step 1. Classify the question

Choose the smallest path that answers the user:

• High/current usage: identify the product, project, and current-period context.
• Spend question: include spend, but keep usage as the diagnostic source.
• Usage change: compare the changed period to a sensible baseline.
• Alert email: follow the usage-change path and apply the alert-specific rules below.
• Reduction question: identify the driver first, then suggest product-specific reductions.

Step 2. Recreate the Billing view

Call `posthog:billing-usage-get` using the dashboard or prompt parameters:

• `start_date`: `date_from`, or about 30 days before the suspected change
• `end_date`: `date_to`, the named date, or today if the user did not name a date
• `interval`: `day`
• `usage_types`: the parsed or inferred `usage_types`, or omit if the product is unclear
• `breakdowns`: `["type","team"]`

If the response shape makes the total hard to read, make a second call with `breakdowns: ["type"]`. Keep dashboard-linked investigations anchored on the provided date range unless you need a small extension to compare against the same weekday/weekend class.

Call `posthog:billing-overview-get` only when you need org context that usage time series cannot answer: plan state, limits, trials, entitlements, docs links, product names, or team name hints. Do not call it by default for simple spike/high-usage questions. Do not use `usage_summary` as the source of truth for the alert, because it only reflects the current billing period.

If the user asks about dollars, call `posthog:billing-spend-get` with the same date range and breakdowns. Treat spend as an estimate/attribution layer over