tgstat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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})'

使用

curl + jq

调用TGStat Stat API。用户的token存储在

$TGSTAT_TOKEN

中，需在每次请求中作为

token

查询参数传递。基础URL：

https://api.tgstat.ru

。

响应格式为JSON：

{"status":"ok","response": ...}

。错误响应格式为

{"status":"error","error":"<message>"}

—— 需原样展示

error

内容。无效token或未激活/过期的API套餐会在此处显示；请告知用户前往TGStat个人中心检查token/套餐，并重新连接连接器。

请始终先确认token及剩余配额（

usage/stat

接口免费，不计入套餐配额）：

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

undefined

GET /channels/search

—— 至少需要

（关键词，最少3个字符）或

category

其中一个参数。

参数：

category

country

language

（默认值

russian

）,

peer_type

（

channel

chat

all

，默认值

channel

）,

search_by_description

（

）,

limit

（最大值100）。

bash

undefined

Russian-language AI/ChatGPT channels, biggest first.

俄语AI/ChatGPT频道，按规模从大到小排序。

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


- 使用`--data-urlencode ... -G`确保`q`中的西里尔字母/空格被正确编码。
- `ci_index`（индекс цитирования）是TGStat的引用/权威评分 —— 分数越高表示被转发/提及的次数越多，是除了订阅量之外的有用质量信号。
- 尝试多个关键词（`ChatGPT`, `нейросети`, `AI`, `разработка`, `API`）并合并结果；TGStat会匹配标题/用户名（添加`search_by_description=1`可同时匹配频道描述）。

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.

GET /channels/stat?channelId=<@username | t.me/username | tgstat id>

会返回对广告定价真正重要的数据：

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小时广告触达量 —— 计算CPM的关键指标
      er_percent, err_percent, err24_percent,
      daily_reach, ci_index, posts_count
    }'

用于估算广告CPM时，请使用
```
adv_post_reach_24h
```
（帖子在24小时内的平均广告触达量），而非原始订阅人数 —— 订阅量只是表面数据，触达量才是广告实际被看到的人数。
相对于订阅量，
```
err_percent
```
/
```
err24_percent
```
数值较低 = 受众注水/僵尸粉 → 请跳过该频道。
对于聊天群组（非频道），响应会包含
```
dau
```
/
```
wau
```
/
```
mau
```
和
```
messages_count_*
```
字段。

当你仅需识别/验证频道而非获取完整数据时，可调用

GET /channels/get?channelId=...

获取描述信息（标题、简介、

category

、

country

、

language

、

participants_count

、

ci_index

）。

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

GET /database/categories?token=$TGSTAT_TOKEN

会列出可传递给

channels/search

的有效

category

值。此外还有

/database/countries

和

/database/languages

接口。（完整的参数/响应格式请参考官方文档。）

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.

套餐限制：
```
channels/search
```
需要Stat API套餐S或更高版本；
```
channels/stat
```
/
```
channels/get
```
适用于所有Stat套餐。如果调用返回访问错误，说明用户的套餐不支持该接口。
**配额限制：**每个唯一频道和每次请求都会计入月度套餐配额（可通过
```
usage/stat
```
查看）。请勿盲目遍历数百个频道 —— 先搜索、筛选出候选列表，再仅对候选列表调用
```
stat
```
接口。
q
参数最小长度为3个字符 → 错误响应：
```
{"error":"param q is too short"}
```
。
**西里尔字母：**请始终通过
```
--data-urlencode
```
（或预先进行URL编码）传递
```
q
```
参数，避免关键词出现乱码。
TGStat是俄罗斯服务；API和计费均在俄罗斯境内 —— 服务可用性和支付事宜由账户所有者负责。