get_subscriber_analytics

Subscriber-centric analytics — new signups, cancellations, churn rate, trial conversion, and status distribution for a window.

Purpose

Return subscriber-centric analytics for the creator — new signups, cancellations, churn rate, trial-to-paid conversion, and a status-distribution snapshot. Accepts period presets or explicit from / to ISO dates.

Required ability

dashboard:read

Input schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Optional project UUID to scope the analytics. 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."
    },
    "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'."
    }
  }
}

Output shape

{
  "data": {
    "new_subscribers": 42,
    "canceled_subscribers": 7,
    "churn_rate_percent": 2.2,
    "trial_started": 15,
    "trial_converted": 11,
    "trial_to_paid_percent": 73.33,
    "status_distribution": {
      "active": 341,
      "trialing": 4,
      "canceled": 22
    }
  },
  "meta": { "period": "30d" }
}

Example prompts

"What's my churn rate this quarter?"

"Show the trial-to-paid conversion rate year-to-date for project prj_01HX...."

Failure modes

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