# Telegram Keyword Search & Channel Scraper (`monkey.d.scraping/telegram-keyword-search-channel-scraper`) Actor Search public Telegram posts by keyword, collect public channel posts, and export verified structured data without Telegram credentials. - **URL**: https://apify.com/monkey.d.scraping/telegram-keyword-search-channel-scraper.md - **Developed by:** [Monkey D. Scraping](https://apify.com/monkey.d.scraping) (community) - **Categories:** Social media, Developer tools - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 telegram 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Telegram Keyword Search & Channel Scraper Collect structured evidence from public Telegram channels in a single, stateless run. Search for publicly indexed posts by keyword, collect posts from public channels you already know, or combine both sources under one result limit. No Telegram account, phone number, or Telegram API key is required. ### At a glance | Capability | What it means | |---|---| | Telegram keyword search | Discover publicly indexed Telegram posts for one or more terms. | | Telegram channel scraper | Collect publicly available posts from channel usernames or public URLs. | | Hybrid runs | Combine keywords and known channels without creating separate jobs. | | Guided plans | Choose automatic, keyword-only, channel-only, or combined collection. | | Predictable allocation | Set a global cap, optional per-channel cap, and source priority for hybrid runs. | | Filters | Limit returned posts by absolute or relative dates, text phrases, optional patterns, country preference, and language preference. | | Verified output | Every row has a canonical post URL; unavailable values are `null`, never inferred. | | Media by choice | Public media references are included; downloading is disabled unless explicitly enabled. | ### Quick start You only need one source to begin: a keyword or a public channel. Leave the collection plan on **Automatic** and fill the source fields that match your task. Choose a focused plan only when you intentionally want the Actor to ignore the other source type. | Your goal | Fill in | Recommended plan | |---|---|---| | Find public Telegram discussion about a topic | `keywords` | Automatic or Keyword discovery only | | Archive or analyze sources you already know | `channels` | Automatic or Known public channels only | | Research a topic while checking selected sources | both `keywords` and `channels` | Combine keywords and channels | Set `maxResults` to control the total size of the dataset, then run the Actor. All other fields are optional. ### When to use it This Actor is designed for one-time public Telegram data extraction rather than ongoing monitoring. It is useful when you need a current, reproducible dataset for: - Telegram brand monitoring and competitor research - News, market, and policy research - Public-source journalism and OSINT workflows - Channel archiving for analysis, audit, or compliance research - Crypto, finance, technology, and community research - Multilingual topic discovery using country and language preferences For a repeated, stateful “what is new since the last run?” workflow, use a dedicated monitoring Actor rather than treating this extractor as a scheduler. ### Choose your collection path #### 1. Discover public posts by keyword Add one or more keywords when the relevant channels are not yet known. The Actor finds publicly indexed Telegram posts and returns only results that literally contain the requested keyword. Country and language preferences help focus discovery, but they do not establish the author’s location or classify a post’s language. #### 2. Collect known public channels Add a channel username such as `cointelegraph`, an `@username`, or a public Telegram channel URL. The Actor collects publicly accessible posts until the date boundary or the run’s global result cap is reached. #### 3. Combine both in one run Use keywords and channels together when you need broad discovery alongside authoritative sources. Canonical post URLs are deduplicated, so the same public post is emitted at most once. #### How a hybrid run uses the result cap `maxResults` is always one global limit. If both sources are present, use **Priority when both sources are used** to make the allocation explicit: | Priority | Use it when | Effect if the global cap is reached | |---|---|---| | Known channels first | Your selected sources are the most important evidence. | Direct channel collection gets capacity before keyword-discovered channels. | | Keyword discovery first | Broad topic discovery matters more than source coverage. | Keyword-discovered channels get capacity before direct channel collection. | You can also set an optional `maxResultsPerChannel` to prevent a high-volume channel from using all available capacity. Neither setting changes canonical deduplication. ### Input guide | Input | Use it for | |---|---| | `keywords` | Topic, brand, product, organization, event, or phrase discovery across public Telegram content. | | `channels` | Direct collection from public channel usernames or URLs. | | `collectionMode` | Guided choice: automatic, keyword-only, channel-only, or hybrid. | | `afterDate` / `beforeDate` | Inclusive date boundaries: choose a date or use a relative value such as `7 days`. | | `countryCode` | Optional ISO 3166-1 alpha-2 preference for keyword discovery. | | `languageCode` | Optional ISO 639-1 preference for keyword discovery. | | `maxResults` | One global maximum for unique posts from all sources in the run. | | `sourcePriority` | Explicit allocation choice for a combined run that reaches its global cap. | | `maxResultsPerChannel` | Optional fairness cap for one channel within the global maximum. | | `includeKeywords` / `excludeKeywords` | Simple phrase filters applied to public post text and public channel title. | | `regexFilters` | Optional advanced text filters using JavaScript-compatible regular expressions. | | `downloadMedia` | Off by default. Enable only when you need available public media files stored with the run. | ### Country and language preferences For keyword discovery, you can optionally enter a two-letter country code such as `IT` or `US`, and a two-letter language code such as `it` or `en`. These fields guide discovery toward a regional and linguistic context; they are not strict filters and do not prove a post’s country of origin or language. Use them together when it helps your research. For example, `countryCode: "IT"` with `languageCode: "it"` is a reasonable starting point for Italian-language topic discovery. Direct collection from a known public channel does not depend on either preference. ### Example inputs #### Public Telegram keyword research ```json { "keywords": ["electric vehicle supply chain", "battery recycling"], "afterDate": "14 days", "countryCode": "it", "languageCode": "it", "maxResults": 100, "downloadMedia": false } ```` #### Scrape known public channels ```json { "channels": ["cointelegraph", "https://t.me/example_public_channel"], "afterDate": "2026-07-01", "maxResults": 250, "downloadMedia": false } ``` #### Combine discovery and direct collection ```json { "keywords": ["open source security"], "channels": ["example_public_channel"], "sourcePriority": "keywordsFirst", "afterDate": "2026-07-01", "includeKeywords": ["advisory", "patch"], "excludeKeywords": ["giveaway"], "maxResults": 150 } ``` ### Dataset fields and data quality The default dataset contains one row per canonical public Telegram post. Each record includes source-channel identity, public channel title and description when exposed, canonical channel and post URLs, message ID, publication time when exposed, post text or caption, public counters when reliably available, structured public reactions by emoji and displayed count, media references, links, tags, mentions, matched input keywords, and collection provenance. The Actor deliberately distinguishes “not available” from “zero”: - `null` means the public page did not reliably expose a value. - An empty array means no value was extracted from the public post representation; it is not a claim about private or deleted content. - Textless posts retain `text: null`; no author, engagement figure, date, or media type is invented. The default key-value store also contains `SUMMARY`, with counts for collected and deduplicated posts, source coverage, and isolated non-sensitive errors. A successful run can validly return zero rows. ### CLI, API, and MCP-ready contract The input schema, output schema, dataset schema, and README use the same field names and meanings. This makes the Actor straightforward to configure in the Apify Console, API, CLI, and Apify MCP server. An agent can determine the required source inputs, inspect the expected dataset fields before a run, and retrieve the post dataset and `SUMMARY` after it finishes. The Actor itself does not use an AI model. “MCP-ready” here means that external AI agents can discover and call a well-described Apify Actor tool. ### Use results in your workflow Read the default dataset and `SUMMARY` through the Apify API or webhooks. The standard Actor result format can also be consumed by compatible automation platforms such as n8n, Make, and Zapier, as well as your own JavaScript, TypeScript, Python, spreadsheet, or data-warehouse workflow. The canonical public post URL makes downstream linking and deduplication straightforward. Integration availability and configuration remain the responsibility of the destination platform and the user’s account. ### Coverage and responsible use This Actor handles public material only. It cannot access private channels, invite-only channels, login-protected material, deleted posts, or content that is not publicly available. Keyword discovery depends on public indexing, so it is not a guarantee of complete, real-time, or exhaustive Telegram coverage. Use the Actor in accordance with applicable law, platform rules, and your organization’s policies. Do not use it to infer identities, location, intent, or engagement values that the public source does not expose. ### FAQ #### Do I need a Telegram login or API key? No. The Actor does not ask the user for Telegram credentials. #### Can I search keywords and scrape channels at the same time? Yes. Both sources can be included in one stateless run and are deduplicated by canonical post URL. #### What does the country or language option do? They are optional discovery preferences. They help focus keyword discovery, but do not certify where a post came from or which language it uses. #### Can I use “7 days” instead of a calendar date? Yes. The date fields accept a calendar date or a relative value such as `7 days`, `2 weeks`, `1 month`, or `1 year`. #### What happens if keywords and channels both return more posts than the limit? The Actor returns at most `maxResults` unique posts. Choose source priority to decide which source is processed first, and optionally add a per-channel cap for a more balanced dataset. #### Why is a field `null`? The value was not reliably available on the public source. The Actor does not guess missing metadata. #### Are media files downloaded automatically? No. The Actor returns public media references when available. Media download is disabled by default. #### Does this Actor monitor new posts over time? No. It is a stateless extractor for one-time collection. Use a stateful monitoring workflow when you need checkpoints and only-new-post detection. ### Pricing Pricing remains under review against measured cloud cost, latency, and result yield. The current private build is intended for validation; no commercial price is active yet. # Actor input Schema ## `collectionMode` (type: `string`): Automatic uses whichever source fields you fill in. Select a focused plan when you want the Actor to ignore the other source type. ## `keywords` (type: `array`): Words or phrases used to discover publicly indexed Telegram posts. Each returned discovery result must contain the literal keyword. ## `channels` (type: `array`): Public Telegram usernames, @usernames, or public channel URLs. Private, invite-only, login-protected, and deleted content is out of scope. ## `afterDate` (type: `string`): Inclusive lower date bound. Choose a date or use a relative value such as 7 days. Leave empty for no lower bound. ## `beforeDate` (type: `string`): Inclusive upper date bound. Choose a date or use a relative value such as 30 days. Leave empty for no upper bound. ## `countryCode` (type: `string`): Optional preference for keyword discovery, not a strict post-location filter. Select a common country code or type any ISO 3166-1 alpha-2 code. ## `languageCode` (type: `string`): Optional preference for keyword discovery, not an automatic language classification. Select a common language code or type any ISO 639-1 code. ## `sourcePriority` (type: `string`): Only matters in a combined run when the global cap is reached. Choose which source gets capacity first. ## `maxResults` (type: `integer`): Global cap across every keyword and channel. The source-priority setting decides which source is processed first when both are used. ## `maxResultsPerChannel` (type: `integer`): Optional fairness cap for each individual channel. Leave empty to use only the global maximum above. ## `includeKeywords` (type: `array`): Keep a post only when its public text or public channel title contains at least one of these phrases. ## `excludeKeywords` (type: `array`): Discard a post when its public text or public channel title contains any of these phrases. ## `regexFilters` (type: `array`): Optional advanced filter. Keep a post only when its public text matches at least one JavaScript-compatible regular expression. Leave empty for normal use. ## `downloadMedia` (type: `boolean`): Disabled by default. When enabled, available public media may also be saved in this run's key-value store; source references remain in the dataset. ## Actor input object example ```json { "collectionMode": "auto", "keywords": [], "channels": [], "sourcePriority": "channelsFirst", "maxResults": 100, "includeKeywords": [], "excludeKeywords": [], "regexFilters": [], "downloadMedia": false } ``` # Actor output Schema ## `overview` (type: `string`): One canonical, deduplicated row for every verifiable public Telegram post returned by the run. ## `runSummary` (type: `string`): Run counts, source coverage, duplicates removed, selected source priority, and non-sensitive isolated errors. A successful run can contain zero matching posts. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("monkey.d.scraping/telegram-keyword-search-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("monkey.d.scraping/telegram-keyword-search-channel-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call monkey.d.scraping/telegram-keyword-search-channel-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=monkey.d.scraping/telegram-keyword-search-channel-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Telegram Keyword Search & Channel Scraper", "description": "Search public Telegram posts by keyword, collect public channel posts, and export verified structured data without Telegram credentials.", "version": "0.1", "x-build-id": "MOgztYCNS2CFBwXmX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/monkey.d.scraping~telegram-keyword-search-channel-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-monkey.d.scraping-telegram-keyword-search-channel-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/monkey.d.scraping~telegram-keyword-search-channel-scraper/runs": { "post": { "operationId": "runs-sync-monkey.d.scraping-telegram-keyword-search-channel-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/monkey.d.scraping~telegram-keyword-search-channel-scraper/run-sync": { "post": { "operationId": "run-sync-monkey.d.scraping-telegram-keyword-search-channel-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "collectionMode": { "title": "Collection plan", "enum": [ "auto", "keyword", "channel", "hybrid" ], "type": "string", "description": "Automatic uses whichever source fields you fill in. Select a focused plan when you want the Actor to ignore the other source type.", "default": "auto" }, "keywords": { "title": "Keywords", "type": "array", "description": "Words or phrases used to discover publicly indexed Telegram posts. Each returned discovery result must contain the literal keyword.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "channels": { "title": "Public channels", "type": "array", "description": "Public Telegram usernames, @usernames, or public channel URLs. Private, invite-only, login-protected, and deleted content is out of scope.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "afterDate": { "title": "Published on or after", "type": "string", "description": "Inclusive lower date bound. Choose a date or use a relative value such as 7 days. Leave empty for no lower bound." }, "beforeDate": { "title": "Published on or before", "type": "string", "description": "Inclusive upper date bound. Choose a date or use a relative value such as 30 days. Leave empty for no upper bound." }, "countryCode": { "title": "Country preference for discovery", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Optional preference for keyword discovery, not a strict post-location filter. Select a common country code or type any ISO 3166-1 alpha-2 code." }, "languageCode": { "title": "Language preference for discovery", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Optional preference for keyword discovery, not an automatic language classification. Select a common language code or type any ISO 639-1 code." }, "sourcePriority": { "title": "Priority when both sources are used", "enum": [ "channelsFirst", "keywordsFirst" ], "type": "string", "description": "Only matters in a combined run when the global cap is reached. Choose which source gets capacity first.", "default": "channelsFirst" }, "maxResults": { "title": "Maximum unique posts in this run", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Global cap across every keyword and channel. The source-priority setting decides which source is processed first when both are used.", "default": 100 }, "maxResultsPerChannel": { "title": "Maximum posts per channel", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Optional fairness cap for each individual channel. Leave empty to use only the global maximum above." }, "includeKeywords": { "title": "Post text or channel title must include", "type": "array", "description": "Keep a post only when its public text or public channel title contains at least one of these phrases.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "excludeKeywords": { "title": "Post text or channel title must not include", "type": "array", "description": "Discard a post when its public text or public channel title contains any of these phrases.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "regexFilters": { "title": "Advanced: regular-expression text patterns", "type": "array", "description": "Optional advanced filter. Keep a post only when its public text matches at least one JavaScript-compatible regular expression. Leave empty for normal use.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "downloadMedia": { "title": "Download available public media", "type": "boolean", "description": "Disabled by default. When enabled, available public media may also be saved in this run's key-value store; source references remain in the dataset.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```