{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/limzo-com/json-schema/limzo-com-public-group-stats-schema.json",
  "title": "PublicGroupStats",
  "description": "Curated, versioned public stats payload. Never includes verbatim member messages. For a private group (one with no public t.me handle) the member identities, the group description and member_count are withheld too: aggregates plus an anonymised leaderboard are all it returns.",
  "x-generated": "2026-11-17",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/limzo-com-openapi.yml#/components/schemas/PublicGroupStats",
  "type": "object",
  "required": [
    "ok",
    "schema",
    "generated_at",
    "group",
    "range",
    "stats"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "schema": {
      "type": "string",
      "const": "limzo.public_stats/v1"
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "docs": {
      "type": "string",
      "format": "uri",
      "description": "Human-readable API documentation."
    },
    "openapi": {
      "type": "string",
      "format": "uri",
      "description": "Machine-readable OpenAPI document for the REST API."
    },
    "group": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string"
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "username": {
          "type": [
            "string",
            "null"
          ],
          "description": "Telegram username without @, when the group is public on t.me."
        },
        "is_private": {
          "type": "boolean",
          "description": "True when the group has no public t.me address. Private groups expose aggregate stats and an anonymised leaderboard only: member identities, verbatim content, the group description and member_count are all withheld, and the group is not listed in the public directory."
        },
        "bot_in_group": {
          "type": "boolean",
          "description": "False once Limzo has been removed from the chat. Every windowed figure then stops advancing and the page becomes a frozen archive; the data is kept for 90 days after removal, then the page returns 410."
        },
        "plan": {
          "type": "string",
          "enum": [
            "free",
            "pro",
            "community"
          ]
        },
        "member_count": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Telegram member count. Always null for a private group — Limzo only knows it because the bot is in the chat, so it is not ours to publish."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "The group description. On a private group this is null unless an admin wrote a public description specifically for this page, in which case that text is served instead of the Telegram one."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The human stats page for this group."
        },
        "telegram_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        }
      }
    },
    "range": {
      "type": "object",
      "description": "The range actually served — compare `key` with what you requested to detect the plan fallback.",
      "properties": {
        "key": {
          "type": "string",
          "enum": [
            "7d",
            "30d",
            "all"
          ]
        },
        "label": {
          "type": "string"
        },
        "days": {
          "type": "integer",
          "description": "Length of the window in days."
        }
      }
    },
    "stats": {
      "type": "object",
      "properties": {
        "messages": {
          "type": "integer",
          "description": "Messages in the selected range."
        },
        "replies": {
          "type": "integer",
          "description": "Replies in the selected range."
        },
        "stickers": {
          "type": "integer",
          "description": "Stickers in the selected range."
        },
        "active_users": {
          "type": "integer",
          "description": "Unique posting members in the selected range."
        },
        "messages_today": {
          "type": "integer",
          "description": "Messages so far today (UTC)."
        },
        "active_users_today": {
          "type": "integer",
          "description": "Unique posting members so far today (UTC)."
        },
        "lifetime_messages": {
          "type": "integer",
          "description": "Messages since Limzo started tracking the group."
        },
        "tracked_since_days": {
          "type": "integer",
          "description": "Days since tracking started."
        },
        "new_active_members": {
          "type": "integer",
          "description": "Members who posted for the first time in the selected range."
        },
        "tracking_frozen": {
          "type": "boolean",
          "description": "True while tracking is paused because the group used up its plan's monthly message allowance (resets on the 1st, UTC). While true, windowed stats undercount real activity — the group is NOT quiet."
        },
        "tracking_paused": {
          "type": "boolean",
          "description": "True when Limzo is no longer in the group, so nothing further will ever be counted. Unlike tracking_frozen (a monthly cap that lifts on the 1st) this only clears if the bot is re-added. Mirrors group.bot_in_group === false."
        },
        "peak_hour_utc": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 23,
          "description": "Busiest hour of day, UTC."
        },
        "mood": {
          "type": [
            "object",
            "null"
          ],
          "description": "Group mood derived from reactions. Null when there is not enough data.",
          "properties": {
            "label": {
              "type": "string"
            },
            "emoji": {
              "type": "string"
            },
            "positive_pct": {
              "type": "number",
              "description": "Share of positive reactions, 0–100."
            }
          }
        },
        "daily": {
          "type": "array",
          "description": "Per-day series over the selected range.",
          "items": {
            "type": "object",
            "properties": {
              "day": {
                "type": "string",
                "format": "date"
              },
              "messages": {
                "type": "integer"
              },
              "replies": {
                "type": "integer"
              },
              "active_users": {
                "type": "integer"
              }
            }
          }
        },
        "top_members": {
          "type": "array",
          "description": "Member leaderboard for the selected range.",
          "items": {
            "type": "object",
            "properties": {
              "rank": {
                "type": "integer",
                "description": "1-based position."
              },
              "name": {
                "type": "string"
              },
              "username": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "messages": {
                "type": "integer"
              },
              "replies": {
                "type": "integer"
              }
            }
          }
        },
        "top_reactor": {
          "type": [
            "object",
            "null"
          ],
          "description": "A member singled out by reaction activity. Null when the range has no reaction data.",
          "properties": {
            "name": {
              "type": "string",
              "description": "Display name as shown on the public page."
            },
            "username": {
              "type": [
                "string",
                "null"
              ],
              "description": "Telegram username without @, when public."
            },
            "count": {
              "type": "integer",
              "description": "Reactions in the selected range."
            }
          }
        },
        "reaction_magnet": {
          "type": [
            "object",
            "null"
          ],
          "description": "The member whose messages attracted the most reactions. Null when the range has no reaction data.",
          "properties": {
            "name": {
              "type": "string",
              "description": "Display name as shown on the public page."
            },
            "username": {
              "type": [
                "string",
                "null"
              ],
              "description": "Telegram username without @, when public."
            },
            "count": {
              "type": "integer",
              "description": "Reactions in the selected range."
            }
          }
        },
        "languages": {
          "type": [
            "object",
            "null"
          ],
          "description": "How international the group is: its language mix, detected from the languages members actually write in (falling back to their app language for new or quiet groups). Null when there is not enough signal. Never derived from verbatim message text exposed over the API.",
          "properties": {
            "primary": {
              "type": [
                "string",
                "null"
              ],
              "description": "Dominant language as an ISO 639-1 code (e.g. \"fa\", \"es\", \"en\")."
            },
            "distinct": {
              "type": "integer",
              "description": "Number of distinct languages detected."
            },
            "items": {
              "type": "array",
              "description": "Top languages by share, largest first; a trailing null-code \"other\" bucket may aggregate the long tail.",
              "items": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ISO 639-1 language code, or null for the aggregated \"other\" bucket."
                  },
                  "name": {
                    "type": "string",
                    "description": "Language name in English."
                  },
                  "pct": {
                    "type": "number",
                    "description": "Share of the group, 0–100."
                  }
                }
              }
            }
          }
        },
        "levels": {
          "type": "array",
          "description": "Limzo Levels — the group's lifetime-XP ladder (top 12 members). XP accrues from karma (helpful replies, reactions received, conversation starters), never from raw message volume alone. Tier names may be customised by the group.",
          "items": {
            "type": "object",
            "properties": {
              "rank": {
                "type": "integer",
                "description": "1-based position."
              },
              "name": {
                "type": "string"
              },
              "username": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "level": {
                "type": "integer",
                "description": "Current level (permanent, no decay)."
              },
              "tier": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Badge tier key: newcomer, regular, familiar, veteran, elite, legend."
              },
              "tier_title": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Display title for the tier (may be a group-custom name)."
              },
              "xp": {
                "type": "integer",
                "description": "Lifetime XP (karma) in this group."
              }
            }
          }
        },
        "league": {
          "type": [
            "object",
            "null"
          ],
          "description": "Weekly league standings (this ISO week, resets Monday). Only present when the group has the league enabled; null otherwise. Tiers are activity percentile bands: diamond top 10%, platinum next 15%, gold next 25%, silver next 25%, bronze rest.",
          "properties": {
            "season": {
              "type": "string",
              "description": "ISO week key, e.g. \"2026-W30\"."
            },
            "members": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "rank": {
                    "type": "integer",
                    "description": "1-based position this week."
                  },
                  "name": {
                    "type": "string"
                  },
                  "username": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "tier": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "bronze, silver, gold, platinum, or diamond."
                  },
                  "messages": {
                    "type": "integer",
                    "description": "Messages this ISO week."
                  },
                  "movement": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "1 promoted vs last week, -1 relegated, 0 unchanged, null = no baseline yet."
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}