{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mentio-dev/json-schema/mentio-dev-usage-breakdown-schema.json",
  "title": "UsageBreakdown",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mentio-dev-usage-api-openapi.yml#/components/schemas/UsageBreakdown",
  "type": "object",
  "properties": {
    "window": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "First day, YYYY-MM-DD, inclusive, UTC."
        },
        "to": {
          "type": "string",
          "description": "Last day, inclusive: today for a trailing window or the running month."
        },
        "days": {
          "type": "integer",
          "minimum": 0,
          "description": "Length of the window in days."
        },
        "keywordDaysFrom": {
          "type": [
            "string",
            "null"
          ],
          "description": "The first day of the window with a recorded keyword count, or null when there is none. Earlier days carry keywordDays: null."
        }
      },
      "required": [
        "from",
        "to",
        "days",
        "keywordDaysFrom"
      ],
      "description": "The window the report covers, in UTC days."
    },
    "by": {
      "type": "string",
      "enum": [
        "day",
        "platform",
        "keyword",
        "group"
      ],
      "description": "The dimension the rows are grouped by."
    },
    "filtered": {
      "type": "boolean",
      "description": "true when keywordIds, groupIds or platforms narrowed the report: totals and rows count only what passes them, except totals.ledgerDebitCents, which is the whole workspace's."
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD"
      ],
      "description": "Every amount is in USD cents."
    },
    "totals": {
      "type": "object",
      "properties": {
        "keywordDays": {
          "type": "integer",
          "minimum": 0,
          "description": "Keyword-days metered in the window."
        },
        "keywordCents": {
          "type": "integer",
          "description": "The keyword-days at the keyword rate ($5 a month, 500/30 cents a day), rounded once on the total."
        },
        "matchedMentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches recorded in the window, relevant or not."
        },
        "billableMentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Of the matches billed in the window (every scored match, relevant or not), the ones in this group."
        },
        "unclassifiedMentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches recorded in the window that are never charged: no score yet (still being scored, or classification failed), or a free review from the look-back of a newly connected app. Every other match is charged, on the mentions line or, for a comment, on the comments line."
        },
        "mentionCents": {
          "type": "integer",
          "description": "The billed mentions at $0.008 each, rounded once on the total."
        },
        "billableComments": {
          "type": "integer",
          "minimum": 0,
          "description": "Comments billed in the window (the comments line): comments delivered under your mentions and comments that matched a keyword, each once per workspace."
        },
        "commentCents": {
          "type": "integer",
          "description": "The billed comments at $0.008 each, rounded once on the total."
        },
        "totalCents": {
          "type": "integer",
          "description": "keywordCents plus mentionCents plus commentCents."
        },
        "ledgerDebitCents": {
          "type": "integer",
          "description": "What the ledger has debited so far for the days of the window, each debit by the day it settled, for the whole workspace whatever the filters. Mentions settle the morning after their day, so a window ending today lags totalCents by today's mentions (and yesterday's before the tick at 00:05 UTC); a closed month differs from totalCents only by cumulative rounding."
        },
        "unattributedBillable": {
          "type": "integer",
          "minimum": 0,
          "description": "Billed mentions whose match row is gone (deleted keyword), so no platform or keyword row can claim them. Charged all the same. Comments carry their keyword and platform on the billed row, so they are never unattributed (by=group puts a deleted keyword's comments on the no-group row)."
        }
      },
      "required": [
        "keywordDays",
        "keywordCents",
        "matchedMentions",
        "billableMentions",
        "unclassifiedMentions",
        "mentionCents",
        "billableComments",
        "commentCents",
        "totalCents",
        "ledgerDebitCents",
        "unattributedBillable"
      ],
      "description": "The whole window as one line, the same for every dimension."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The row's key: the UTC day (YYYY-MM-DD) for by=day, the platform for by=platform, the keyword id for by=keyword, the group id for by=group."
          },
          "label": {
            "type": "string",
            "description": "Readable name: the keyword term or the group name, otherwise the key."
          },
          "keyword": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Keyword id (kw_...); a deleted keyword keeps its id here."
              },
              "term": {
                "type": "string",
                "description": "The term as it was last metered, or as the keyword reads now."
              },
              "removed": {
                "type": "boolean",
                "description": "The keyword has since been deleted. Its charges stay on the record; its mentions went with it, so its mention counts read 0."
              }
            },
            "required": [
              "id",
              "term",
              "removed"
            ],
            "description": "by=keyword only; null otherwise."
          },
          "group": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Group id, or \"none\" for keyword-days metered before groups existed whose keyword is gone."
              },
              "name": {
                "type": "string",
                "description": "The group's name as it reads now, or \"Deleted group\" / \"No group\"."
              },
              "removed": {
                "type": "boolean",
                "description": "The group has since been deleted."
              }
            },
            "required": [
              "id",
              "name",
              "removed"
            ],
            "description": "by=group only; null otherwise."
          },
          "keywordDays": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "Keyword-days metered in this group: the days the daily tick charged for. Null for by=platform (a keyword-day belongs to no platform) and for a day before the first recorded tick (unknown, not zero); a keyword row counts only the days on record, so before window.keywordDaysFrom it is a floor, not a zero."
          },
          "keywordCents": {
            "type": "integer",
            "description": "The keyword-days at the keyword rate ($5 a month, 500/30 cents a day), rounded once on the total."
          },
          "matchedMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Matches recorded in the window, relevant or not."
          },
          "billableMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Of the matches billed in the window (every scored match, relevant or not), the ones in this group."
          },
          "unclassifiedMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Matches recorded in the window that are never charged: no score yet (still being scored, or classification failed), or a free review from the look-back of a newly connected app. Every other match is charged, on the mentions line or, for a comment, on the comments line."
          },
          "mentionCents": {
            "type": "integer",
            "description": "The billed mentions at $0.008 each, rounded once on the total."
          },
          "billableComments": {
            "type": "integer",
            "minimum": 0,
            "description": "Comments billed in the window (the comments line): comments delivered under your mentions and comments that matched a keyword, each once per workspace."
          },
          "commentCents": {
            "type": "integer",
            "description": "The billed comments at $0.008 each, rounded once on the total."
          },
          "totalCents": {
            "type": "integer",
            "description": "keywordCents plus mentionCents plus commentCents."
          }
        },
        "required": [
          "key",
          "label",
          "keyword",
          "group",
          "keywordDays",
          "keywordCents",
          "matchedMentions",
          "billableMentions",
          "unclassifiedMentions",
          "mentionCents",
          "billableComments",
          "commentCents",
          "totalCents"
        ]
      },
      "description": "by=day: chronological. by=platform and by=keyword: most expensive first, then most matched, deleted keywords included."
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "description": "Rows in the dimension before `limit` and `offset`."
    }
  },
  "required": [
    "window",
    "by",
    "filtered",
    "currency",
    "totals",
    "data",
    "total"
  ]
}