# Telegram Channel Scraper + Keyword Search (`puhmeisterluka/telegram-channel-scraper`) Actor

Scrape posts from public Telegram channels without a login. Search a channel's whole history by keyword, filter by date range, and schedule runs that return only new posts.

- **URL**: https://apify.com/puhmeisterluka/telegram-channel-scraper.md
- **Developed by:** [Luka Puhmeister](https://apify.com/puhmeisterluka) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 posts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Telegram Channel Scraper + Keyword Search

Get posts from public Telegram channels as JSON, CSV or Excel. No login, no phone number, no Telegram account.

- **Search by keyword inside a channel.** Uses Telegram's own search across the channel's whole history, with no Google dependency and no extra search costs.
- **Complete mode.** Reads every post in a date range and matches keywords itself, for when Telegram's search stops early.
- **Monitor mode with no bookkeeping.** Schedule it and each run returns only new posts. The Actor remembers where it stopped, per channel and keyword set. You never pass a cursor.
- **Both ends of a date range.** Set a start, an end, or both. An old date window jumps straight there instead of reading years of posts.

### What data does it return?

| Field | Example | Notes |
|---|---|---|
| `id` | `durov/551` | Stable, use it to de-duplicate |
| `channel` | `durov` | The username Telegram serves the post under |
| `requestedChannel` | `durov` | What you asked for. Differs when a channel has several usernames: `breakingmash` serves posts as `mash` |
| `messageId` | `551` | |
| `url` | `https://t.me/durov/551` | |
| `date` | `2026-10-10T14:22:43+00:00` | |
| `text` | `💸 If your wallet...` | Line breaks and emoji kept |
| `views`, `viewsRaw` | `2040000`, `2.04M` | Telegram rounds big numbers |
| `author` | `Pavel Durov` | The post signature, when the channel uses them |
| `isEdited` | `false` | |
| `isForwarded`, `forwardedFrom` | `true`, `{ "name": "Telegram Designers", "url": "https://t.me/designers/266", "author": null }` | `name` is empty when the source is hidden |
| `replyTo` | `{ "url": "...", "author": "...", "text": "..." }` | |
| `mediaType` | `video` | `photo`, `video`, `album`, `round_video`, `voice`, `audio`, `document`, `sticker`, `poll`, `unsupported` or empty for plain text |
| `photos` | `["https://cdn4.telesco.pe/..."]` | All photos of an album |
| `video`, `videos` | `{ "url": "...", "thumbnail": "...", "duration": "1:15" }` | `video` is the first one, `videos` lists all. `url` is empty when Telegram shows "Media is too big" |
| `document` | `{ "title": "...", "extra": "..." }` | Title only, Telegram does not expose the file |
| `voice` | `{ "url": "...", "duration": "0:03" }` | |
| `poll` | `{ "question": "...", "type": "Anonymous Poll", "voters": 21400, "options": [{ "text": "...", "percent": 13 }] }` | |
| `linkPreview` | `{ "url": "...", "siteName": "...", "title": "...", "description": "...", "image": "..." }` | |
| `reactions` | `[{ "emoji": "🤡", "emojiId": null, "count": 1420, "countRaw": "1.42K" }]` | Custom emoji have only an `emojiId`, the page does not show a character for them |
| `reactionsTotal` | `61260` | Sum of `reactions`, without paid stars |
| `paidStars` | `5` | |
| `hashtags`, `mentions`, `links` | `["AI"]`, `["durov"]`, `["https://..."]` | |
| `matchedKeywords` | `["wallet"]` | Empty when you did not set keywords |
| `channelTitle`, `channelSubscribers` | `Pavel Durov`, `10100000` | |
| `scrapedAt` | `2026-11-04T12:00:00+00:00` | |

Media URLs carry tokens and expire. Download the files you need soon after the run.

### How much does it cost?

Pay per event, with no subscription and no platform usage on top:

| Event | Price |
|---|---|
| Run start | $0.005 |
| Channel read | $0.002 per channel |
| Post returned | $0.0015 per post ($1.50 per 1,000) |

So 1,000 posts from one channel cost $1.507. A channel with no public preview costs nothing and is never billed as a result.

### Output example

One item from a real run, long texts shortened:

```json
{
  "id": "durov/552",
  "channel": "durov",
  "messageId": 552,
  "url": "https://t.me/durov/552",
  "date": "2026-10-11T14:52:40+00:00",
  "text": "✨ Designers × AI\n\n🆕 The mockup era is over. Today’s AI tools give every designer a superpower: you can now craft...",
  "views": 2670000,
  "viewsRaw": "2.67M",
  "author": "Pavel Durov",
  "isEdited": false,
  "isForwarded": true,
  "forwardedFrom": {
    "name": "Telegram Designers",
    "url": "https://t.me/designers/266",
    "author": null
  },
  "replyTo": null,
  "mediaType": "video",
  "photos": [],
  "video": {
    "url": null,
    "thumbnail": "https://cdn4.telesco.pe/file/E22fRJ-zY1kHBKt8IFVngVgh694n_petLTWDG_O2BDO9ItJyagQZntBhYBMi2OtjeNjZiXY09nD_NYw6V4B4ubOg...",
    "duration": "1:15"
  },
  "videos": [
    {
      "url": null,
      "thumbnail": "https://cdn4.telesco.pe/file/E22fRJ-zY1kHBKt8IFVngVgh694n_petLTWDG_O2BDO9ItJyagQZntBhYBMi2OtjeNjZiXY09nD_NYw6V4B4ubOg...",
      "duration": "1:15"
    }
  ],
  "document": null,
  "voice": null,
  "poll": null,
  "linkPreview": null,
  "reactions": [
    {
      "emoji": null,
      "emojiId": "5936157098181135162",
      "count": 20400,
      "countRaw": "20.4K"
    },
    {
      "emoji": null,
      "emojiId": "5399847211989246390",
      "count": 8680,
      "countRaw": "8.68K"
    },
    {
      "emoji": null,
      "emojiId": "5373223594484587136",
      "count": 6880,
      "countRaw": "6.88K"
    }
  ],
  "reactionsTotal": 35960,
  "paidStars": 10900,
  "hashtags": [],
  "mentions": [
    "designers"
  ],
  "links": [],
  "matchedKeywords": [],
  "scrapedAt": "2026-11-09T22:30:16+00:00",
  "channelTitle": "Pavel Durov",
  "channelSubscribers": 10100000,
  "requestedChannel": "durov"
}
```

### How to use it

1. Add **Channels**: a username, an @name or a t.me link.
2. Optional: add **Keywords**, a date range, or turn on **Only new posts**.
3. Set **Max posts per channel** so the run stops where you want it to.
4. Run, then download from the Dataset tab or pull results through the API.

### Input example

```json
{
  "channels": ["durov", "https://t.me/telegram"],
  "keywords": ["wallet"],
  "searchMode": "telegram",
  "dateFrom": "2025-01-01",
  "dateTo": "2026-06-30",
  "maxPostsPerChannel": 200,
  "onlyNew": false
}
```

### Telegram search or complete mode?

**Telegram search** (the default) is fast and reaches the whole history, because Telegram does the searching. It has two quirks. For very common words it can stop early: `telegram` in @durov returned 22 posts out of hundreds. It can also return a post where the word is not visible.

**Complete mode** reads every post and matches keywords at the start of a word, in the text and the link preview: `wallet` finds `wallets`, and `art` does not find `start`. It misses nothing but reads more pages, so use it with a date range. It stops after **Max pages to read per channel** (1,000 by default, about 20,000 posts) and notes that in the run's report.

### Monitor mode

Turn on **Only new posts** and put the Actor on a schedule.

- The first run returns the latest posts and sets the starting point.
- Later runs return only what is new, oldest first.
- If there are more new posts than **Max posts per channel**, or your Max total charge runs out, the rest comes in the next run. Nothing is skipped.
- Each channel and keyword set has its own position, kept in a key-value store named `telegram-channel-scraper-state` in your account. Delete a record there to start that channel over.

A run with nothing new still pays the run start and channel events.

### Use it from code

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("PuhmeisterLuka/telegram-channel-scraper").call(
    run_input={"channels": ["durov"], "keywords": ["wallet"], "maxPostsPerChannel": 100}
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["url"], item["text"])
```

Works the same from Node, Make, Zapier, n8n, or as an MCP tool for AI agents.

### FAQ

**Why is a channel missing from my results?**
Some channels turn off the public web preview, and `@bbcnews` is one. Those cannot be read without an account, so the Actor skips them and does not bill them. The run's status message names them, and the `CHANNELS` record in the run's key-value store has a line per channel with its status, subscriber count, description and post count.

**Why did I get fewer posts than Max posts per channel?**
The channel or the date range ran out, or your Max total charge was reached. You are only billed for posts delivered.

**Why are some posts empty?**
Telegram's web page shows "Please open Telegram to view this post" for some content. Those come back with `mediaType: "unsupported"`, plus their date, views and reactions. Service messages such as "Channel created" are skipped.

**Can it read private channels or groups?**
No. Public pages only, with no login.

**Does it need a proxy?**
No. Leave it off unless you see blocks.

**Is this legal?**
The Actor reads only pages anyone can open without an account. Check Telegram's terms and your local law for how you use the data, especially personal data under GDPR.

**Something broke?**
Open an issue on the Issues tab. Fixes usually ship within a day.

### More scrapers

Job boards in India, the Netherlands, Germany, Switzerland, Denmark, Poland, Singapore and the US, Remote OK, and any company's Ashby, Lever, Greenhouse, SmartRecruiters or ADP board: [all Actors by this developer](https://apify.com/puhmeisterluka).

# Actor input Schema

## `channels` (type: `array`):

Public channels to read. Use a username, an @name or a t.me link.

## `keywords` (type: `array`):

Optional. Return only posts that match at least one keyword. Leave empty to get every post.

## `searchMode` (type: `string`):

Telegram search is fast and covers the whole history, but it can stop early on very common words. Complete mode reads every post and matches keywords itself, so it misses nothing and takes longer. Use it with a date range.

## `dateFrom` (type: `string`):

Optional. Oldest day to include, in UTC.

## `dateTo` (type: `string`):

Optional. Newest day to include, in UTC.

## `maxPostsPerChannel` (type: `integer`):

Stop after this many posts from each channel. Keeps your bill predictable.

## `onlyNew` (type: `boolean`):

Remember the last post per channel and keyword set, so each scheduled run returns only what is new. The first run returns the latest posts and sets the starting point.

## `maxScanPagesPerChannel` (type: `integer`):

Complete mode stops reading a channel after this many pages. One page holds about 20 posts.

## `proxyConfiguration` (type: `object`):

Optional. Runs work without a proxy. Turn it on only if you see blocks.

## Actor input object example

```json
{
  "channels": [
    "durov"
  ],
  "searchMode": "telegram",
  "maxPostsPerChannel": 100,
  "onlyNew": false,
  "maxScanPagesPerChannel": 1000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `posts` (type: `string`):

One item per post in the default dataset.

## `channels` (type: `string`):

Status, post count and channel info for every requested channel. Channels with no public preview appear only here.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "channels": [
        "durov"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("puhmeisterluka/telegram-channel-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "channels": ["durov"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("puhmeisterluka/telegram-channel-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "channels": [
    "durov"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call puhmeisterluka/telegram-channel-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,puhmeisterluka/telegram-channel-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/prBmwdYie85QJRhpb/builds/uHRxRcOdHATIIBC72/openapi.json
