# Telegram Profile Scraper (`brilliant_gum/telegram-profile-scraper`) Actor Extract 80+ fields from any Telegram account by username, @handle, t.me link, or phone number. Users, bots, channels, groups. Includes trust score, DC geolocation, account age, bio parsing, and collectible username detection. - **URL**: https://apify.com/brilliant\_gum/telegram-profile-scraper.md - **Developed by:** [Yuliia Kulakova](https://apify.com/brilliant_gum) (community) - **Categories:** Social media, Lead generation, AI - **Stats:** 10 total users, 5 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $300.00 / 1,000 profile lookups This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 Profile Scraper ![Telegram Profile Scraper](https://i.imgur.com/QPPlDvM.jpg) Extract a full intelligence profile from any Telegram account in seconds. Give us a username, a link, or a phone number — we return 80+ fields of structured data including built-in trust scoring, DC geolocation, account age estimation, and bio parsing. No browser, no proxies, no manual work. --- ### What You Get Point it at any Telegram username, @handle, t.me link, or phone number. The actor resolves the entity, pulls all available metadata via the official Telegram MTProto API, and returns clean JSON — ready for your database, CRM, or analysis pipeline. **Works for users, bots, channels, and groups. All in one tool.** --- ### Features #### 🔍 Universal Input Mix any format in a single run — plain usernames, @handles, t.me short links, full URLs, or phone numbers. The actor auto-detects and handles each correctly. #### 👤 Full User Profiles First name, last name, bio, last seen (with Unix timestamp), Premium status, verified badge, scam/fake flags, birthday, business info, privacy settings, emoji status, name color, personal channel ID, and more. #### 🤖 Complete Bot Intelligence Commands list, bot description, active users count, web app URL, inline mode placeholder, business bot flag, attachment menu status — everything the Bot API exposes, and more. #### 📢 Channel & Group Analytics Member count, online count, admin count, banned/kicked counts, creation date, linked discussion group, slowmode, forum flag, star gifts, monetization flags (paid messages, paid media), and live stream status. #### 📍 DC Geolocation Identifies which Telegram data center hosts the account based on the profile photo DC ID. Returns region and city — a reliable signal for account origin. | DC | Region | City | |----|--------|------| | 1 | US | Miami | | 2 | EU | Amsterdam | | 3 | US | Miami | | 4 | EU | Amsterdam | | 5 | Asia | Singapore | #### 📅 Account Age Estimation Estimates how old a Telegram account is by interpolating the user ID against known registration date ranges. Accurate to within weeks for most accounts. #### 🏆 Trust Score (0–100) Computed locally from all available signals: | Score | Meaning | |-------|---------| | 70–100 | Trusted — verified, complete, established account | | 40–69 | Mixed — some signals missing or inconsistent | | 0–39 | Suspicious — scam flag, fake flag, deleted, or unverified bot | #### 📊 Profile Completeness (0–100) Scores how complete the profile is — photo, bio, username, name, birthday, business info, premium, verified badge. #### 🔗 Bio Parsing Automatically extracts emails, URLs, @handles, and phone numbers from bio text. No regex needed on your end. #### 💎 Collectible Username Detection Detects Fragment NFT usernames (non-editable handles bought on the Fragment marketplace). Returned separately in `collectible_usernames`. #### 🖼️ Profile Photo History Optionally downloads up to 5 historical profile photos per user and stores them in Apify Key-Value Store with public URLs. #### ⚡ Smart Rate Limit Handling Automatically detects Telegram FLOOD_WAIT errors, waits the required time, and retries — instead of failing the run. --- ### Pricing | Event | Price | When Charged | |-------|-------|-------------| | Profile lookup (username/URL) | **$0.30** | Per resolved profile | | Phone number lookup | **$0.50** | Per phone number resolved | > 💡 **Example:** 1,000 username lookups = **$300** > > Set a budget cap in Apify — the actor stops gracefully when the limit is hit. --- ### Input ```json { "targets": [ "durov", "@BotFather", "t.me/telegram", "https://t.me/Apify_Actor", "+14155552671" ], "includeProfilePhotos": false, "concurrency": 3, "timeoutMs": 30000 } ```` #### Input Fields | Field | Type | Default | Description | |-------|------|---------|-------------| | `targets` | array | **required** | Telegram targets. Max 10,000 per run. | | `includeProfilePhotos` | boolean | `false` | Download up to 5 historical profile photos per user/bot | | `concurrency` | integer | `3` | Parallel lookups (1–20). Keep low to avoid rate limits. | | `timeoutMs` | integer | `30000` | Timeout per lookup in milliseconds | #### Supported Input Formats | Format | Example | |--------|---------| | Plain username | `durov` | | @handle | `@BotFather` | | t.me short link | `t.me/telegram` | | Full URL | `https://t.me/Apify_Actor` | | Phone number | `+14155552671` | *** ### Output ```json { "status": "success", "source_input": "durov", "processed_at": "2026-05-05T11:35:12.009Z", "type": "channel", "id": 1006503122, "usernames": ["durov", "rove", "paul", "snow", "feed", "lean"], "collectible_usernames": ["rove", "paul", "snow", "feed", "lean"], "title": "Pavel Durov", "description": "Founder of Telegram.", "profile_photo": true, "photo_url": "https://api.apify.com/v2/key-value-stores/.../records/photo-1006503122", "is_verified": true, "is_scam": false, "is_fake": false, "member_count": 10117792, "stargifts_count": 46916, "data_center": { "id": 2, "region": "EU", "city": "Amsterdam" }, "profile_completeness": 45, "trust_score": 85 } ``` #### Key Output Fields | Field | Types | Description | |-------|-------|-------------| | `status` | All | `success`, `not_found`, or `error` | | `type` | All | `user`, `bot`, `channel`, `supergroup`, `group` | | `id` | All | Permanent Telegram numeric ID | | `usernames` | All | All active usernames | | `collectible_usernames` | All | Fragment NFT (non-editable) usernames | | `first_name` / `last_name` | User/Bot | Name fields | | `title` | Channel/Group | Channel or group title | | `description` | All | Bio / about text | | `photo_url` | All | Downloaded profile photo URL | | `photo_urls` | User/Bot | Up to 5 historical photos (if enabled) | | `is_premium` | User | Telegram Premium subscriber | | `is_verified` | All | Blue checkmark | | `is_scam` / `is_fake` | All | Flagged by Telegram | | `last_seen` | User | `online`, ISO timestamp, or `recently` | | `last_seen_timestamp` | User | Unix timestamp (when available) | | `birthday` | User | `{ day, month, year }` | | `emoji_status` | User | Custom emoji status document ID | | `bot_commands` | Bot | Full list with descriptions | | `bot_active_users` | Bot | Estimated active users | | `member_count` | Channel/Group | Total subscribers/members | | `admins_count` | Channel/Group | Number of admins | | `created_date` | Channel/Group | ISO creation timestamp | | `stargifts_count` | All | Total star gifts received | | `data_center` | All | `{ id, region, city }` | | `estimated_account_age_days` | User/Bot | Days since registration | | `profile_completeness` | All | 0–100 completeness score | | `trust_score` | All | 0–100 trust score | | `bio_extracted` | All | `{ emails, urls, handles, phones }` parsed from bio | *** ### Use Cases 🔎 **OSINT Investigations** — Build a full intelligence profile on any Telegram identity from a single input. Cross-reference IDs, usernames, DC locations, and account age. 📋 **Lead Enrichment** — Look up phone numbers from your CRM to find Telegram presence, bio, and profile data automatically. 🛡️ **Fraud & Scam Detection** — Identify accounts flagged by Telegram, check trust scores, detect VoIP numbers, and flag newly created accounts. 📊 **Channel Analytics** — Pull member counts, admin counts, online stats, creation dates, star gifts, and monetization data for any public channel. 🤖 **Bot Research** — Analyze bot commands, active user counts, web app URLs, and capabilities across multiple bots at once. 🔍 **Competitor Intelligence** — Monitor competitor Telegram channels with full metadata — growth, engagement signals, linked groups, and more. *** ### FAQ **What input formats are supported?** Plain usernames, @handles, t.me short links, full t.me URLs, and phone numbers — all in one run. **Does phone lookup always work?** Phone lookup uses the Telegram contacts API. If the target has set "Who can find me by phone number" to "Nobody" in their privacy settings, it will return `not_found`. This is expected behavior — the data is private by their choice. **What entity types are supported?** Users, bots, channels, supergroups, and groups. The actor auto-detects the type and returns the relevant fields for each. **Can I process large lists?** Yes — up to 10,000 targets per run. Keep `concurrency` at 3–5 to stay within Telegram rate limits. **What happens on rate limits?** The actor detects `FLOOD_WAIT` errors automatically, waits the required time (up to 60 seconds), and retries. If the wait is longer than 60 seconds, the target is skipped with an error status. **Are the intelligence fields accurate?** DC geolocation is based on profile photo DC — highly reliable. Account age is estimated from Telegram ID ranges — accurate to within a few weeks for most accounts. Trust and completeness scores are computed locally from available signals. # Actor input Schema ## `targets` (type: `array`): List of Telegram targets to look up. Supports usernames (durov), @handles (@BotFather), t.me URLs (https://t.me/telegram), and phone numbers (+14155552671). ## `includeProfilePhotos` (type: `boolean`): Download up to 5 historical profile photos per user and store them in Key-Value Store. Adds extra API calls. ## `concurrency` (type: `integer`): How many targets to process in parallel. Keep low (1-5) to avoid Telegram rate limits. ## `timeoutMs` (type: `integer`): Timeout per target lookup in milliseconds. ## Actor input object example ```json { "targets": [ "durov", "@BotFather", "t.me/telegram" ], "includeProfilePhotos": false, "concurrency": 3, "timeoutMs": 30000 } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = { "targets": [ "durov", "@BotFather", "t.me/telegram" ] }; // Run the Actor and wait for it to finish const run = await client.actor("brilliant_gum/telegram-profile-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 = { "targets": [ "durov", "@BotFather", "t.me/telegram", ] } # Run the Actor and wait for it to finish run = client.actor("brilliant_gum/telegram-profile-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 '{ "targets": [ "durov", "@BotFather", "t.me/telegram" ] }' | apify call brilliant_gum/telegram-profile-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=brilliant_gum/telegram-profile-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Telegram Profile Scraper", "description": "Extract 80+ fields from any Telegram account by username, @handle, t.me link, or phone number. Users, bots, channels, groups. Includes trust score, DC geolocation, account age, bio parsing, and collectible username detection.", "version": "1.0", "x-build-id": "CVOAn6tfpXyXH73ga" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/brilliant_gum~telegram-profile-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-brilliant_gum-telegram-profile-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/brilliant_gum~telegram-profile-scraper/runs": { "post": { "operationId": "runs-sync-brilliant_gum-telegram-profile-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/brilliant_gum~telegram-profile-scraper/run-sync": { "post": { "operationId": "run-sync-brilliant_gum-telegram-profile-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", "required": [ "targets" ], "properties": { "targets": { "title": "Telegram Targets", "minItems": 1, "maxItems": 10000, "type": "array", "description": "List of Telegram targets to look up. Supports usernames (durov), @handles (@BotFather), t.me URLs (https://t.me/telegram), and phone numbers (+14155552671).", "items": { "type": "string" } }, "includeProfilePhotos": { "title": "Include Profile Photo History", "type": "boolean", "description": "Download up to 5 historical profile photos per user and store them in Key-Value Store. Adds extra API calls.", "default": false }, "concurrency": { "title": "Concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many targets to process in parallel. Keep low (1-5) to avoid Telegram rate limits.", "default": 3 }, "timeoutMs": { "title": "Timeout (ms)", "minimum": 5000, "maximum": 120000, "type": "integer", "description": "Timeout per target lookup in milliseconds.", "default": 30000 } } }, "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 } } } } } } } } } } ```