get_dashboard_metrics

Return headline dashboard metrics — MRR, active subscribers, churn, and plan-level breakdown — with a period-over-period comparison.

Purpose

Return headline dashboard metrics for the current creator: MRR, active subscribers, churn, and a plan-level breakdown. Delegates to the same analytics service that powers the Livewire dashboard, so responses ride the same 5-minute cache — agent calls warm the human-facing view and vice versa.

Required ability

dashboard:read

Input schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Optional project UUID to scope the metrics to. Leave blank for all projects in the current team."
    },
    "period": {
      "type": "string",
      "description": "Period preset — 7d, 14d, 30d, 60d, 90d, mtd, qtd, ytd, 1y, all. Defaults to 30d. Ignored when both from and to are supplied."
    },
    "from": {
      "type": "string",
      "description": "Explicit start date (ISO YYYY-MM-DD). Overrides period when paired with 'to'."
    },
    "to": {
      "type": "string",
      "description": "Explicit end date (ISO YYYY-MM-DD). Overrides period when paired with 'from'."
    },
    "compare_period": {
      "type": "string",
      "description": "Baseline to compare against — 'previous' (prior window) or 'none'. Defaults to 'previous'."
    },
    "plan_ids": {
      "type": "array",
      "description": "Optional plan-UUID allow-list."
    },
    "statuses": {
      "type": "array",
      "description": "Optional SubscriptionStatus allow-list."
    },
    "payment_method_ids": {
      "type": "array",
      "description": "Optional payment-method UUID allow-list."
    }
  }
}

Output shape

{
  "data": {
    "mrr": "5280.00",
    "active_subscribers": 182,
    "new_subscribers": 14,
    "churn_rate": 3.2,
    "by_plan": [{ "plan_id": "pln_01HX...", "name": "Premium", "active": 120 }]
  },
  "meta": {
    "period": "30d",
    "compare_period": "previous",
    "project_id": null
  }
}

Example prompts

"Show me MRR, active subscribers, and churn for the last 30 days across all my projects."

"Give me headline metrics month-to-date for project prj_01HX...."

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks dashboard:read.