Telegram Channel Scraper: Posts + Media + Metadata

📦 Telegram Channel Scraper: Posts + Media + Metadata

📊 Find out how well any Telegram channel really performs — and what its audience reacts to.

Paste up to 25 public channels — yours or your competitors' — and in a few minutes you get:

• Every post with its numbers: views, ER, reactions, forwards, comments, text and links
• Photos, videos and files from every post — as links, or downloaded to storage with direct URLs (merge albums into one record if you like)
• A ready-made report for each channel: average reach, average ER, engagement rate, posts per day and the top post
• A table you can export to Excel, CSV or JSON, or send to Google Sheets, Make or Zapier

No Telegram account, API key or phone number needed — just enter channel names and click Start.

Who it's for: marketers and SMM specialists checking competitors, advertisers choosing channels before buying ads, analysts and researchers tracking topics and trends.

🆕 Updated on October 16, 2026: engagement analytics — er, forwards, comments and pinned on every post, and a free per-channel summary (CHANNEL_STATS). Nothing changed in existing fields.

💰 No monthly fee. $0.01 per run, $10 per 1,000 posts, $5 per 1,000 downloaded media files. Channel stats, errors, queue time and service records are free. Details below in Pricing.

---

🆕 What's new (2026-10-16)

• ✅ Engagement on every post: forwards (how many times the post was shared), comments (number of comments), er (views ÷ subscribers, %), pinned
• ✅ Channel stats (CHANNEL_STATS) — one summary per channel: average views, average ER, engagement rate, posts per day, average reactions, forwards and comments, top post and last post date. Free, no extra charge
• ✅ Output tab: new ER, Forwards and Comments columns, and a Channel stats link
• ✅ Existing fields, record count and input are unchanged — your automations keep working

---

💰 Pricing — pay only for what you use

What	Price
Run start (charged only after a successful connection to Telegram)	$0.01
Post	$10.00 / 1,000 posts
Downloaded media file (only when downloadMedia is on)	$5.00 / 1,000 files
Channel stats (CHANNEL_STATS)	Free
Platform usage	Included

There is no monthly fee. Since October 12, 2026, the former $9/month rental has been replaced by this pay-per-event pricing.

You are never charged for:

• time in the queue, queue timeouts, or failed connections to Telegram;
• service records — "no posts found", channel errors, rate-limit notices, skipped channels;
• media left as a link (files over maxMediaSizeMB, or when downloadMedia is off);
• the channel stats summary.

Control your spending: set Max cost per run in the run options — the Actor stops cleanly when the limit is reached.

Examples

• 10 channels × 20 posts, text only → $0.01 + 200 × $0.01 = $2.01
• 5 channels × 50 posts, 120 media files downloaded → $0.01 + $2.50 + $0.60 = $3.11

---

✅ What This Actor Does

