tgstat
GitHub通过TGStat API搜索Telegram频道并获取受众与互动数据，用于俄语市场广告投放、竞品分析及购买广告前的效果评估。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill tgstat -g -y
SKILL.md
Frontmatter
{
"name": "tgstat",
"license": "Apache-2.0",
"metadata": {
"author": "acedatacloud",
"version": "1.0"
},
"connections": [
"tgstat"
],
"description": "Search Telegram channels\/chats and pull audience + engagement stats (subscribers, reach, ER\/ERR) from TGStat via its Stat API. Use when the user wants to find Telegram channels to advertise in (esp. Russian-language \/ RU market), research competitor channels, or check a channel's reach\/engagement before buying an ad placement.",
"when_to_use": "Trigger when the user wants to discover Telegram channels by keyword \/\ncategory \/ country \/ language, inspect a specific channel's subscriber\ncount, average post reach and engagement (ER \/ ERR) to judge ad value,\nor check their TGStat API quota. This is a marketing-research \/\nad-channel-selection tool — it does NOT post to Telegram (use the\n`telegram` connector for reading\/sending messages).\n",
"allowed_tools": [
"Bash"
]
}
Call the TGStat Stat API with curl + jq. The user's token is in
$TGSTAT_TOKEN and is passed as the token query parameter on every request.
Base URL: https://api.tgstat.ru.
Responses are JSON shaped {"status":"ok","response": ...}. Errors come back as
{"status":"error","error":"<message>"} — show the error verbatim. An invalid
token or an inactive/expired API plan will surface here; tell the user to check
their token / plan in the TGStat 个人中心 and re-connect the connector.
Always confirm the token + remaining quota first (usage/stat is free and
does not count against tariff quota):
curl -sS "https://api.tgstat.ru/usage/stat?token=$TGSTAT_TOKEN" \
| jq '.status, (.response[]? | {serviceKey, title, spentChannels, spentRequests, expiredAt})'
Find channels to advertise in (the main workflow)
GET /channels/search — at least one of q (keyword, min 3 chars) or
category is required.
Params: q, category, country, language (default russian),
peer_type (channel | chat | all, default channel),
search_by_description (0/1), limit (max 100).
# Russian-language AI/ChatGPT channels, biggest first.
curl -sS "https://api.tgstat.ru/channels/search" \
--data-urlencode "token=$TGSTAT_TOKEN" \
--data-urlencode "q=нейросети" \
--data-urlencode "language=russian" \
--data-urlencode "peer_type=channel" \
--data-urlencode "limit=50" -G \
| jq '.response.items | sort_by(-.participants_count)
| .[] | {username, title, subs: .participants_count, ci_index, link}'
- Use
--data-urlencode ... -Gso Cyrillic / spaces inqare encoded correctly. ci_index(индекс цитирования) is TGStat's citation/authority score — higher = more reposted/mentioned elsewhere, a useful quality signal beyond raw subs.- Try several keywords (
ChatGPT,нейросети,AI,разработка,API) and merge results; TGStat matches title/username (addsearch_by_description=1to also match the channel description).
Judge a channel's ad value
GET /channels/stat?channelId=<@username | t.me/username | tgstat id> returns
the numbers that actually matter for ad pricing:
curl -sS "https://api.tgstat.ru/channels/stat?token=$TGSTAT_TOKEN&channelId=@durov" \
| jq '.response | {
subs: .participants_count,
avg_post_reach, # средний охват публикации
adv_reach_24h: .adv_post_reach_24h, # рекламный охват за 24ч — key for CPM
er_percent, err_percent, err24_percent,
daily_reach, ci_index, posts_count
}'
- For ad CPM estimation use
adv_post_reach_24h(average advertising reach of a post over 24h), not raw subscriber count — subs are vanity, reach is what the ad actually gets seen by. - Low
err_percent/err24_percentrelative to subs = inflated/dead audience → skip it. - For a chat (not channel) the response instead has
dau/wau/mauandmessages_count_*fields.
GET /channels/get?channelId=... returns descriptive info (title, about,
category, country, language, participants_count, ci_index) when you
just need to identify/verify a channel rather than full stats.
Reference data
GET /database/categories?token=$TGSTAT_TOKEN lists valid category values you
can pass to channels/search. There are also /database/countries and
/database/languages. (See the docs for the full parameter/response shape.)
Gotchas
- Plan gating:
channels/searchneeds a Stat API tariff S or higher;channels/stat/channels/getwork on all Stat tariffs. If a call returns an access error, the user's plan doesn't cover that method. - Quota: each unique channel and each request counts against the monthly
tariff (visible via
usage/stat). Don't loop over hundreds of channels blindly — search, shortlist, thenstatonly the shortlist. qmin length is 3 chars →{"error":"param q is too short"}.- Cyrillic: always send
qvia--data-urlencode(or pre-URL-encode) so the keyword isn't mangled. - TGStat is a Russian service; the API and billing are RU-side — availability and payment are the account owner's responsibility.
Version History
- e0220ca Current 2026-07-05 22:56
