# Telegram Private Group Scraper (`agentx/telegram-private-group-scraper`) Actor

Authenticated private-group member extractor — log in once with QR (and optional 2FA), then pull up to 100,000 members from any private Telegram group or supergroup you already belong to. Optional Deep Search reveals hidden and historical members alongside username, names, and activity signals.

- **URL**: https://apify.com/agentx/telegram-private-group-scraper.md
- **Developed by:** [AgentX](https://apify.com/agentx) (community)
- **Categories:** Social media, Agents, Integrations
- **Stats:** 86 total users, 9 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.27 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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 Private Group Scraper uses an authenticated Telegram user session to collect member observations that the account can access in one basic group or supergroup. It combines the regular participant listing with optional search and message-sender discovery, then writes deduplicated 18-field profile rows.

- Authenticate with a reusable Telethon StringSession or a QR code shown in the live run log.
- Match accessible group dialogs by title, username, or numeric-ID substring; the last matching dialog is selected.
- Choose a required `max_results` stopping threshold from 100 to 100,000 and optionally request Deep Search.
- Pay per Result row actually written, while recognizing that one batch can exceed the requested threshold.

[Open Telegram Private Group Scraper](https://console.apify.com/actors/L4SPW5ECJb9gP5aDT/input), use the [Apify API](https://docs.apify.com/api/v2), or connect through [MCP](https://docs.apify.com/integrations/mcp). Process only groups and member data you are authorized to access. Telegram privacy, permissions, session visibility, and API limits remain authoritative.

### Why Choose This API

The Actor packages a user-session Telegram workflow into a traceable Apify run. It signs in, scans the account's dialogs, selects the last basic group or supergroup whose title, username, or numeric ID contains `group_match`, obtains accessible participants, formats Telegram User entities, deduplicates them by user ID, and writes batches to the default Dataset.

The standard pass calls Telegram's participant listing with an empty search. Deep Search adds 36 single-character participant queries and then inspects senders from message-history ranges. This can discover additional User entities when the authenticated account is allowed to see them. It does not bypass hidden-member settings, access controls, Telegram privacy, or unavailable message history, and it cannot promise all current or historical members.

Coverage is shaped by several independent gates. Telegram may return only a partial participant list, searches may overlap, older messages may be unavailable, some messages have no user sender, and peer resolution may fail. Flood-wait and other RPC errors can stop an individual pass without failing the entire Actor. Because many exceptions become an empty or partial batch, the final row count is a run observation—not a count that automatically reconciles to the group's displayed membership total.

The output is explicit about visibility. Phone number, language, last-seen state, usernames, premium state, and other flags appear only as Telegram exposes them to that authorization. Null or coarse values are expected. The Actor does not validate identities, infer demographics, verify account ownership, or label someone beyond Telegram's source flags.

A StringSession is an exported authorization credential. Telethon warns that anyone holding one may be able to log in and act as the account. On QR login, this runtime prints the generated session to the run log and sends it to the account's Saved Messages. Protect both surfaces, restrict run access, and revoke exposed sessions.

### Quick Start Guide

Start with `deep_search: false`, the minimum threshold, and a distinctive group value. Use an account that already has legitimate access to the target group.

```json
{
  "session": "YOUR_TELETHON_STRING_SESSION",
  "group_match": "authorized research group 2026",
  "deep_search": false,
  "max_results": 100
}
```

If `session` is empty, watch the log and scan the QR code using Telegram's device-linking flow. Runtime attempts up to three QR windows of roughly 30 seconds. Supply `password` only when Telegram requests two-step verification. After login, secure the printed session and Saved Messages copy.

Verify the logged group title and ID before relying on output. Despite older wording that said “first match,” runtime keeps replacing the candidate during the dialog scan, so the last matching group is used. A short query can silently select an unintended dialog.

At completion, compare terminal status, charged Result count, Dataset item count, and logs. Fatal login or matching errors are caught by the main process and may finish with zero rows. A nonzero Dataset is evidence that profile batches were written, not evidence of group completeness.

Record the build and selected group identifier with each export. Repeating the same input later can yield different rows as membership, usernames, source visibility, account permissions, API behavior, and message history change. For change detection, compare snapshots by `user_id` and preserve collection times instead of overwriting the earlier run.

### Input Parameters

| Field | Type | Required | Runtime behavior |
|---|---|---:|---|
| `session` | secret string | No | Reuses a Telethon StringSession; empty starts QR login. |
| `password` | secret string | No | Used for Telegram two-step verification during authorization. |
| `group_match` | string | Yes | Trimmed, lowercased substring; the last matching basic group or supergroup wins. |
| `deep_search` | boolean | Yes | Adds participant-search and message-sender passes when permitted. |
| `max_results` | integer | Yes | Stopping threshold from 100 to 100,000, checked between batches. |

The free-plan runtime branch forces `deep_search` to false and clamps `max_results` to 100 regardless of supplied values. Paid-user behavior depends on Apify's run metadata recognized by the Actor.

`max_results` is not a hard Dataset or billing limit. A participant request is collected into a whole in-memory mapping and pushed before the next threshold check. If the first empty-search batch returns 750 accessible users while the threshold is 100, that full batch can be written and charged. Deep Search batches can also cross the threshold. Use a conservative charge cap and monitor the run.

There are no public inputs for a strict row cap, query character set, message range count, delay, proxy, retry strategy, field selection, or session revocation. The selected group must already appear in the account's dialogs.

### Output Data Schema

Each successful profile format contains 18 fields:

| Field group | Fields | Boundary |
|---|---|---|
| Provenance | `processor`, `processed_at` | Actor URL and formatting timestamp. |
| Identity | `user_id`, `first_name`, `last_name`, `usernames` | Telegram-visible values; usernames are deduplicated with no stable order. |
| Contact/type | `phone_number`, `entity_type`, `lang_code` | Phone and language are often null; type is `user` or `bot`. |
| Status | `last_seen`, `premium_contact` | Privacy can reduce last seen to coarse or unknown. |
| Flags | `is_deleted`, `is_verified`, `is_premium`, `is_scam`, `is_fake`, `is_restricted`, `stories_hidden` | Source User flags at processing time, not independent findings. |

```json
{
  "processor": "https://apify.com/agentx/telegram-private-group-scraper?fpr=aiagentapi",
  "processed_at": "2026-07-23T19:10:00+00:00",
  "user_id": 123456789,
  "first_name": "Example",
  "last_name": "Member",
  "usernames": ["example_member"],
  "phone_number": null,
  "entity_type": "user",
  "is_deleted": false,
  "is_verified": false,
  "is_premium": null,
  "is_scam": false,
  "is_fake": false,
  "is_restricted": false,
  "lang_code": null,
  "last_seen": "recently",
  "stories_hidden": null,
  "premium_contact": null
}
```

Rows are deduplicated by numeric user ID across standard, query, and message passes. Formatting failures return no object and are skipped. Exceptions during participant or message traversal are generally swallowed or end that pass, so missing rows do not establish that a user is absent from the group.

### Integration Examples

Use the stable Actor name `agentx/telegram-private-group-scraper`. Keep the Apify token and Telegram credentials in a managed secret store, preserve the run ID, and restrict access to Dataset and logs.

```json
{
  "method": "POST",
  "url": "https://api.apify.com/v2/acts/agentx~telegram-private-group-scraper/runs?waitForFinish=240&maxTotalChargeUsd=0.10",
  "headers": {
    "Authorization": "Bearer YOUR_APIFY_TOKEN",
    "Content-Type": "application/json"
  },
  "body": {
    "session": "YOUR_TELETHON_STRING_SESSION",
    "group_match": "authorized research group 2026",
    "deep_search": false,
    "max_results": 100
  }
}
```

After completion, fetch items from `defaultDatasetId` and reconcile them with `chargedEventCounts.result`. Deduplicate again by `user_id` when merging multiple runs. Treat repeated observations as time-specific snapshots because usernames, flags, visibility, and group membership can change.

MCP clients should fetch the current input schema before execution. Do not let a client invent a group query, reuse an unapproved session, or widen Deep Search without explicit authorization and a cost boundary.

### Pricing & Cost Calculator

The active local schedule charges one **Actor Start** at `$0.01` plus one **Result** per written Dataset row. Result prices are tiered: Free `$0.00030`, Bronze `$0.00029`, Silver `$0.00028`, and Gold, Platinum, or Diamond `$0.00027`.

At Bronze pricing, 100 rows cost `$0.039`, 1,000 rows cost `$0.30`, and 10,000 rows cost `$2.91`, including one start and excluding any unrelated platform usage. A 100,000-row run would be `$29.01`. Actual charges follow the active tier at execution.

Because result batches can exceed `max_results`, those calculations are examples, not caps. `maxTotalChargeUsd` is the primary financial guard. Inspect the event count afterward and choose a low initial cap for an unfamiliar group.

### Use Cases & Applications

Appropriate uses include authorized community administration, access reviews, internal group audits, research with participant permission, or migration planning where the operator has a documented basis to process membership data. Keep only the minimum fields needed for the stated purpose.

Standard search is preferable when the visible participant list is sufficient. Deep Search is more resource-intensive and broadens collection to query matches and accessible message senders; enable it only when that additional processing is necessary and authorized.

Do not use this Actor to build unsolicited contact lists, infer sensitive traits, evade hidden-member controls, monitor people covertly, or train models from Telegram data. A group's availability to one account does not grant unrestricted reuse or publication rights.

### FAQ

**Does Deep Search reveal every hidden member?** No. It only adds defined participant searches and message-sender resolution where Telegram permits access.

**Why did I get more rows than max\_results?** The threshold is checked between full batches, after a batch can already be pushed and charged.

**Why was a different group selected?** Runtime uses the last matching dialog, not the first. Make `group_match` more distinctive and verify logs.

**Why is last\_seen unknown or coarse?** Telegram privacy can expose `recently`, `last_week`, `last_month`, or nothing instead of a timestamp.

**Why did a finished run return zero rows?** Authorization, QR login, dialog matching, group inspection, or participant access may have failed before any push.

**Is the StringSession safe to share with support?** No. Treat it like an account password and revoke it if exposed.

**Does a row prove that the person is still a member?** No. It proves only that a Telegram User entity was returned through an accessible pass during that run. Deep Search can include message senders, and membership can change afterward.

### Trust & Certifications

The public contract documents the exact required inputs, 18 output fields, last-match behavior, tiered per-row billing, free-plan restrictions, Deep Search mechanics, session exposure, and soft threshold. The Actor is not certified or endorsed by Telegram, Telethon, Apify, a privacy regulator, or a security auditor, and it offers no completeness or accuracy guarantee.

Telegram is authoritative for visible entities and flags. Review official [privacy settings](https://core.telegram.org/api/privacy), [peer behavior](https://core.telegram.org/api/peers), and [API errors](https://core.telegram.org/api/errors) before interpreting gaps.

### Legal & Compliance

Use the API only with the account owner's knowledge and for groups you are authorized to access. Telegram's [API terms](https://core.telegram.org/api/terms) require strong privacy protection and restrict acting without user knowledge and consent. Define purpose, lawful basis, access control, retention, deletion, and incident handling before collection.

Public or account-visible profile fields are still personal data in many contexts. Do not evade restrictions, republish sensitive membership, or assume a Telegram flag is an independent factual finding. This is operational guidance, not legal advice.

### Related Tools

- [Telegram Member Scraper](https://apify.com/agentx/telegram-member-scraper?fpr=aiagentapi) — use a public or separately authorized member workflow.
- [Telegram Chat Scraper](https://apify.com/agentx/telegram-chat-scraper?fpr=aiagentapi) — collect authorized chat observations rather than member profiles.
- [Telegram Info Scraper](https://apify.com/agentx/telegram-info-scraper?fpr=aiagentapi) — retrieve public Telegram entity metadata.
- [Telegram Group Inviter](https://apify.com/agentx/telegram-group-inviter?fpr=aiagentapi) — invite only people who expect it; scraped membership is not consent.
- [Reddit Author Scraper](https://apify.com/agentx/reddit-author-scraper?fpr=aiagentapi) — a separate public-author observation workflow.
- [Twitter Info Scraper](https://apify.com/agentx/twitter-info-scraper?fpr=aiagentapi) — retrieve public X profile observations separately.

### Support & Community

For a reproducible report, provide the run ID, UTC time, build, terminal status, redacted group query, `deep_search`, requested threshold, Dataset count, Result event count, and relevant non-secret log lines. Never share the StringSession, QR code, two-step password, API token, private group title, or member records.

Contact [AgentX support](https://t.me/AiAgentApi). Review [Telethon session security](https://docs.telethon.dev/en/stable/concepts/sessions.html) and [Telethon chat/participant examples](https://docs.telethon.dev/en/stable/examples/chats-and-channels.html) for the client-library layer. Last updated: July 23, 2026.

# Actor input Schema

## `session` (type: `string`):

Optional Telethon StringSession for a Telegram user account. Anyone holding it may be able to act as that account. If omitted, QR login is attempted and the generated session is printed in logs and sent to Saved Messages.

## `password` (type: `string`):

Optional Telegram two-step-verification password used during authorization. It does not replace the session.

## `group_match` (type: `string`):

Non-empty case-insensitive substring compared with accessible basic-group and supergroup dialog titles, usernames, and numeric IDs. Runtime keeps the last match returned by the dialog scan, so use a distinctive value and verify logs.

## `deep_search` (type: `boolean`):

When true, adds 36 participant-search queries and resolves senders from sampled message-history ranges. It does not bypass Telegram access or hidden-member controls. Free-plan runs force this to false.

## `max_results` (type: `integer`):

Requested stopping threshold from 100 to 100,000. Runtime checks it between whole result batches, so a batch can make Dataset rows and charges exceed this value. Free-plan runs reduce it to 100.

## Actor input object example

```json
{
  "group_match": "binance",
  "max_results": 100
}
```

# Actor output Schema

## `results` (type: `string`):

Open accessible member observations. max\_results is a between-batch stopping threshold and can be exceeded; fatal login or group-selection failures can finish with zero rows.

# 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 = {
    "group_match": "binance",
    "deep_search": false,
    "max_results": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("agentx/telegram-private-group-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 = {
    "group_match": "binance",
    "deep_search": False,
    "max_results": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("agentx/telegram-private-group-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 '{
  "group_match": "binance",
  "deep_search": false,
  "max_results": 100
}' |
apify call agentx/telegram-private-group-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/L4SPW5ECJb9gP5aDT/builds/F4O3UzBoA2w1A13ee/openapi.json