• Connects to Telegram automatically (no credentials needed from your side)
• Parses public channels (by username or t.me link), up to 25 channels per run
• For each post:
  • text, date, post URL
  • views, ER (views ÷ subscribers), reactions (with emoji breakdown + total), forwards, comments, pinned
  • forward source: isForward, forwardFromType, forwardFromId, forwardFromName, forwardChannelPost, forwardPostAuthor, forwardDate
  • hashtags & mentions (Unicode-aware — supports Cyrillic, e.g. #вакансия)
  • links from the post text, edit date, reply chain (replyToMsgId, replyToPostUrl)
  • media: photos, videos, documents — as t.me links, or downloaded with direct URLs (.jpg, .mp4, .pdf, etc.)
• For each channel: title, description, subscribers, and the channel stats summary
• Handles:
  • Albums — one record per message by default, or one record per album with groupAlbums
  • Telegram FloodWait limits gracefully (with an explanatory record in the dataset)
  • Cross-run conflicts via a per-session queue (see "Queue Behavior" below)
• Channels you've scraped before are remembered, so repeat monitoring is faster and avoids Telegram lookup limits
• Starts from the most recent post and works backwards

---

🧾 Input

You don't need to enter any credentials — they're already preconfigured.

Field	Type	Required	Default	Description
channels	string	✅	—	Channel usernames or links, separated by commas or new lines (e.g. @channel1, https://t.me/channel2)
maxPosts	number	❌	10	Max number of Telegram messages per channel (1–200)
daysRange	number	❌	3	Number of days to look back from today (1–30)
includeText	boolean	❌	true	Whether to include post text in the output
mediaOnly	boolean	❌	false	If true, skip posts that have no photos, videos or files
downloadMedia	boolean	❌	false	If true, download media files into the run's Key-Value Store
maxMediaSizeMB	number	❌	50	Files larger than this stay as t.me links (not downloaded). 0 = no limit
groupAlbums	boolean	❌	false	If true, merge an album into one record: all files in mediaUrls, all message ids in groupedPostIds. With merging on you may get fewer records than maxPosts, because maxPosts counts Telegram messages

📌 Example input — weekly competitor check

{
  "channels": "@competitor1, https://t.me/competitor2, competitor3",
  "maxPosts": 50,
  "daysRange": 7,
  "includeText": true,
  "mediaOnly": false,
  "downloadMedia": false,
  "groupAlbums": false
}

⚠️ Channel limits per run. Up to 25 channels per run, of which up to 10 new channels (not scraped by this Actor before). Previously scraped channels are remembered and don't need a Telegram lookup, so they don't count toward the 10. Channels over the limit are listed in the run status and saved as type: "skipped" records — just run them again.

---

▶️ How to Run

1. Open the Actor in Apify Console
2. Fill in the input fields
3. Click Save, then Start
4. Watch the run status — it shows queue waiting time, progress, and a final summary
5. Open the Output tab:
   • Posts — all posts with engagement metrics
   • Channel stats — one summary per channel
   • Downloaded media files — when downloadMedia is on
   • Run summary

To monitor channels regularly, save your input as a Task and add a Schedule (for example, every Monday).

---

📤 Output

Posts (dataset)

Each Telegram message (or each album, with groupAlbums: true) is a separate record. Every record has a type field:

type	Meaning	Charged
post	A post with content	✅
no_posts	Channel has no posts in the selected period	❌
skipped	Channel postponed (per-run limit or temporary Telegram limit) — run it again	❌
telegram_rate_limit	Telegram asked to slow down; includes waitSeconds	❌
channel_error	Channel not found, private, or another error	❌

To get only content, filter by type = "post".

{
  "type": "post",
  "channel": "@channel_name",
  "channelLink": "https://t.me/channel_name",
  "channelTitle": "Channel Display Name",
  "channelDescription": "Channel about / bio text",
  "postId": 101,
  "postUrl": "https://t.me/channel_name/101",
  "date": "2026-10-15T17:31:01.000Z",
  "views": 8263,
  "subscribers": 330421,
  "er": 2.5,
  "text": "Example post content with #hashtag and @mention",
  "reactions": [
    { "emoji": "❤", "count": 31 },
    { "emoji": "🔥", "count": 12 }
  ],
  "totalReactions": 43,
  "forwards": 41,
  "comments": 3,
  "pinned": false,
  "links": ["https://example.com"],
  "hasMedia": true,
  "mediaUrls": ["https://t.me/channel_name/101"],
  "mediaTypes": ["jpg"],
  "groupedPostIds": [101],
  "isForward": false,
  "forwardFromType": "",
  "forwardFromId": "",
  "forwardFromName": "",
  "forwardChannelPost": 0,
  "forwardPostAuthor": "",
  "forwardDate": "",
  "hashtags": ["#hashtag"],
  "mentions": ["@mention"],
  "editDate": "",
  "replyToMsgId": 0,
  "replyToPostUrl": ""
}

Channel stats (CHANNEL_STATS, free)

Saved in the run's Key-Value Store and linked on the Output tab. One object per channel that returned posts:

{
  "channel": "@channel_name",
  "channelLink": "https://t.me/channel_name",
  "channelTitle": "Channel Display Name",
  "subscribers": 330421,
  "postsAnalyzed": 12,
  "basedOn": "all posts",
  "periodDays": 1.04,
  "postsPerDay": 11.57,
  "avgViews": 5541,
  "avgEr": 2.5,
  "engagementRate": 1.74,
  "avgReactions": 51.58,
  "avgForwards": 40.75,
  "avgComments": 3.83,
  "topPostUrl": "https://t.me/channel_name/72686",
  "topPostViews": 8263,
  "lastPostDate": "2026-10-16T18:00:01.000Z"
}

What the metrics mean

Field	Meaning
er	Views ÷ subscribers, in %. Fresh posts are still gaining views, so their ER is lower
forwards	How many times the post was forwarded (shared)
comments	Number of comments. 0 if the channel has comments turned off
avgEr	Average ER of the channel's posts. Posts younger than 24 hours are left out when older posts exist, so the number isn't pulled down by fresh posts
engagementRate	(reactions + forwards + comments) ÷ views, in % — how actively readers interact
postsPerDay	Posts per day over periodDays
periodDays	The period the stats cover: your daysRange, or — if maxPosts was reached first — the time from the oldest returned post to now
postsAnalyzed	Posts in the summary. An album always counts as one post here, even with groupAlbums off
basedOn	all posts, or media posts only when mediaOnly is on
topPostUrl, topPostViews	The most-viewed post in the period

The summary is built from the posts returned in this run. For a fuller picture, raise maxPosts and daysRange. If Telegram doesn't return a subscriber count, er and avgEr are 0.

Run summary (RUN_SUMMARY)

{
  "posts": 42,
  "channelsProcessed": 3,
  "mediaDownloaded": 0,
  "mediaSkippedLarge": 0,
  "postponedChannels": [],
  "failedChannels": [],
  "costLimitReached": false,
  "channelStats": 3
}

---

⏳ Queue Behavior (Important for parallel users)

The Actor uses a shared Telegram session preconfigured by the author. Telegram allows only one active connection per session at any time — if multiple users run the Actor simultaneously, the second connection would get AUTH_KEY_DUPLICATED.

To prevent this, the Actor uses a cross-run lock: parallel runs are automatically queued and processed one at a time.

What this means in practice:

• If no one else is running the Actor → starts immediately
• If another user is currently scraping → your run waits in queue, and the run status shows how long you've been waiting
• A typical wait is a few minutes (depends on what the previous run is doing)
• Maximum queue wait is 15 minutes, after which the run fails with a clear message. You are not charged for waiting

---

🛡️ Telegram Rate Limit Handling

If Telegram returns a FloodWait on contacts.ResolveUsername (too many lookups of new channel usernames in a short period), the Actor:

1. Stops looking up new channels for the rest of this run, to protect the session
2. Keeps processing channels you've scraped before — they don't need a lookup
3. Adds a telegram_rate_limit record with the wait duration (waitSeconds) and a clear explanation
4. Retry the skipped channels after the indicated time (often 10–11 hours)

For any other very long FloodWait (1 hour or more), the run stops early to protect the session and reports it in the dataset and run status.

---

🛠 Use Cases

• Competitor monitoring — compare reach, ER and posting frequency across channels every week
• Choosing channels for ads — check real reach (avgEr) and audience activity (engagementRate) before you buy
• Content analytics — find the posts that get the most views, forwards and comments
• Market and trend research — track topics through hashtags, mentions and links
• Forward chain analysis — see which posts get republished and where they came from
• Dataset building for AI/ML models (with hashtags and mentions as labels)

---

📜 Changelog

2026-10-16

• ✅ New post fields: forwards, comments, er, pinned
• ✅ New free CHANNEL_STATS summary per channel (average views, average ER, engagement rate, posts per day, average reactions, forwards and comments, top post)
• ✅ RUN_SUMMARY.channelStats — number of channels with a summary
• ✅ Output tab: ER, Forwards and Comments columns; Channel stats link
• ✅ Existing fields, record count, input and pricing unchanged

2026-10-12

• ✅ Pay-per-event pricing is live: no monthly fee — $0.01 per run start, $10 per 1,000 posts, $5 per 1,000 downloaded media files
• ✅ Queue waits, failed connections and service records are free

2026-09-28

• ✅ Pay-per-event pricing announced, effective 2026-10-12 (no monthly fee; service records, queue waits and failed connections will be free)
• ✅ Channel cache: previously scraped channels skip contacts.ResolveUsername (the main cause of FloodWait); each channel is now resolved once per run instead of twice
• ✅ Up to 25 channels per run, max 10 new ones; channels over the limit are reported as type: "skipped" instead of being silently dropped
• ✅ FloodWait on new-channel lookups no longer stops already-known channels
• ✅ Run status messages: queue waiting time, progress per channel, final summary
• ✅ RUN_SUMMARY record in the Key-Value Store
• ✅ type field on every record (post, no_posts, skipped, telegram_rate_limit, channel_error)
• ✅ channels accepts t.me links (incl. /s/ and post links) and new-line separation; duplicates removed
• ✅ New groupAlbums option (off by default) and groupedPostIds field
• ✅ New maxMediaSizeMB option (default 50 MB)
• ✅ Link previews no longer counted as media (hasMedia, mediaUrls)
• ✅ Respects the Max cost per run limit
• ✅ Clearer error messages for invalid, private and non-channel usernames

2026-05-03

• ✅ Added channel metadata (channelTitle, channelDescription)
• ✅ Added forwards detection (7 new forward* fields)
• ✅ Added hashtags + mentions extraction
• ✅ Added editDate and reply chain fields (replyToMsgId, replyToPostUrl)
• ✅ Cross-run lock now uses author-scoped Apify token, so the queue works for all users (not only the Actor owner)
• ✅ Replaced silent exit handling with explicit Actor.fail() so errors are visible in run status
• ✅ Added 15-second timeout on Telegram getMe() to prevent multi-minute hangs on dead sessions
• ✅ Disabled autoReconnect to fail fast and surface real errors

2025-12-05

• ✅ Added explicit handling and logging for Telegram contacts.ResolveUsername FloodWait errors
• ✅ When Telegram returns a FloodWait, the Actor now stops processing further channels in that run and adds a telegram_rate_limit record to the dataset with a human-readable explanation
• ✅ Limited the number of channels processed per run to 10 to reduce the risk of hitting global FloodWait on the shared Telegram session
• ✅ Updated input description to recommend no more than 10 channels per run and documented this behavior in the README

2025-10-10

• ✅ Fixed AUTH_KEY_DUPLICATED by adding a per-session lock (prevents concurrent reuse of the same Telegram auth key)
• ✅ Improved error messages for session conflicts
• ✅ Internal stability tweaks for Telegram requests and media downloads

---

❓ Troubleshooting

Empty results / type: "no_posts"

• Increase daysRange to 7..14 — the channel may not have posts in the default 3-day window
• Increase maxPosts to 20..50
• Make sure the channel is public and the username is correct

comments is always 0

• The channel has comments turned off (no discussion group). This is normal

ER looks low for the newest posts

• Fresh posts are still gaining views. Use avgEr in Channel stats — it leaves out posts younger than 24 hours

type: "skipped" records / channels "not processed" in the run status

• The run hit the per-run channel limits — run again with just those channels

type: "channel_error"

• The channel may be private, deleted, a user or bot rather than a channel, or an invite link (t.me/+...), which isn't supported

Run waits 5+ minutes in queue

• Another user is currently using the Actor; this is normal under load
• Retry in a few minutes when the queue clears

telegram_rate_limit record in dataset

• Telegram applied a FloodWait — wait the indicated number of hours before retrying the skipped channels
• Channels you've scraped before are not affected

Run failed with AUTH_KEY_DUPLICATED

• Should not happen with the built-in queue, but if it does — wait 10 minutes and retry

---

⚠️ Telegram Albums

Telegram delivers an album (several photos/videos with one caption) as several separate messages, one file each, with the caption on one of them.

By default (groupAlbums: false) the Actor returns them as Telegram delivers them — one record per message. They share the same date and have consecutive postId values.

With groupAlbums: true the Actor merges them into one record:

• text — the album's caption
• mediaUrls / mediaTypes — all files of the album
• groupedPostIds — ids of all messages in the album
• postId / postUrl — the first message of the album

In Channel stats, an album always counts as one post, whichever setting you use.

---

🔐 License & Usage

This Actor is a proprietary paid product.

• ❗ It is not open source
• 📦 It is licensed for private and commercial use by users of this Actor
• 🛑 Any unauthorized copying, reselling, or redistribution is strictly prohibited
• 🧑‍💻 All activity is logged for abuse prevention and fair use enforcement

To report a bug, please open an issue — I respond quickly.

---

Made with 💙 for Telegram research & automation.