start_keyword_search
Launch a paid Telegram keyword search that finds relevant channels and returns a run_id for fetching matching posts; set keywords, date limits, and a spending cap.
Instructions
Start a Telegram keyword search that also FINDS the channels talking about each keyword, and return a run_id immediately. Step 1 of 2: then call get_keyword_results(run_id) to get the posts.
Starts the hosted Apify Actor "datalume/telegram-keyword-search-scraper" with your own
Apify account. Requires the APIFY_TOKEN environment variable. It is PAID: per matching
post plus a small fee per keyword when channels are found (current price:
https://apify.com/datalume/telegram-keyword-search-scraper ); non-matching posts and
unreadable channels are not charged. Starting a search spends money even if the results
are never fetched, so start one only when the user wants the posts. The run stops at
max_posts_per_keyword and at max_total_charge_usd. A run takes from a few seconds to
about two minutes (15 Nov 2026: 3 keywords, 259 posts from 19 channels in 2 min 15 s).
Args:
keywords: words or phrases, e.g. ["Hyperliquid"]. Each keyword is searched separately.
channels: optional channels that are always searched, e.g. ["durov"].
discover_channels: find channels for each keyword with Google (site:t.me). Set false to search only `channels`.
max_channels_per_keyword: found channels searched per keyword, 1-50.
match_mode: "phrase" (exact phrase or #hashtag), "allWords" or "telegram" (everything Telegram returns).
max_posts_per_keyword: stop a keyword after this many matching posts. Keep small to control cost.
date_from: only posts since a date ("2026-11-01") or a period ("7 days", "24 hours"). Empty = any date.
only_new_posts: return only posts published since the previous run of the same keyword in each channel.
max_total_charge_usd: hard spending cap for this search, in USD.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"keywords": "<keywords>"
},
"name": "start_keyword_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| channels | No | ||
| keywords | Yes | ||
| date_from | No | ||
| match_mode | No | phrase | |
| only_new_posts | No | ||
| discover_channels | No | ||
| max_total_charge_usd | No | ||
| max_posts_per_keyword | No | ||
| max_channels_per_keyword | No |