TGStat APIin.tgstat.com ↗
Search Telegram channels and groups, retrieve ranked lists, and fetch detailed channel profiles including subscriber counts and category metadata via the TGStat India API.
What is the TGStat API?
The TGStat India API exposes 4 endpoints for discovering and profiling Telegram channels and groups. Use search_channels to run full-text searches across Telegram with filters for country, category, and sort order, or call get_channel_profile to retrieve a channel's title, description, subscriber metrics, category, and geo/language metadata for any public Telegram handle.
curl -X POST 'https://api.parse.bot/scraper/ebf74fe8-f81a-4263-8013-8aa752ee2694/search_channels' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"page": "0",
"sort": "participants",
"query": "education",
"country": "8",
"category": "education"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tgstat-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TGStat SDK — search channels, view ratings, get profiles."""
from parse_apis.tgstat_api import TGStat, SearchSort, ChannelNotFound
client = TGStat()
# Search for education channels in India, sorted by subscribers
for ch in client.channelsummaries.search(query="education", country=8, sort=SearchSort.PARTICIPANTS, limit=5):
print(ch.name, ch.subscribers)
# Get top-rated channels in the education category
top = client.channelsummaries.rated(category="education", sort="members", limit=3).first()
if top:
print(top.name, top.handle, top.subscribers)
# Drill into full profile from a summary
profile = top.details()
print(profile.title, profile.metrics, profile.info)
# List top groups by members
for group in client.groupsummaries.rated(sort="members", limit=3):
print(group.name, group.handle)
# Handle a channel that doesn't exist
try:
missing = client.channelsummaries.search(query="zzz_nonexistent_xyz", limit=1).first()
if missing:
missing.details()
except ChannelNotFound as exc:
print(f"Channel not found: {exc.username}")
print("exercised: channelsummaries.search / channelsummaries.rated / details / groupsummaries.rated")Full-text search over Telegram channels with filters for country, category, and sort order. Returns a paginated list of channel summaries. Pagination advances via the integer page counter returned in nextPage. Each result includes the channel name, handle, and subscriber count but not full profile details — use get_channel_profile for those.
| Param | Type | Description |
|---|---|---|
| page | integer | Pagination page number (zero-based), use nextPage from previous response to get next page of results |
| sort | string | Sort order for results |
| query | string | Keyword to search for in channel name or description |
| country | integer | Country ID to filter results by (e.g. 8 for India, 1 for Russia). Omit to search globally. |
| category | string | Category name to filter by (e.g. education, cryptocurrencies, news) |
{
"type": "object",
"fields": {
"hasMore": "boolean indicating if more results are available",
"channels": "array of channel summary objects with name, handle, tgstat_id, and subscribers fields",
"nextPage": "integer page number for fetching next page of results",
"nextOffset": "integer offset for next page"
},
"sample": {
"data": {
"hasMore": true,
"channels": [
{
"name": "Rajasthan Vacancy Education News",
"handle": "@rajasthanvacancy_in",
"tgstat_id": null,
"subscribers": "575 265"
}
],
"nextPage": 1,
"nextOffset": 30
},
"status": "success"
}
}About the TGStat API
Search and Discovery
The search_channels endpoint accepts a query string and optional filters including country (integer ID, e.g. 8 for India), category (slug such as education or cryptocurrencies), and sort. Results are paginated: each response includes a hasMore boolean, a nextPage integer, and an array of channel objects containing name, handle, tgstat_id, and subscribers. Pass nextPage back as the page parameter to advance through results.
Channel and Group Rankings
get_ratings_channels returns a ranked list of top Telegram channels filtered by category and ordered by sort (supported values: members, reach). Each entry in the channels array carries the same summary shape as search results. get_ratings_groups works analogously for Telegram groups — two-way communication chats rather than broadcast channels — returning a groups array sorted by member count, with optional category filtering.
Channel Profile Detail
get_channel_profile takes a single username parameter (with or without the @ prefix) and returns the most granular data available: title, description, handle, tgstat_id, a url pointing to the TGStat profile page, and two open-schema objects. The metrics object holds subscriber count and other quantitative values whose keys vary by channel. The info object holds category, geo, and language metadata. Because both are open dictionaries, available keys depend on what TGStat has indexed for that channel.
The TGStat API is a managed, monitored endpoint for in.tgstat.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when in.tgstat.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official in.tgstat.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a Telegram channel discovery tool filtered by Indian category and subscriber threshold using
search_channelswith country ID 8. - Track ranking shifts for news or crypto channels week-over-week by polling
get_ratings_channelswith differentsortvalues. - Identify top Telegram groups in a niche category for community research using
get_ratings_groupswith acategoryfilter. - Enrich a CRM or influencer database with Telegram channel descriptions and subscriber counts via
get_channel_profile. - Compare reach vs. member-count rankings for the same category by calling
get_ratings_channelstwice withsort=reachandsort=members. - Automate alerts when new channels appear for a keyword by paginating
search_channelsand comparingtgstat_idsets over time.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TGStat have an official developer API?+
What does `get_channel_profile` return, and how complete is the data?+
title, description, handle, tgstat_id, a TGStat url, and two open-schema objects: metrics (subscriber count and other quantitative values) and info (category, geo, language). The available keys inside metrics and info vary by channel — fields are present only when TGStat has indexed them for that channel, so sparse profiles will return fewer keys.Can I filter search results by a specific country other than India?+
country parameter in search_channels accepts any integer country ID — pass 8 for India or 1 for Russia, for example. Omitting the parameter searches globally across all TGStat-indexed channels.Does the API return historical subscriber growth or post-level engagement data?+
How does pagination work for `search_channels`, and is there a limit on results per page?+
search_channels response includes a hasMore boolean and a nextPage integer. Pass nextPage as the page parameter in your next request to retrieve the following page. The API does not expose a configurable page-size parameter, so page size is fixed by the source.