Limzo Public API

The Public API from Limzo — 3 operation(s) for public.

GitHub OpenAPI

Operations 3

GET /api/public/{slug} Alias of /s/{slug}.json #
GET /api/public/global-stats Network-wide totals across all public groups #
GET /api/public/groups List or search the public group directory #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/limzo-com:limzo-com-public-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

limzo-com-public-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Limzo Data Public API
  version: 1.0.0
  summary: Read-only JSON for public Telegram group stats pages.
  description: 'Every public Limzo group profile is available as machine-readable JSON — the same aggregate data the human page shows, built for agents, dashboards, and integrations.


    - **No authentication, no key.** All endpoints are public and read-only.

    - **CORS:** every endpoint sends `Access-Control-Allow-Origin: *`.

    - **Caching:** responses send `Cache-Control: public, max-age=1800`; stats move slowly, so respect the cache instead of polling.

    - **Rate limit:** 5 requests/second with a burst of 20 per client IP; excess requests get HTTP 429.

    - **Privacy:** payloads never include verbatim member messages. Private groups (no public t.me address) expose aggregate metrics and the member leaderboard only.

    - **Versioning:** the payload carries `schema: "limzo.public_stats/v1"`. Fields may be added without notice; breaking changes bump the schema version.


    To find groups to query, use /api/public/groups (list/search as JSON), the public directory (https://limzo.com/groups/), or the group sitemap (https://limzo.com/sitemap-groups.xml). Human-readable docs: https://limzo.com/docs/'
  contact:
    name: Limzo
    url: https://limzo.com/contact/
    email: info@limzo.com
  termsOfService: https://limzo.com/terms/
servers:
- url: https://limzo.com
tags:
- name: Public
paths:
  /api/public/{slug}:
    get:
      operationId: getGroupStatsAlias
      summary: Alias of /s/{slug}.json
      description: Same payload and parameters as /s/{slug}.json.
      parameters:
      - name: slug
        in: path
        required: true
        description: The group’s public slug — the last part of its limzo.com/s/<slug> URL.
        schema:
          type: string
        example: hipo
      - name: range
        in: query
        required: false
        description: Stats window. 30d and all require the group’s Pro/Ultra plan; on free groups the response silently falls back to 7d (check `range.key` in the payload).
        schema:
          type: string
          enum:
          - 7d
          - 30d
          - all
          default: 7d
      responses:
        '200':
          description: Curated public stats for the group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicGroupStats'
        '403':
          description: The group exists but its public page is disabled or not public.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No public group with this slug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: 'The group existed but its stats were deleted — Limzo was removed from it more than 90 days ago, or an admin deleted the data. This is permanent: stop polling this slug.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (more than 5 requests/second sustained from one IP). Slow down and retry.
      tags:
      - Public
  /api/public/global-stats:
    get:
      operationId: getGlobalStats
      summary: Network-wide totals across all public groups
      responses:
        '200':
          description: Totals over the public directory plus the current top groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalStats'
        '429':
          description: Rate limited (more than 5 requests/second sustained from one IP). Slow down and retry.
      tags:
      - Public
  /api/public/groups:
    get:
      operationId: listGroups
      summary: List or search the public group directory
      description: The machine twin of the /groups/ directory page. Sorted by Limzo Score; use the returned slug with /s/{slug}.json for full stats.
      parameters:
      - name: q
        in: query
        required: false
        description: Keyword matched case-insensitively against group title, username, slug, and description. Omit to list the top groups.
        schema:
          type: string
      - name: lang
        in: query
        required: false
        description: ISO 639-1 language code (e.g. "fa", "es"). Keeps groups whose main language it is (the detected top language, or the admin's chosen one when both are languages Limzo speaks) or where it is a meaningful share of what members write.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum groups to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      responses:
        '200':
          description: Matching public groups, best first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupDirectory'
        '429':
          description: Rate limited (more than 5 requests/second sustained from one IP). Slow down and retry.
      tags:
      - Public
components:
  schemas:
    GlobalStats:
      type: object
      description: Network-wide totals across all listed public groups.
      required:
      - ok
      - stats
      properties:
        ok:
          type: boolean
          const: true
        docs:
          type: string
          format: uri
          description: Human-readable API documentation.
        openapi:
          type: string
          format: uri
          description: Machine-readable OpenAPI document for the REST API.
        stats:
          type: object
          properties:
            public_groups:
              type: integer
              description: Public groups in the directory.
            messages_7d:
              type: integer
            messages_all:
              type: integer
            messages_total:
              type: integer
              description: Messages analyzed across all groups, all time (durable — survives retention pruning).
            members_total:
              type: integer
              description: Distinct members ever tracked across all groups.
            spam_removed_total:
              type: integer
              description: Spam messages removed by moderation across all groups, all time.
            active_users_7d:
              type: integer
            replies_7d:
              type: integer
            reactions_7d:
              type: integer
            karma_7d:
              type: integer
        top_groups:
          type: array
          description: Current top public groups by Limzo Score.
          items:
            type: object
            properties:
              title:
                type: string
              slug:
                type: string
              plan:
                type: string
                enum:
                - free
                - pro
                - community
              score:
                type: number
              messages_7d:
                type: integer
              active_users_7d:
                type: integer
    Error:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable reason.
      required:
      - ok
      - error
    PublicGroupStats:
      type: object
      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.'
      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.
    GroupDirectory:
      type: object
      description: Compact directory rows for discovering groups. Sorted by Limzo Score.
      required:
      - ok
      - total_matches
      - groups
      properties:
        ok:
          type: boolean
          const: true
        docs:
          type: string
          format: uri
          description: Human-readable API documentation.
        openapi:
          type: string
          format: uri
          description: Machine-readable OpenAPI document for the REST API.
        query:
          type:
          - string
          - 'null'
          description: The normalized search keyword, or null when listing top groups.
        lang:
          type:
          - string
          - 'null'
          description: The applied ISO 639-1 language filter, or null when not filtering by language.
        total_matches:
          type: integer
          description: Groups that matched, before the limit was applied.
        groups:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
                description: Use with /s/{slug}.json or the get_group_stats MCP tool.
              title:
                type: string
              username:
                type:
                - string
                - 'null'
                description: Telegram username without @, when the group is public on t.me.
              plan:
                type: string
                enum:
                - free
                - pro
                - community
              member_count:
                type:
                - integer
                - 'null'
              score:
                type: number
                description: Limzo Score — the directory ranking metric.
              messages_7d:
                type: integer
              active_users_7d:
                type: integer
              language:
                type:
                - object
                - 'null'
                description: The group's language mix (primary language + top languages as percentages). Null when there is not enough signal.
                properties:
                  primary:
                    type:
                    - string
                    - 'null'
                    description: Dominant language as an ISO 639-1 code.
                  distinct:
                    type: integer
                    description: Number of distinct languages detected.
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type:
                          - string
                          - 'null'
                          description: ISO 639-1 language code, or null for the aggregated "other" bucket.
                        name:
                          type: string
                        pct:
                          type: number
                          description: Share of the group, 0–100.
              url:
                type: string
                format: uri
                description: The human stats page for this group.
              stats_json:
                type: string
                format: uri
                description: Full curated stats payload for this group.
externalDocs:
  description: Developer documentation
  url: https://limzo.com/docs/