get_earnings_report

Full earnings report — totals plus a day, week, or month timeseries. Accepts explicit from/to dates or period presets.

Purpose

Return a full earnings report for the creator — totals (gross, fees, net, transactions) plus a timeseries bucketed by day, week, or month. Accepts period presets or explicit from / to ISO dates; if both are supplied, the explicit dates win.

Required ability

dashboard:read

Input schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Optional project UUID to scope the report. 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'."
    },
    "granularity": {
      "type": "string",
      "description": "Timeseries bucket size — day, week, month. Defaults to day."
    },
    "plan_ids": {
      "type": "array",
      "description": "Optional plan-UUID allow-list."
    },
    "statuses": {
      "type": "array",
      "description": "Optional SubscriptionStatus allow-list applied to parent subscriptions."
    },
    "payment_method_ids": {
      "type": "array",
      "description": "Optional payment-method UUID allow-list applied to parent subscriptions."
    }
  }
}

Output shape

{
  "data": {
    "totals": {
      "gross": "4821.50",
      "fees": "193.27",
      "net": "4628.23",
      "transactions": 184
    },
    "timeseries": [
      {
        "bucket": "2026-03-22",
        "gross": "145.00",
        "net": "139.20",
        "transactions": 6
      }
    ]
  },
  "meta": {
    "period": "30d",
    "granularity": "day"
  }
}

Example prompts

"Show weekly earnings year-to-date across all projects."

"What's the total revenue for project prj_01HX... from 2026-01-01 to 2026-03-31, broken down by month?"

Failure modes

VALIDATION_FAILED — granularity is not one of day, week, month.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks dashboard:read.