# Telegram Keyword Search: Find Posts Across Channels (`precious_bathmat/telegram-keyword-search`) Actor

Search public Telegram channels for any keyword, brand or ticker: matching posts with views, dates and links, plus a report per keyword with mentions by channel, a 30-day timeline and top posts. Built-in crypto, news, markets and tech channels. No account.

- **URL**: https://apify.com/precious_bathmat/telegram-keyword-search.md
- **Developed by:** [Mariam Ahmed](https://apify.com/precious_bathmat) (community)
- **Categories:** Social media, Marketing
- **Stats:** 2 total users, 1 monthly users, 87.5% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 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 Keyword Search: Find Posts Across Channels

Search **public Telegram channels for any keyword**: a brand, a coin or ticker, a product, a person in the news or a topic. No Telegram account, no phone number, no API key. You get:

- **Every matching post**: channel, subscribers, date, full text, **views**, views per subscriber, photo / video, forwarded-from, link preview, and an **exact-match flag**
- **A report per keyword**: mentions and **share of voice by channel**, total and median views, mentions in the **last 24 hours / 7 days / 30 days**, a **30-day daily timeline**, top posts by views and the latest posts
- **A built-in directory of 34 large public channels** checked to be searchable (crypto, world news, markets, tech), or **your own channel list**

### What does this Telegram keyword search do?

```
"AI" · 34 channels searched · 26 mention it · 296 posts in 30 days
 5.6M views · top: @durov 1.48M views · Watcher Guru, Insider Paper, Walter Bloomberg lead
```

1. Enter **keywords**.
2. Add **channels** ("@cointelegraph", "t.me/WatcherGuru") or leave empty to search the **built-in directory** (pick topics if you like).
3. Choose a **time window**, and optionally **scan recent history** for complete counts on busy channels.

```mermaid
flowchart LR
    A[Keywords] --> C[Search box of<br/>each channel]
    B[Your channels or<br/>the directory] --> C
    C --> D[Up to ~22 newest<br/>matches per channel]
    B --> E[Optional: scan the<br/>channel's latest posts]
    E --> F[Match every<br/>keyword locally]
    D --> G[Posts]
    F --> G
    G --> H[Report<br/>share of voice,<br/>timeline, top posts]
```

### Who is it for?

- **Crypto teams and traders**: who is talking about a coin, an airdrop or a listing, how often and with how many views
- **Brand and PR teams**: mentions of a brand or product across news and community channels
- **Market researchers and journalists**: how a story spreads across channels day by day
- **Agencies**: share of voice for a client against competitors, on a schedule

### What data do you get?

**Posts** (dataset, one row per matching post)

| Field | What it tells you |
|---|---|
| `keyword`, `exactMatch` | The search, and whether the exact keyword is in the text (Telegram also matches word forms) |
| `channelUsername`, `channelTitle`, `channelSubscribers` | Where it was posted |
| `postUrl`, `publishedAt`, `text`, `linkPreviewTitle` | The post |
| `views`, `viewsPerSubscriberPercent` | Reach |
| `hasPhoto`, `hasVideo`, `forwardedFrom` | Format and origin |

**Report** (`REPORTS`, one per keyword)

| Field | What it tells you |
|---|---|
| `channelsSearched`, `channelsMentioning`, `mentions`, `exactMentions` | How widely it is mentioned |
| `mentionsLast24h`, `mentionsLast7d`, `mentionsLast30d`, `firstMentionAt`, `lastMentionAt` | How recent |
| `totalViews`, `medianViews` | How far it travelled |
| `byChannel` | Mentions, share of voice, views and last mention per channel, and `searchCapped` where Telegram's search limit was hit |
| `last30Days`, `topPosts`, `latestPosts` | Daily timeline and the posts behind it |

### Example: 25 October 2026

**Built-in directory, last 30 days, five keywords**: 692 posts and 5 reports in 202 seconds, no proxy needed.

| Keyword | Channels mentioning (of 34) | Posts | Last 7 days | Total views | Most-viewed post |
|---|---|---|---|---|---|
| AI | 26 | 296 | 148 | 5.6M | @durov, 1.48M views |
| ETF | 14 | 149 | 48 | 1.2M | @WatcherGuru, 165K views |
| Ukraine | 9 | 143 | 94 | 1.2M | @WatcherGuru, 107K views |
| Tesla | 17 | 88 | 46 | 1.7M | @nexta_live, 197K views |
| airdrop | 4 | 16 | 7 | 187K | @binance_announcements, 58.5K views |

**Five market channels, last 7 days, with "Scan recent history" at 40 pages**: "Fed" 51 posts (Market News Feed 28, FinancialJuice 18), "Tesla" 38, "ETF" 17, in 124 seconds.

### Pricing

**$0.001 per post saved** and **$0.01 per keyword report**.

- One keyword across the directory, last 30 days (about 100-300 posts): **$0.11 to $0.31**
- The first run above (692 posts, 5 reports): **$0.74**
- Reports only, posts capped at 5 per channel: about **$0.02 to $0.10 per keyword**

### Good to know

- **No global Telegram search exists without an account.** Only the channels you list, plus the directory if on, are searched, and only channels whose owner **switched on the public web preview** (many big media channels have not). Channels without a preview are listed in the run summary.
- **Telegram's channel search returns only about the 22 newest matches per channel.** For common words on busy channels, turn on **Scan recent history**: the channel's latest posts (20 per page) are read once and every keyword is matched in them, so recent counts are complete. `searchCapped` in the report shows where the limit was hit without it.
- **Matching** is Telegram's own and includes word forms ("launch" finds "launched"); turn on **Exact keyword only** to keep exact matches.
- **Views** are Telegram's rounded counts ("6.9K" → 6,900).
- **Privacy**: only what channels published is collected: no members, commenters or phone numbers.
- **Proxy**: requests go direct, about one a second. Apify datacenter proxy is used only if Telegram answers "too many requests".
- Data comes from **t.me public channel previews**. **Not affiliated with Telegram.**

### Input

| Field | Meaning |
|---|---|
| **Keywords** | One search each (required) |
| **Channels** | Optional; empty = built-in directory |
| **Also search the built-in channel directory** / **Directory topics** | Crypto, news, markets, tech |
| **Posted within** | 24 hours, 7, 30, 90 days or a year |
| **Posts per channel** | 1 to 1,000 per keyword and channel (default 100) |
| **Scan recent history** | 0 to 50 pages per channel (default 0 = search only) |
| **Exact keyword only** | Off by default |
| **Reports** | On by default |

### Integrations

Export to JSON, CSV, Excel or Google Sheets, or connect through the Apify API, webhooks, Make, Zapier and n8n. **Schedule it hourly or daily** with "Last 24 hours" as a mention alert. To score whole channels (posting rate, views per subscriber, momentum), see the [Telegram Channel Monitor](https://apify.com/precious_bathmat/telegram-channel-monitor).

# Actor input Schema

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

Words or phrases to search for, one search each: a brand, a coin or ticker, a product, a topic ("bitcoin ETF", "airdrop", "Tesla", "layoffs").

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

Public channels to search: "@cointelegraph", "WatcherGuru" or "https://t.me/bloomberg". Leave empty to search the built-in directory.

## `useDirectory` (type: `boolean`):

Adds 34 large public channels checked to be searchable (crypto, news, markets, tech). On automatically when you list no channels.

## `topics` (type: `array`):

Which part of the directory to search. Empty = all.

## `withinDays` (type: `string`):

Only posts from this period (searching stops going back once it is passed).

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

Most matching posts per keyword and channel, newest first (1 to 1,000). Search alone finds up to about 22 per channel; more need "Scan recent history".

## `scanHistoryPages` (type: `integer`):

Telegram's channel search returns only about the 22 newest matches per channel. Set this to also read each channel's latest posts (20 per page, newest first, once per channel for all keywords) and match the keywords in them: complete counts for busy channels and common words. 0 = search only. Stops early at the "Posted within" limit.

## `exactOnly` (type: `boolean`):

Telegram's search also matches word forms ("launch" finds "launched"). Turn on to keep only posts whose text contains the keyword exactly.

## `includeReports` (type: `boolean`):

One report per keyword: mentions and share by channel, views, mentions in the last 24 hours / 7 / 30 days, a 30-day daily timeline, top posts and latest posts.

## Actor input object example

```json
{
  "keywords": [
    "ETF"
  ],
  "withinDays": "any",
  "maxPostsPerChannel": 100,
  "scanHistoryPages": 0,
  "exactOnly": false,
  "includeReports": true
}
```

# Actor output Schema

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

One row per matching post: channel, subscribers, date, text, views, link.

## `reports` (type: `string`):

Per keyword: mentions by channel, views, recent mentions, a 30-day timeline, top and latest posts.

## `reportsCsv` (type: `string`):

One flat row per keyword.

## `summary` (type: `string`):

Channels used, requests, problems and the limits of the data.

# 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 = {
    "keywords": [
        "ETF"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("precious_bathmat/telegram-keyword-search").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 = { "keywords": ["ETF"] }

# Run the Actor and wait for it to finish
run = client.actor("precious_bathmat/telegram-keyword-search").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 '{
  "keywords": [
    "ETF"
  ]
}' |
apify call precious_bathmat/telegram-keyword-search --silent --output-dataset

```

## MCP server setup

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

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/ebpBHGyJJ7EjtJh9U/builds/yPXdmzFJanGAKV2IU/openapi.json