Telegram Private Group Scraper

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, use the Apify API, or connect through 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.

{
  "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.

{
  "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.

{
  "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, peer behavior, and 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 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 — use a public or separately authorized member workflow.
• Telegram Chat Scraper — collect authorized chat observations rather than member profiles.
• Telegram Info Scraper — retrieve public Telegram entity metadata.
• Telegram Group Inviter — invite only people who expect it; scraped membership is not consent.
• Reddit Author Scraper — a separate public-author observation workflow.
• Twitter Info Scraper — 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. Review Telethon session security and Telethon chat/participant examples for the client-library layer. Last updated: July 23, 2026.