tgstat

Original：🇺🇸 English

Translated

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.

14installs

Sourceacedatacloud/skills

Added on2026-07-04

NPX Install

npx skill4agent add acedatacloud/skills tgstat

SKILL.md Content

View Translation Comparison →

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):

bash

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

(keyword, min 3 chars) or

category

is required.

Params:

,

category

,

country

,

language

(default

russian

),

peer_type

(

channel

|

chat

|

all

, default

channel

),

search_by_description

(

/

),

limit

(max 100).

bash

# 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 ... -G
```
so Cyrillic / spaces in
```
q
```
are 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 (add
```
search_by_description=1
```
to 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:

bash

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_percent
```
relative to subs = inflated/dead audience → skip it.
For a chat (not channel) the response instead has
```
dau
```
/
```
wau
```
/
```
mau
```
and
```
messages_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/search
```
needs a Stat API tariff S or higher;
```
channels/stat
```
/
```
channels/get
```
work 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, then
```
stat
```
only the shortlist.
q
min length is 3 chars →
```
{"error":"param q is too short"}
```
.
Cyrillic: always send
```
q
```
via
```
--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.

tgstat

NPX Install

Tags

SKILL.md Content

Find channels to advertise in (the main workflow)

Judge a channel's ad value

Reference data

Gotchas