Telegram API & Scraper
This API reads public Telegram channels the way Telegram shows them to any visitor who is not logged in, and returns JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
No Telegram account, phone number or app is involved. `channel` returns the channel card: title, @username, description, photo, verified badge, the exact subscriber count (for example 10,145,770 where the channel page only says 10.1M) and the channel's photo, video, file and link counters; for a group it returns members and online counts. `posts` returns one page of about 20 posts, newest first, each with its id and link, date, edited flag, author signature, text with its links, hashtags and mentions, view count, every reaction with its count (paid Telegram Stars reactions marked), forwarded-from, the post it replies to, media (photos, videos with duration, documents, audio, voice messages, stickers, locations, each album item with its own post id), link preview, poll results and buttons. Page back with `next_before`. `search` runs Telegram's own search inside one channel, including #hashtags. `post` reads one post from its t.me link. `comments` returns the public comments under a post with each commenter's name, @username, text, reply and reactions.
What a Telegram field actually contains
Fields that read differently from how they look. Every row was measured against live Telegram pages on 2026-11-03.
| Field | What it holds |
|---|---|
| subscribers, subscribers_display | subscribers is the exact count Telegram prints on the channel's own page (10,145,770 for @durov). subscribers_display is the rounded figure of the post list ("10.1M"); subscribers_approx is that figure as a number. The exact count matched a separate read of the channel page on 8 of 8 channels (the largest moved by 8 subscribers between the two reads). |
| views, views_display, views_is_exact | Telegram prints views rounded above 999 ("5.87M", "54.7K"). views is that figure as a number, views_display the text as printed, views_is_exact false when the figure is rounded. Views and dates matched each post's own page on 16 of 16 posts; views grow while you read, so two reads minutes apart can differ. |
| reactions | One entry per reaction shown: the emoji, or custom_emoji_id for a custom emoji, paid true for Telegram Stars, count and count_display. reactions_total sums the non-paid counts and says whether that sum is exact. The first reaction's count matched each post's own page on 16 of 16 posts. |
| post_id, url | The number after the channel name in the post link (https://t.me/durov/531). Pass the link or channel + post_id to post; the same id, text and date came back on 16 of 16 posts. An album is one row; each photo or video in it carries its own post_id. |
| forwarded_from | is_forwarded is always set. The source channel's name and link are filled only when Telegram prints them; on 2026-11-03 Telegram left the name blank on most reads of the same forwarded post. |
| media[].url | A direct file link for photos and most videos, valid for a limited time. Telegram gives no file link for very large videos ("Media is too big") and for documents and audio: url is null there and the title, size or performer is returned. |
| hashtags, mentions, links | Only what Telegram itself links in the text: "Update #2" is not a hashtag in Telegram and is not returned as one. |
| region_withheld, viewer_region | Telegram hides some channels from visitors in some countries. region_withheld is true when the channel is one of them, and viewer_region names the country whose view of the channel the answer carries. Channels that are not withheld look the same from every country. |
Telegram withholds some channels per country: on 2026-11-03 rian_ru was hidden from German visitors and shown in the US, Canada, Turkey and Kazakhstan; rt_russian was hidden in the US, Canada and Germany and shown in Turkey and Kazakhstan. The posts of a channel that is not withheld were identical from five countries in the same minute.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/telegram/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"channel": "telegram",
"query": "update"
}
}{
"ok": true,
"meta": {
"api": "telegram",
"endpoint": "search",
"mode": "live",
"latency_ms": 681.4,
"record_count": 20,
"bytes": 129757,
"cache_hit": false,
"pagination": {
"next_before": 378,
"has_more": true
},
"upstream_requests": 1,
"charged_credits": 2,
"version": "0.1.0",
"request_id": "0c68687f0d2b4bc3",
"queue_ms": 3.2,
"fetched_at": "2026-11-03T13:40:19.286Z"
},
"data": {
"query": {
"channel": "telegram",
"query": "update",
"before": null
},
"channel": {
"title": "Telegram News",
"username": "telegram",
"description": "The official Telegram on Telegram. Much recursion. Very Telegram. Wow.",
"description_links": [],
"photo_url": "https://cdn1.telesco.pe/file/hnmFZVV6A1_vjW41WnRQI9LiY1404GFwcfT_HbWGXlPkZCJQr6yK31wcwJaRhyFUvrnsmXneFNxc3-olbF7UP_ezD8Aukc3IdB1-Rh0_7PSI-osS0bXY4ttXpC1hHPOWX-SZDSIJyEJcq4P6QvrpuXvwsq408sT9Ja-0iTpFkyZqe-onN2nh_D_CDOriOoVh7e-kHzpT2ctEJaVhVfw2cNA2Fyy1VDESyi7fMp_gFUZf5pjODz_s5UcIOEo0jyeVgyY-ZspgI2erawqK3zVPDNjVq0KmxUcZSujTiAB9w__o9XFeuZK9NZZnjKopOI_qUB12IUYqOCt_OcEkGyTbQg.jpg",
"verified": true,
"scam": false,
"subscribers_approx": 9200000,
"subscribers_display": "9.2M",
"counters": {
"photos": 16,
"videos": 228,
"files": null,
"links": 378
},
"url": "https://t.me/telegram"
},
"posts": [
{
"post_id": 460,
"channel": "telegram",
"url": "https://t.me/telegram/460",
"channel_id": 1005640892,
"date": "2026-08-26T19:12:34+00:00",
"edited": false,
"author_signature": null,
"channel_title": "Telegram News",
"text": "For all the info from today's update and a look back at 13 years of Telegram features — check out our blog:\nhttps://telegram.org/blog/welcome-messages-buttons-TG-13\n\nAugust Features\n1 • 2 • 3 • 4 • 5 • More",
"links": [
"https://telegram.org/blog/welcome-messages-buttons-TG-13",
"https://t.me/telegram/455",
"https://t.me/telegram/456"
],
"hashtags": [],
"cashtags": [],
"mentions": [],
"views": 2290000,
"views_display": "2.29M",
"views_is_exact": false,
"reactions": [],
"reactions_total": null,
"reactions_total_is_exact": null,
"paid_stars": null,
"is_forwarded": false,
"forwarded_from": null,
"reply_to": null,
"media": [],
"link_preview": {
"url": "https://telegram.org/blog/welcome-messages-buttons-TG-13",
"site_name": "Telegram",
"title": "Welcome Messages, Buttons in Messages and Signed Gifts",
"description": "Introducing Welcome Messages to greet new members of groups or channels, Buttons in Messages to make any text interactive, Inline Documents in Messages and much more.",
"image": "https://cdn4.telesco.pe/file/F2P1VroQynemZqaz9u4XMw4e-Ot8POcgM7MZ42w_DmSClUKCE26IV7WX43jByz1h15eWyk8INeSDccx-721EsIManHHPhXdq27C6dNHQihizAy7PP810WkfuBOrBVTzgtMVmXOJcYa6gRBqc_wy43pWu81WMJBCYQVWdaLg5Il3Zqd20-BBXr514jj1l6OGNxHFpkPx0XNTIhLa5aiMeozcHfOYpjEA0YN6QBiCmewlYwdqDrmMZild4vWIHSU6ydRCkxt-aG8YrhqRgWT4UkIEHd8ke25EZVm_YUkQ9o-6IZKV31-3G41FQ-HvK40ko6DHdt5shLq_VFX34vesm8g.jpg",
"video": null
},
"poll": null,
"inline_buttons": [],
"is_service": false
},
{
"post_id": 458,
"channel": "telegram",
"url": "https://t.me/telegram/458",
"channel_id": 1005640892,
"date": "2026-08-26T19:12:04+00:00",
"edited": false,
"author_signature": null,
"channel_title": "Telegram News",
"text": "Placeholders for App Updates. If a user with an outdated app encounters a new feature, they can now instantly tap to download the latest update.\n\nAugust Features\n1 • 2 • 3 • 4 • 5 • More",
"links": [
"https://t.me/telegram/455",
"https://t.me/telegram/456",
"https://t.me/telegram/457"
],
"hashtags": [],
"cashtags": [],
"mentions": [],
"views": 1250000,
"views_display": "1.25M",
"views_is_exact": false,
"reactions": [],
"reactions_total": null,
"reactions_total_is_exact": null,
"paid_stars": null,
"is_forwarded": false,
"forwarded_from": null,
"reply_to": null,
"media": [
{
"type": "[trimmed-depth]",
"url": "[trimmed-depth]",
"thumbnail": "[trimmed-depth]",
"post_id": "[trimmed-depth]",
"duration": "[trimmed-depth]",
"duration_seconds": "[trimmed-depth]"
}
],
"link_preview": null,
"poll": null,
"inline_buttons": [],
"is_service": false
},
{
"post_id": 449,
"channel": "telegram",
"url": "https://t.me/telegram/449",
"channel_id": 1005640892,
"date": "2026-06-18T14:36:06+00:00",
"edited": false,
"author_signature": null,
"channel_title": "Telegram News",
"text": "For all the features from this update, like links in poll options, support for .md files and new browser settings – check out the full blog:\nhttps://telegram.org/blog/watch-apps-and-more\n\nJune Features\n1 • 2 • 3 • More",
"links": [
"https://telegram.org/blog/watch-apps-and-more",
"https://t.me/telegram/446",
"https://t.me/telegram/447"
],
"hashtags": [],
"cashtags": [],
"mentions": [],
"views": 2570000,
"views_display": "2.57M",
"views_is_exact": false,
"reactions": [],
"reactions_total": null,
"reactions_total_is_exact": null,
"paid_stars": null,
"is_forwarded": false,
"forwarded_from": null,
"reply_to": null,
"media": [],
"link_preview": {
"url": "https://telegram.org/blog/watch-apps-and-more",
"site_name": "Telegram",
"title": "Smartwatch Apps, Rich Text for Bots, AI Guardians for Groups, and Much More",
"description": "Today’s update brings Telegram to Apple Watch and Android smartwatches, adds filthy rich text for bots, lets AI admins screen new group members, and introduces smarter polls, browser controls, and much more.",
"image": "https://cdn4.telesco.pe/file/Op5uL-secO36R4a_Lf3-bfkuMJw0qiHUPAcflerAezYFcBwOW_tSZmiKu3iQUoAbLaztAvnSBPO4CzeFjBxVurKItQNgf7qQvrgkfcTnKiSiMpfYc6jEDfE9R86_Tbx78M3icWCEok73tcVw9zKTMcVyZByAHA11kRlwzczQaxfs0QAibKz1jYb-fuCnoleFV6Z6QE_EhOlUNisTfFP_2f7e9xYpx4DunMUhon-7L0xz-rFXGFtiZxr46g8Ek26t5xZzkpdGJ0gKZXDkEz9rsX8V4A8EAq6pl5k_FC00_j9iCCD4-UQrqMntFsy05s7Npq-G--GdX5jUy6GvwZwHVg.jpg",
"video": null
},
"poll": null,
"inline_buttons": [],
"is_service": false
}
],
"next_before": 378,
"has_more": true,
"region_withheld": false,
"viewer_region": null,
"total_is_exact": false,
"results_cap": 22
}
}What the Telegram API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| channel | Channel card for a public Telegram username: title, @username, description (+ its links), photo URL, verified badge, the EXACT subscriber count as Telegram prints it on t.me/<channel> (e.g. 10 146 005, where the preview only says 10.1M), and the preview's media counters (photos, videos, files, links). If the username is a group the card carries members and online counts; a user or bot is recognised too (`type`), with `preview_available: false`. | Social-listening tools call channel to get channel card for a public Telegram username. | channel |
| posts | One page of a public channel's posts as Telegram's web preview serves it (about 20 posts; an album counts as one), newest first. Page back with `before` (the `next_before` of the previous answer) or forward with `after`. Each post: id, URL, date, edited flag, author signature, text with its links / hashtags / mentions / cashtags, views, reactions (emoji or custom-emoji id, paid Stars, count), forwarded-from, reply-to, media (photos, videos with duration, documents, audio, voice, stickers, locations; album items with their own post ids), link preview, poll, inline URL buttons. The channel card (rounded subscriber count + media counters) comes with every page. | Creator and influencer platforms call posts to get one page of a public channel's posts as Telegram's web preview serves it (about 20 posts; an…. | channel, before, after |
| search | Telegram's own search inside one public channel (`q`; a `#hashtag` finds that hashtag). Same post rows as `posts`, newest first: 20 on the first page and the rest on the page `next_before` points to. Telegram's channel search stops at the 22 newest matching posts (measured on 4 queries in 4 channels: 20 + 2, then no more page, and older `before` values return nothing) and publishes no total; to reach older matches, walk `posts`. | Brand-monitoring teams call search to get telegram's own search inside one public channel (`q`; a `#hashtag` finds that hashtag). | channel, query, before |
| post | One post by its t.me URL (https://t.me/durov/531) or channel + post_id: the same row as `posts` plus the channel's verified flag. A deleted or never-existing post is NOT_FOUND. | Audience analysts call post to get one post by its t.me URL (https://t.me/durov/531) or channel + post_id. | url, channel, post_id |
| comments | Public comments under a channel post (the channel's linked discussion, as Telegram's comments widget shows it): newest `limit` comments, then older ones with `cursor` = the previous answer's `next_cursor`. Each comment: id, date, author name / @username / link / photo, text, links, reply-to (comment id, author, quoted text), reactions, media. Posts whose channel has no public discussion answer `comments_available: false` with 0 rows. | Social-listening tools call comments to get public comments under a channel post (the channel's linked discussion, as Telegram's comments…. | url, channel, post_id, limit, cursor |
Call search from your stack
curl -X POST https://api.reefapi.com/telegram/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"channel":"telegram","query":"update"}'import requests
r = requests.post(
"https://api.reefapi.com/telegram/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"channel": "telegram",
"query": "update"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/telegram/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"channel": "telegram",
"query": "update"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.telegram.search with {"channel":"telegram","query":"update"}.Who uses this API and why
- Monitor news, crypto and brand channels: new posts with views and reactions every few minutes.
- Track a channel's growth with the exact subscriber count, day by day.
- Search a channel for a keyword or #hashtag and collect every matching post with its link.
- Collect the public comments under a post for sentiment or moderation work.
- Archive a channel's history with its media links, polls and link previews, page by page.
Questions developers ask before integrating
Do I need a Telegram account or an API ID?
No. Everything is read from Telegram's public channel pages, logged out. You call reefapi.com with your ReefAPI key.
Which channels can I read?
Public channels that have an @username and whose web preview is on. Private channels, invite links (t.me/+...) and group chats have no public page; a group returns its card (members, online) from channel, and posts answers NOT_FOUND saying it is a group.
How do I get a channel's full history?
Call posts, then call it again with before = next_before until has_more is false. Each page holds about 20 posts (10 to 20 measured, an album counts as one); three pages back on two channels had no post twice.
Are view counts exact?
Telegram rounds them above 999 ("5.87M"), and so does every tool that reads the public page. We return the number, the text as printed and a flag saying whether it is exact. Subscriber counts are exact in the channel action.
Can I search a channel?
Yes, with Telegram's own search: words or a #hashtag, newest first. Telegram's channel search returns the 22 newest matching posts (20, then 2 on the next page) and no total: measured on four queries in four channels. "#сбои" in @tginfo returned 20 posts on the first page, 19 carrying the tag. For older matches, walk posts page by page.
Do you return comments?
Yes, when the channel has public comments: the newest 1 to 100, then older pages of 50 with next_cursor. Each comment has its id, date, author name, @username and photo, text, the comment it replies to and its reactions. Channels without public comments answer comments_available false.
Can I get the list of subscribers or who reacted?
No. Telegram does not publish them on any public page.
Do media links last?
Photo and video links are Telegram's own CDN links and carry a token; download what you need soon after the call, or call again for a fresh link.
What is the Telegram API?
Telegram API is a ReefAPI endpoint group for public telegram channels as json: posts with views, reactions and media, in-channel search, single posts, comments and exact subscriber counts. It returns live JSON through POST requests under /telegram/v1.
Is the Telegram API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Telegram calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Telegram login or account?
No login to Telegram is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Telegram data?
The page example is captured from a live channel call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Telegram API use?
Telegram actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Telegram from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call telegram actions with the same key, credit pool and JSON envelope used by normal REST requests.