Limzo Telegram Group Stats
Estatísticas públicas somente leitura para grupos do Telegram monitorados pelo Limzo — atividade, engajamento, humor e rankings, sem necessidade de chave de API.
Documentação
API de Dados do Limzo
Todo perfil público de grupo do Limzo também está disponível como JSON somente leitura — as mesmas estatísticas agregadas que a página humana mostra, criadas para dashboards, bots e agentes de IA. Sem autenticação, habilitado para CORS, descrito por uma especificação OpenAPI 3.1.
Início rápido
Pegue qualquer URL de perfil público e adicione .json — ou apenas abra limzo.com/s/hipo.json no seu navegador agora mesmo (hipo é um grupo real, o exemplo ao vivo do site):
curl https://limzo.com/s/hipo.json
Uma resposta real dessa URL, resumida:
{
"ok": true,
"schema": "limzo.public_stats/v1",
"generated_at": "2026-07-15T12:55:04.464Z",
"docs": "https://limzo.com/docs/",
"openapi": "https://limzo.com/api/public/openapi.json",
"group": {
"slug": "hipo",
"title": "Hipo Chat",
"username": "hipo_chat",
"is_private": false,
"bot_in_group": true,
"plan": "community",
"member_count": 3922,
"url": "https://limzo.com/s/hipo",
"telegram_url": "https://t.me/hipo_chat"
},
"range": { "key": "7d", "label": "7 days", "days": 7 },
"stats": {
"messages": 906,
"replies": 391,
"active_users": 228,
"lifetime_messages": 1728,
"peak_hour_utc": 21,
"mood": { "label": "Sunny", "emoji": "☀️", "positive_pct": 81 },
"daily": [ { "day": "2026-07-09", "messages": 142, "replies": 80, "active_users": 31 }, "…" ],
"top_members": [ { "rank": 1, "name": "Josip", "username": "heretic", "messages": 213, "replies": 116 }, "…" ],
"top_reactor": { "name": "mili", "username": "milibilij", "count": 120 },
"reaction_magnet": { "name": "Josip", "username": "heretic", "count": 228 },
"languages": { "primary": "en", "distinct": 4, "items": [ { "code": "en", "name": "English", "pct": 62 }, { "code": "fa", "name": "Persian", "pct": 21 }, "…" ] },
"levels": [ { "rank": 1, "name": "Josip", "username": "heretic", "level": 12, "tier": "veteran", "tier_title": "Veteran", "xp": 1930 }, "…" ],
"league": { "season": "2026-W30", "members": [ { "rank": 1, "name": "mili", "username": "milibilij", "tier": "diamond", "messages": 213, "movement": 1 }, "…" ] }
}
}
Essa é a API completa: JSON público e somente leitura via HTTPS simples. Sem chave, sem cadastro, sem necessidade de SDK.
Use com um assistente de IA
A API foi projetada para ser consumida diretamente por ferramentas de IA — assistentes podem buscar essas URLs durante a conversa, e a especificação OpenAPI se integra a frameworks de agentes sem código de ligação. Três coisas para experimentar (a história voltada a administradores está em Visibilidade de IA para seu grupo). Ainda não conectou nenhum grupo? Cada prompt abaixo funciona como está com hipo, o grupo de exemplo ao vivo, no lugar de yourgroup:
1. Leitura instantânea de saúde. Cole no ChatGPT ou Claude:
Open https://limzo.com/s/yourgroup.json and tell me how my community
is doing — the trend, the mood, and what I should fix first.
2. Ferramentas nativas no ChatGPT e Claude. No ChatGPT, experimente o oficial Limzo Community Analyst na GPT Store — ou crie seu próprio GPT personalizado importando a especificação como uma Action:
https://limzo.com/api/public/openapi.json
No Claude, adicione o conector MCP do Limzo (Configurações → Conectores → Adicionar conector personalizado) e o Claude recebe as estatísticas como ferramentas nativas:
https://limzo.com/api/public/mcp
A URL do OpenAPI também funciona em qualquer lugar onde ferramentas descritas por OpenAPI sejam aceitas; a URL do MCP funciona com qualquer cliente MCP.
3. Um dashboard ao vivo sem backend. A API é aberta para CORS, então buscas no navegador funcionam de qualquer origem. Um prompt para o Claude ou ChatGPT:
Build a single-file HTML dashboard that fetches
https://limzo.com/s/yourgroup.json and shows the daily trend
(stats.daily), the leaderboard (stats.top_members), and the
mood (stats.mood). Refresh every 30 minutes. The exact response
schema: https://limzo.com/api/public/openapi.json
Endpoints
GET /s/{slug}.json
Estatísticas de um grupo público. Espelha a URL da página humana — {slug} é a última parte do endereço limzo.com/s/<slug> do grupo. Alias: GET /api/public/{slug} retorna o mesmo payload.
Parâmetro de consulta opcional ?range=7d|30d|all — veja intervalos. Slugs desconhecidos retornam um JSON 404 ({"ok":false,"error":"Public stats page not found."}); grupos cuja página pública está desativada retornam 403; e um grupo cujas estatísticas foram excluídas retorna um 410 permanente ({"ok":false,"gone":true}) — pare de consultar esse slug.
Experimente: /s/hipo.json · /api/public/hipo (alias) · um 404
GET /api/public/groups
Lista ou pesquisa o diretório público de grupos — o equivalente em máquina de /groups/, para descobrir grupos e seus slugs. ?q=<keyword\> opcional corresponde sem diferenciar maiúsculas de minúsculas contra título, nome de usuário, slug e descrição; ?lang=<ISO 639-1\> (ex.: fa, es) mantém apenas grupos onde esse idioma é uma parcela significativa do que os membros escrevem; ?limit=1–50 limita as linhas (padrão 20). Cada linha traz uma mistura de idiomas (idioma principal + principais idiomas como porcentagens). Ordenado pela Pontuação Limzo.
Experimente: /api/public/groups · /api/public/groups?q=hipo · /api/public/groups?lang=fa
GET /api/public/global-stats
Totais em toda a rede entre todos os grupos públicos listados (contagem de grupos, mensagens, membros ativos, respostas, reações, karma — 7 dias e todos os tempos) além dos principais grupos atuais pela Pontuação Limzo.
Experimente: /api/public/global-stats
GET /api/public/openapi.json
Esta API como um documento OpenAPI 3.1 legível por máquina — esquemas completos de requisição/resposta para geradores de código, clientes de API e agentes de IA. Abra a especificação.
POST /api/public/mcp
A mesma API como um servidor MCP (Model Context Protocol, HTTP transmissível, sem autenticação) para Claude e qualquer cliente MCP. Expõe três ferramentas somente leitura: list_groups, get_group_stats e get_global_stats.
Conecte no Claude: Configurações → Conectores → Adicionar conector personalizado → https://limzo.com/api/public/mcp. No Claude Code: claude mcp add --transport http limzo https://limzo.com/api/public/mcp
Clientes MCP que só falam stdio podem usar o pacote npm limzo-mcp, uma ponte leve para o mesmo endpoint: defina o comando do cliente como npx com args ["-y", "limzo-mcp"]. Prefira a URL do conector acima quando seu cliente suportar MCP remoto.
O parâmetro de intervalo
As estatísticas do grupo usam por padrão os últimos 7 dias. Existem duas janelas mais amplas:
| Valor | Janela | Disponibilidade |
|---|---|---|
| 7d | Últimos 7 dias | Todos os grupos (padrão) |
| 30d | Últimos 30 dias | Grupos no plano Pro ou Community |
| all | Todos os tempos | Grupos no plano Pro ou Community |
Solicitar 30d ou all em um grupo do plano gratuito não é um erro — a resposta silenciosamente volta para 7 dias. Sempre verifique range.key no payload para ver qual janela você realmente obteve.
O grupo de exemplo está em um plano pago, então ambas as janelas mais amplas servem dados reais — compare range.key entre ?range=30d e ?range=all.
Referência de resposta
O payload de estatísticas do grupo (esquema: "limzo.public_stats/v1") tem três partes: group, range e stats. A definição exata legível por máquina está na especificação OpenAPI.
group
| Campo | Tipo | Significado |
|---|---|---|
| slug | string | O slug público do grupo. |
| title | string? | Título de exibição. |
| username | string? | Nome de usuário do Telegram sem @, quando o grupo é público no t.me. |
| is_private | boolean | Verdadeiro quando o grupo não tem endereço público no t.me. |
| bot_in_group | boolean | Falso assim que o Limzo for removido do chat. Cada número por janela então para de avançar e a página se torna um arquivo congelado. |
| plan | string | free, pro ou community. |
| member_count | integer? | Total de membros. |
| description | string? | Descrição do grupo. |
| url | string | A página humana de estatísticas. |
| telegram_url | string? | Link do t.me, quando público. |
range
| Campo | Tipo | Significado |
|---|---|---|
| key | string | A janela realmente servida: 7d, 30d ou all. |
| label | string | Rótulo humano, ex.: "7 days". |
| days | integer | Duração da janela em dias. |
stats
| Campo | Tipo | Significado |
|---|---|---|
| messages | integer | Mensagens no intervalo selecionado. |
| replies | integer | Respostas no intervalo selecionado. |
| stickers | integer | Figurinhas no intervalo selecionado. |
| active_users | integer | Membros únicos que postaram no intervalo. |
| messages_today | integer | Mensagens até agora hoje (UTC). |
| active_users_today | integer | Membros únicos que postaram até agora hoje (UTC). |
| lifetime_messages | integer | Mensagens desde o início do rastreamento. |
| tracked_since_days | integer | Dias desde o início do rastreamento. |
| new_active_members | integer | Membros que postaram pela primeira vez no intervalo. |
| tracking_frozen | boolean | Verdadeiro enquanto o rastreamento está pausado porque o grupo usou a cota mensal de mensagens do plano. Reinicia no dia 1º (UTC). Enquanto verdadeiro, as estatísticas por janela subestimam a atividade real — o grupo não está quieto. |
| tracking_paused | boolean | Verdadeiro quando o Limzo não está mais no grupo, então nada mais será contado. Diferente de tracking_frozen, isso só é limpo se o bot for readicionado. |
| peak_hour_utc | integer? | Hora mais movimentada do dia, 0–23 UTC. |
| mood | object? | { label, emoji, positive_pct } — humor do grupo a partir de reações. |
| daily | array | Série por dia: { day, messages, replies, active_users }. |
| top_members | array | Ranking: { rank, name, username, messages, replies }. |
| top_reactor | object? | Membro que mais reagiu: { name, username, count }. |
| reaction_magnet | object? | Membro cujas mensagens atraíram mais reações. |
| languages | object? | Quão internacional é o grupo: { primary, distinct, items:[{ code, name, pct }] }. Códigos são ISO 639-1; detectados a partir do que os membros escrevem, com fallback para o idioma do aplicativo deles. Nulo quando o sinal é fraco. |
Campos marcados com? podem ser nulos — geralmente quando um grupo ainda não acumulou esses dados.
Cache, CORS e limites de taxa
| Cabeçalho / limite | Valor | Notas |
|---|---|---|
| Cache-Control | public, max-age=1800 | As estatísticas mudam lentamente; respeite o cache de 30 minutos em vez de consultar repetidamente. |
| Access-Control-Allow-Origin | * | Chame a API diretamente de aplicativos no navegador. |
| Limite de taxa | 5 req/s, rajada 20 | Por IP do cliente. Solicitações em excesso recebem HTTP 429 — recue e tente novamente. |
| HEAD | suportado | Todos os endpoints respondem a sondagens HEAD apenas com cabeçalhos. |
Veja por si mesmo:
$ curl -I https://limzo.com/s/hipo.json
HTTP/2 200
content-type: application/json; charset=utf-8
cache-control: public, max-age=1800
access-control-allow-origin: *
JSON é a forma barata de consumir o Limzo — um payload típico é ~50× menor que a página HTML equivalente. Se você está construindo algo que precisa de mais do que o feed público oferece, conte para a gente.
Encontrando grupos para consultar
Slugs são públicos e descobríveis:
• O diretório público de grupos lista perfis públicos ativos.
• O sitemap de grupos enumera cada URL de perfil público.
• Cada página de estatísticas carrega uma tag <link rel="alternate" type="application/json"> apontando para seu equivalente JSON.
• llms.txt resume todo o site — incluindo esta API — para assistentes de IA.
Versionamento e estabilidade
O payload carrega schema: "limzo.public_stats/v1". Novos campos podem ser adicionados a qualquer momento sem aviso — escreva consumidores que ignorem chaves desconhecidas. Mudanças que quebram compatibilidade (campos renomeados ou removidos, significados alterados) aumentarão a versão do esquema, então fixe sua integração ao valor do esquema.
Dúvidas ou pedidos de recursos? Entre na comunidade Limzo no Telegram ou fale conosco.