# BORG Telegram channel scraper (`acid-base/borg-telegram-scraper`) Actor

Extracts data without a Telegram account or API key.

Collect channel metadata, posts, media links, view counts, forwards, replies, timestamps, and date-filtered history from public channels.

Good for market research, community monitoring, content archiving, lead intelligence, competitive analysis.

- **URL**: https://apify.com/acid-base/borg-telegram-scraper.md
- **Developed by:** [Daniel Yates](https://apify.com/acid-base) (community)
- **Categories:** Social media, Lead generation, Other
- **Stats:** 120 total users, 34 monthly users, 81.8% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.60 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Historical Archive / Research Dataset Export

Export public Telegram channel profiles and message history as a normalized, reusable
research dataset — for archival analysis, indexing, and downstream intelligence
workflows.

Public and **credential-free**: the actor reads only Telegram's server-rendered public
web preview (`https://t.me/s/<channel>`) with a plain HTTP fetch parsed by Cheerio. No
login, no cookies, no API keys, no proxy escalation, no headless browser. It never
accesses private content and never asks for your Telegram credentials.

### Task modes (polymorphic templates)

One extraction engine serves several Telegram surfaces. Pick a `mode`:

| Mode | Purpose |
| --- | --- |
| `legacy_channel_scraper` | Backward-compatible with the original deployed actor (`channels`, `maxMessages`, `dateFrom`/`dateTo`). |
| `historical_archive` | Export public channel history into a normalized research archive. |
| `research_dataset_export` | Bounded public-message dataset with stable fields for research/enrichment. |
| `media_link_inventory` | Inventory public media and outbound links from a channel. |
| `recent_monitor` | Check recent public posts for fresh updates. |
| `incremental_update_seed` | Bounded latest-message seed for downstream delta comparison. |
| `channel_summary` | Resolve a public profile into a compact channel summary. |
| `message_probe` | Small public-message sample for schema validation / triage. |

### Input

See `.actor/INPUT_SCHEMA.json`. Common fields: `telegramChannelOrProfile` (or legacy
`channels`), `mode`, `messageLimit` (or legacy `maxMessages`), `includeMedia`,
`includeReplies`, `dateRange` (or legacy `dateFrom`/`dateTo`). `proxyConfiguration` is
accepted for compatibility but non-escalating.

### Output

Records are pushed to the dataset (`.actor/dataset_schema.json`) with `Messages`,
`Media & Links`, and `Channels` views. Each message row carries text, author, date,
views, edited/album flags, media references (photo/video/document/voice/sticker/poll),
link previews, and outbound links. A per-run summary is written to the default
key-value store under `OUTPUT` (`.actor/output_schema.json`).

### Standby mode

The actor supports the Apify Standby Actor spec: when started in Standby mode it runs a
warm HTTP server instead of a one-shot run, answering requests without cold starts.

```
GET  /?channel=<@handle|url>&mode=<task>&messageLimit=<n>
POST /            (JSON body = actor input)
```

The server answers the platform readiness probe and returns scraped records as JSON in
the HTTP response (it does not push to the shared dataset). Enable Standby in the
Actor's **Settings** tab in the Apify Console.

### Deployment

Deployment-ready Apify Actor scaffold. Runs on `apify/actor-node:22` via `npm start`
(`tsx src/main.ts`).

# Actor input Schema

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

Legacy deployed actor task input. List of public Telegram channels or groups. Can be @username, t.me/username, or just the username.

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

Legacy deployed actor task input. Only scrape messages after this date (ISO format: YYYY-MM-DD).

## `dateRange` (type: `object`):

Optional date range filter (ISO YYYY-MM-DD start/end). The public web preview exposes a channel's most recent messages, so this narrows within recent history; leave empty to export the latest messages.

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

Legacy deployed actor task input. Only scrape messages before this date (ISO format: YYYY-MM-DD).

## `includeMedia` (type: `boolean`):

Include media references when present.

## `includeReplies` (type: `boolean`):

Include reply threads when present.

## `maxMessages` (type: `integer`):

Legacy deployed actor task input. Maximum number of messages to scrape per channel.

## `messageLimit` (type: `integer`):

Maximum number of messages to export.

## `mode` (type: `string`):

Choose the polymorphic task template to run on top of the Telegram public-preview schema.

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

Accepted for backward compatibility. Public preview access remains unauthenticated and avoids proxy escalation by default.

## `telegramChannelOrProfile` (type: `string`):

Telegram channel, group, or profile URL or handle.

## Actor input object example

```json
{
  "dateRange": {
    "start": "2020-01-01",
    "end": "2099-12-31"
  },
  "includeMedia": true,
  "includeReplies": true,
  "messageLimit": 25,
  "mode": "research_dataset_export",
  "telegramChannelOrProfile": "https://t.me/telegramtips"
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

All scraped Telegram message and channel records in the default dataset.

## `runSummary` (type: `string`):

Compact run summary record (mode, transport, counts, custody flags) in the default key-value store.

# 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 = {
    "dateRange": {
        "start": "2020-01-01",
        "end": "2099-12-31"
    },
    "includeMedia": true,
    "includeReplies": true,
    "messageLimit": 25,
    "mode": "research_dataset_export",
    "telegramChannelOrProfile": "https://t.me/telegramtips"
};

// Run the Actor and wait for it to finish
const run = await client.actor("acid-base/borg-telegram-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 = {
    "dateRange": {
        "start": "2020-01-01",
        "end": "2099-12-31",
    },
    "includeMedia": True,
    "includeReplies": True,
    "messageLimit": 25,
    "mode": "research_dataset_export",
    "telegramChannelOrProfile": "https://t.me/telegramtips",
}

# Run the Actor and wait for it to finish
run = client.actor("acid-base/borg-telegram-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 '{
  "dateRange": {
    "start": "2020-01-01",
    "end": "2099-12-31"
  },
  "includeMedia": true,
  "includeReplies": true,
  "messageLimit": 25,
  "mode": "research_dataset_export",
  "telegramChannelOrProfile": "https://t.me/telegramtips"
}' |
apify call acid-base/borg-telegram-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=acid-base/borg-telegram-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/8ScAgnvsbOpw7g7Pn/builds/N6PrglfjstFdcEnxT/openapi.json