{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mentio-dev/json-schema/mentio-dev-analytics-breakdown-schema.json",
  "title": "AnalyticsBreakdown",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mentio-dev-analytics-api-openapi.yml#/components/schemas/AnalyticsBreakdown",
  "type": "object",
  "properties": {
    "window": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "First day, inclusive."
        },
        "to": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Last day, inclusive."
        },
        "days": {
          "type": "integer",
          "minimum": 0,
          "description": "Length of the window in days."
        },
        "timezone": {
          "type": "string",
          "description": "IANA zone the days were cut in."
        }
      },
      "required": [
        "from",
        "to",
        "days",
        "timezone"
      ],
      "description": "The window the report covers."
    },
    "by": {
      "type": "string",
      "enum": [
        "platform",
        "keyword",
        "sentiment",
        "intent",
        "status",
        "hour",
        "person",
        "language",
        "country",
        "subreddit"
      ],
      "description": "The dimension the rows are grouped by."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The group: platform name, keyword id, sentiment, intent, status, \"weekday-hour\" for by=hour, an opaque person key, or the subreddit in lowercase."
          },
          "label": {
            "type": "string",
            "description": "Readable name: the keyword term, the person name, the subreddit as Reddit spells it, otherwise the key."
          },
          "keyword": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Keyword id (kw_...)."
              },
              "term": {
                "type": "string",
                "description": "The tracked term."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "brand",
                  "competitor",
                  "topic"
                ],
                "description": "brand, competitor or topic."
              },
              "group": {
                "allOf": [
                  {
                    "$ref": "#/$defs/GroupRef"
                  },
                  {
                    "description": "The group the keyword is in."
                  }
                ]
              }
            },
            "required": [
              "id",
              "term",
              "kind",
              "group"
            ],
            "description": "by=keyword only; null otherwise."
          },
          "person": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Person id (aut_...); null for posts ingested before people were linked."
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Display name as the platform shows it."
              },
              "platform": {
                "type": "string",
                "enum": [
                  "bluesky",
                  "hackernews",
                  "github",
                  "stackoverflow",
                  "devto",
                  "reddit",
                  "x",
                  "youtube",
                  "news",
                  "linkedin",
                  "tiktok",
                  "instagram",
                  "appstore",
                  "googleplay",
                  "trustpilot",
                  "googlemaps",
                  "rss"
                ],
                "description": "Platform: bluesky, hackernews, github, stackoverflow, devto, reddit, x, youtube, news, linkedin, tiktok, instagram, appstore (App Store reviews), googleplay (Google Play reviews), trustpilot (Trustpilot reviews), googlemaps (Google reviews of a place), rss (RSS and Atom feeds a keyword reads)."
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Profile URL."
              },
              "avatarUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Avatar image URL, when the platform gave one."
              },
              "followers": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "description": "From the audience profile; null when unknown."
              }
            },
            "required": [
              "id",
              "name",
              "platform",
              "url",
              "avatarUrl",
              "followers"
            ],
            "description": "by=person only; null otherwise."
          },
          "slot": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "weekday": {
                "type": "integer",
                "minimum": 0,
                "maximum": 6,
                "description": "0 = Sunday through 6 = Saturday."
              },
              "hour": {
                "type": "integer",
                "minimum": 0,
                "maximum": 23,
                "description": "Hour of day, 0 to 23."
              }
            },
            "required": [
              "weekday",
              "hour"
            ],
            "description": "by=hour only: the weekday and hour of day in `timezone`; null otherwise."
          },
          "matched": {
            "type": "integer",
            "minimum": 0,
            "description": "Matches in the group."
          },
          "relevant": {
            "type": "integer",
            "minimum": 0,
            "description": "Of those, scored at or above the relevance threshold."
          },
          "share": {
            "type": "number",
            "description": "Percent of the window's matched mentions in this group, one decimal. Intents overlap, so their shares can add up past 100."
          },
          "sentiment": {
            "type": "object",
            "properties": {
              "positive": {
                "type": "integer",
                "minimum": 0,
                "description": "Classified positive."
              },
              "neutral": {
                "type": "integer",
                "minimum": 0,
                "description": "Classified neutral."
              },
              "negative": {
                "type": "integer",
                "minimum": 0,
                "description": "Classified negative."
              },
              "unclassified": {
                "type": "integer",
                "minimum": 0,
                "description": "Not scored: still queued, or the classifier failed on it."
              }
            },
            "required": [
              "positive",
              "neutral",
              "negative",
              "unclassified"
            ],
            "description": "Matched mentions by classifier sentiment."
          },
          "previous": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "matched": {
                "type": "integer",
                "minimum": 0,
                "description": "Matches in the group then."
              },
              "relevant": {
                "type": "integer",
                "minimum": 0,
                "description": "Relevant matches in the group then."
              }
            },
            "required": [
              "matched",
              "relevant"
            ],
            "description": "The same group over the period right before the window; null unless compare=true."
          }
        },
        "required": [
          "key",
          "label",
          "keyword",
          "person",
          "slot",
          "matched",
          "relevant",
          "share",
          "sentiment",
          "previous"
        ]
      },
      "description": "Most matched first, at most 50 groups. by=hour is chronological and unlimited (168 cells at most)."
    }
  },
  "required": [
    "window",
    "by",
    "data"
  ],
  "$defs": {
    "GroupRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Group id (grp_...)."
        },
        "name": {
          "type": "string",
          "description": "The group's name."
        },
        "externalId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Your own id for the group, or null."
        },
        "isDefault": {
          "type": "boolean",
          "description": "The workspace's default group, where a keyword lands when no group is named."
        }
      },
      "required": [
        "id",
        "name",
        "externalId",
        "isDefault"
      ],
      "description": "The group the keyword belongs to."
    }
  }
}