{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/rumoro-dev/json-schema/rumoro-dev-usage-breakdown-schema.json",
  "title": "UsageBreakdown",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/rumoro-dev-usage-api-openapi.yml#/components/schemas/UsageBreakdown",
  "type": "object",
  "properties": {
    "window": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "Start date (UTC, YYYY-MM-DD), included."
        },
        "to": {
          "type": "string",
          "description": "The last day included. It is today for a trailing range or the current month."
        },
        "days": {
          "type": "integer",
          "minimum": 0,
          "description": "How many days the window spans."
        },
        "keywordDaysFrom": {
          "type": [
            "string",
            "null"
          ],
          "description": "Earliest day in the window with a keyword count, or null. Earlier days show `keywordDays: null`."
        }
      },
      "required": [
        "from",
        "to",
        "days",
        "keywordDaysFrom"
      ],
      "description": "Report range in UTC days."
    },
    "by": {
      "type": "string",
      "enum": [
        "day",
        "platform",
        "keyword",
        "group"
      ],
      "description": "Grouping used for the rows."
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD"
      ],
      "description": "All amounts are in US cents."
    },
    "totals": {
      "type": "object",
      "properties": {
        "keywordDays": {
          "type": "integer",
          "minimum": 0,
          "description": "Sum of keyword-days over the window."
        },
        "keywordCents": {
          "type": "integer",
          "description": "Those keyword-days priced at $5 a month (500/30 cents a day), with the total rounded once."
        },
        "matchedMentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Match count for the window, relevant or not."
        },
        "billableMentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches billed in the window that fall in this row. Every scored match is billed, relevant or not."
        },
        "mentionCents": {
          "type": "integer",
          "description": "Those mentions priced at $0.008 each, with the total rounded once."
        },
        "billableComments": {
          "type": "integer",
          "minimum": 0,
          "description": "Comments billed on the comments line: comments delivered under mentions and matched replies, each once per workspace."
        },
        "commentCents": {
          "type": "integer",
          "description": "Those comments at $0.008 each, rounded once on the total."
        },
        "totalCents": {
          "type": "integer",
          "description": "keywordCents plus mentionCents plus commentCents."
        },
        "unclassifiedMentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches whose classification failed. They are never charged."
        },
        "ledgerDebitCents": {
          "type": "integer",
          "description": "Debits recorded so far for the window's days, each on its settlement day. Mentions settle the next morning, so a window ending today trails totalCents by today's mentions, plus yesterday's before the 00:05 UTC run. A closed month differs only by cumulative rounding."
        },
        "unattributedBillable": {
          "type": "integer",
          "minimum": 0,
          "description": "Billed mentions whose match was removed with a deleted keyword, so they belong to no platform or keyword row. They were still charged."
        }
      },
      "required": [
        "keywordDays",
        "keywordCents",
        "matchedMentions",
        "billableMentions",
        "mentionCents",
        "billableComments",
        "commentCents",
        "totalCents",
        "unclassifiedMentions",
        "ledgerDebitCents",
        "unattributedBillable"
      ],
      "description": "Totals for the whole window. They are the same whatever `by` is."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "What the row stands for. A UTC day (YYYY-MM-DD) with by=day, a platform with by=platform, a keyword id with by=keyword and a group id with by=group."
          },
          "label": {
            "type": "string",
            "description": "A name to display. The keyword's term or the group's name, or else the key."
          },
          "keyword": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The keyword's id (kw_...). Deleted keywords keep their id here."
              },
              "term": {
                "type": "string",
                "description": "The term when it was last charged, or its current term."
              },
              "removed": {
                "type": "boolean",
                "description": "The keyword was deleted later. Charges remain, but its mentions are gone, so mention counts are 0."
              }
            },
            "required": [
              "id",
              "term",
              "removed"
            ],
            "description": "Set only with by=keyword. Null otherwise."
          },
          "group": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The group's id. It is \"none\" for keyword-days charged before groups existed when the keyword has since been deleted."
              },
              "name": {
                "type": "string",
                "description": "Current group name, or \"Deleted group\" or \"No group\"."
              },
              "removed": {
                "type": "boolean",
                "description": "True when the group was deleted later."
              }
            },
            "required": [
              "id",
              "name",
              "removed"
            ],
            "description": "Set only with by=group. Null otherwise."
          },
          "keywordDays": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "Keyword-days charged in this row by the daily run. Null with by=platform, since a keyword-day has no platform, and for days before the first recorded run, where the count is unknown rather than zero. A keyword row only counts recorded days, so before window.keywordDaysFrom it is a minimum, not zero."
          },
          "keywordCents": {
            "type": "integer",
            "description": "Those keyword-days priced at $5 a month (500/30 cents a day), with the total rounded once."
          },
          "matchedMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Match count for the window, relevant or not."
          },
          "billableMentions": {
            "type": "integer",
            "minimum": 0,
            "description": "Matches billed in the window that fall in this row. Every scored match is billed, relevant or not."
          },
          "mentionCents": {
            "type": "integer",
            "description": "Those mentions priced at $0.008 each, with the total rounded once."
          },
          "billableComments": {
            "type": "integer",
            "minimum": 0,
            "description": "Comments billed on the comments line: comments delivered under mentions and matched replies, each once per workspace."
          },
          "commentCents": {
            "type": "integer",
            "description": "Those 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",
          "mentionCents",
          "billableComments",
          "commentCents",
          "totalCents"
        ]
      },
      "description": "With by=day the rows are in date order. With by=platform and by=keyword the most expensive come first, then those with the most matches, deleted keywords included."
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "description": "The number of rows before `limit` and `offset` are applied."
    }
  },
  "required": [
    "window",
    "by",
    "currency",
    "totals",
    "data",
    "total"
  ]
}