# Telegram Profile (`truefetch/telegram-profile`) Actor

Telegram profile scraper for resolving up to 1,000 usernames, @handles, t.me URLs, accessible invites, or phone numbers into 41-field sparse profiles for users, bots, channels, groups, and supergroups, including identity, public flags, counts, business details, and photo links.

- **URL**: https://apify.com/truefetch/telegram-profile.md
- **Developed by:** [TrueFetch](https://apify.com/truefetch) (community)
- **Categories:** Social media, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 1,310 total users, 47 monthly users, 99.9% runs succeeded, 18 bookmarks
- **User rating**: 4.87 out of 5 stars

## Pricing

from $2.25 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Telegram Profile

**Telegram Profile is a telegram profile scraper that converts public Telegram identifiers into 41-field sparse profiles for users, bots, channels, groups, and supergroups.** It accepts up to 1,000 usernames, `@handles`, canonical `t.me` links, accessible invite references, or authorized phone numbers per run.

- **One mixed target list:** resolve several Telegram entity types without selecting a mode first.
- **Stable sparse contract:** keep correlation, identity, public state, community facts, and provenance in one Dataset shape.
- **Privacy-conscious output:** mask phone and invite correlations and exclude source-account credentials or relationship state.
- **Source-backed billing:** charge Result only when a resolved or normal not-found row is saved.

[**Run a one-result test**](https://apify.com/truefetch/telegram-profile/input) · [**View API**](https://apify.com/truefetch/telegram-profile/api)

The smallest FREE-tier run is **$0.01300**: one $0.01 Actor Start plus one $0.00300 Result.

### What does Telegram Profile do?

Telegram Profile resolves each supported identifier and classifies the returned entity as a user, bot, broadcast channel, group, or supergroup. A common row carries the original query position, sanitized query value, source-backed status, entity type, stable Telegram ID, active username data, and provenance. Entity-specific fields then add the public facts relevant to that branch.

User and bot rows may contain names, visible description, presence category, public flags, color and emoji status, birthday or business details, personal-channel context, profile music, monetization facts, and declared bot commands or features. Channel and group rows may contain title, description, creation time, participant counts, forum and join flags, reactions, slow mode, pinned message, linked chat, public bots, sticker set, location, and other community settings.

The result is intentionally sparse. Forty-one describes the union of possible top-level fields, not the number filled on every row. A not-found record needs only correlation, status, and provenance; a bot and a supergroup populate different sections. Missing fields remain missing instead of being filled with guessed defaults.

### How do I run Telegram Profile?

Use the input form with its one-channel example:

```json
{
  "telegram_url": [
    "telegram"
  ]
}
```

Start the Actor and open the default Dataset. The example should return a `success` row with `type` equal to `channel`, `username` equal to `telegram`, and current public channel facts. The live values can change, so validate the shape and status rather than a hardcoded member count.

After the one-result test, add a small authorized mixture such as a user, bot, and group. Compare the number of unique normalized inputs with Dataset rows. A run that finishes successfully can still contain `not_found` results or omit transiently unavailable targets; inspect each row instead of relying only on the terminal run status.

Free-plan runs resolve the first 10 unique targets. Paying runs accept up to 1,000 entries. Source availability, account rotation, profile-photo work, deliberate pacing, and the run timeout remain practical completion limits.

### What data does Telegram Profile return?

The default Dataset exposes this 41-field sparse union:

| Area | Fields |
| --- | --- |
| Correlation and outcome | `query_index`, `query`, `status`, `type` |
| Core identity | `id`, `username`, `usernames`, `source_url`, `title`, `first_name`, `last_name`, `description` |
| Photo and public state | `photo_url`, `has_photo`, `flags`, `restrictions`, `last_seen`, `colors`, `emoji_status` |
| Profile extensions | `personal_channel`, `birthday`, `business`, `profile_music`, `monetization`, `bot_info` |
| Community facts | `created_at`, `member_count`, `online_count`, `chat_level`, `chat_flags`, `location`, `slowmode_seconds` |
| Community relationships | `linked_chat_id`, `linked_monoforum_id`, `pinned_message_id`, `default_restrictions`, `available_reactions`, `chat_bots`, `sticker_set` |
| Provenance | `processor`, `processed_at` |

A compact channel row can look like this:

```json
{
  "query_index": 1,
  "query": "@telegram",
  "status": "success",
  "type": "channel",
  "id": 1005640892,
  "username": "telegram",
  "usernames": ["telegram"],
  "source_url": "https://t.me/telegram",
  "title": "Telegram News",
  "has_photo": true,
  "flags": ["verified"],
  "member_count": 9800000,
  "processor": "https://apify.com/username/actor_name",
  "processed_at": "2026-08-12T13:00:00+00:00"
}
```

The count is illustrative. Telegram controls current values and visibility. `photo_url` is present only after both download and storage succeed; `has_photo` can be true while no stored link is available.

### What inputs can I configure?

`telegram_url` is the only input and is required. Despite its singular historical name, it is an array of 1 to 1,000 strings.

| Accepted form | Example | Notes |
| --- | --- | --- |
| Bare username | `telegram` | Public username without `@` |
| Handle | `@BotFather` | Normalized to the same public identity |
| Canonical URL | `https://t.me/telegram` | Telegram hosts only |
| Preview URL | `https://t.me/s/telegram` | Public preview form |
| Invite reference | accessible invite | Does not grant access |
| International phone | authorized `+...` value | Correlation is masked |

Foreign hosts, unrelated paths, ports, query strings, blank items, wrong list types, and invalid invite forms are rejected explicitly. Equivalent public identifiers are deduplicated before source work. Input order remains available through `query_index`.

An invite succeeds only when the managed source account can already resolve it. A phone succeeds only when Telegram permits the lookup. Neither input form overrides privacy or access controls.

### What platforms and markets does Telegram Profile cover?

Coverage is Telegram-wide rather than country-specific. Public username resolution is not limited to a market or language. Returned names, descriptions, commands, and titles retain source text, including Unicode.

The Actor covers users, bots, broadcast channels, groups, and supergroups/forums that Telegram makes resolvable through the supported identifier path. It does not scrape messages, export complete member lists, join arbitrary private communities, or infer personal identity from a username.

Official Telegram documentation describes [user profile attributes](https://core.telegram.org/api/profile), the [user entity constructor](https://core.telegram.org/constructor/user), and [deep-link forms](https://core.telegram.org/api/links). Actual availability still depends on the live entity and source response.

### Why use Telegram Profile?

Use it when a workflow needs repeatable JSON rather than a manual profile view. The Dataset keeps normalized identity and entity-specific context together, making it easier to route downstream processing without a separate pre-classification call.

Use it for sparse data quality. The Actor does not claim that every field applies to every entity, and it avoids filling unavailable values with zeros or false flags. That matters when a downstream model, database, or analyst must distinguish “not present” from “observed false.”

Use it for safer correlation. Submitted phone numbers and invite tokens are masked in output, while access hashes, file references, source-account permissions, contact relationships, private read state, and session credentials are excluded entirely.

Use it for controlled automation. Apify supplies API calls, schedules, webhooks, Dataset exports, key-value storage for successfully saved profile photos, and maximum-charge controls around the same input contract.

### Who is Telegram Profile for?

**Data engineers** can normalize a bounded authorized identifier list before joining Telegram facts to an internal record.

**Community analysts** can observe current public titles, usernames, descriptions, member counts, flags, linked chats, reactions, forum settings, and location when exposed.

**Bot developers** can inventory public bot descriptions, commands, menu links, feature declarations, active-user estimates, and app colors.

**Trust and safety teams** can retain Telegram-provided verified, fake, scam, deleted, or restricted labels as source signals inside a wider human review. Those labels are not independent proof.

The Actor is not appropriate for harassment, doxxing, surveillance, sensitive profiling, spam, identity verification, unauthorized phone discovery, or access-control bypass.

### How can I use Telegram Profile through the API or MCP?

Actor ID `awbkkk1w2CKtNBScC` runs the same one-result example synchronously. It is also addressable by name as `truefetch/telegram-profile`, and both forms work in the API, the SDKs, and the integrations below.

```bash
curl -X POST "https://api.apify.com/v2/acts/awbkkk1w2CKtNBScC/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"telegram_url":["telegram"]}'
```

Store the token securely and use asynchronous runs for larger lists. Poll the run, fetch the default Dataset, and compare statuses and row count with normalized inputs before treating the batch as complete.

MCP uses the official Apify server with the same scenario:

```json
{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": [
        "-y",
        "@apify/actors-mcp-server",
        "--actors",
        "truefetch/telegram-profile"
      ],
      "env": { "APIFY_TOKEN": "YOUR_TOKEN" }
    }
  }
}
```

Load the current schema from the server, then send `telegram_url` exactly as above.

The same Actor can be connected to schedules, webhooks, Make, n8n, or a custom client. Keep one canonical input object across integrations and apply `maxTotalChargeUsd` when a workflow needs an enforceable budget.

### How much does Telegram Profile cost?

Pricing uses two event types. Actor Start is charged once. Result is charged for each persisted source-backed profile or normal not-found row.

| Event | FREE | BRONZE | SILVER | GOLD | PLATINUM | DIAMOND |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| Actor Start | $0.01000 | $0.01000 | $0.01000 | $0.01000 | $0.01000 | $0.01000 |
| Result | $0.00300 | $0.00270 | $0.00240 | $0.00225 | $0.00225 | $0.00225 |

One FREE-tier result is $0.01300. Ten results are $0.04000: `$0.01 + 10 × $0.00300`. A normal `not_found` row is a Result because it is a real source outcome. A transient unavailable target that produces no row is not billed as a Result.

Actual charges depend on emitted events and current published pricing. Set a maximum total charge before an unattended large-list run.

### How does Telegram Profile compare with alternatives?

Choose this Actor when the primary object is entity metadata. Choose Telegram Channel Message when the primary object is post history. Choose Telegram Group Member when the primary object is a visible participant list from a known community.

Telegram's native apps are simpler for occasional manual inspection. This Actor adds value when a job needs bulk input, stable JSON, source status, sparse schema, Dataset export, scheduled execution, or an API/MCP surface.

A generic web-page parser may see only Telegram's public preview surface. This Actor uses a managed Telegram source session and can expose the public entity fields available through that path, but it still cannot make inaccessible private facts public or guarantee that every identifier resolves.

### What are the limits and troubleshooting steps?

- **The row count is lower than expected:** account for free-plan truncation, identifier deduplication, transient source failures, and stopped runs. Inspect Dataset statuses.
- **A target is `not_found`:** retry a known canonical public username. Do not treat one lookup as proof that the entity never existed.
- **A photo link is absent:** the profile may expose no photo, download can fail, or storage can fail. No synthetic URL is emitted.
- **A private invite fails:** the managed source account must already have legitimate access. The Actor does not join arbitrary private spaces.
- **A phone lookup fails:** confirm authorized international format and expect Telegram privacy to control the result.
- **A large run takes too long:** each unique target can require resolution, a full-record request, photo work, and pacing. Measure 1 and 10 targets before scaling.

Rows are flushed in small batches, so completed batches remain if a later failure or explicit stop ends the run. Keep the run ID when contacting support and sanitize every sensitive input.

### Frequently asked questions

#### Can I use a telegram profile info api for bots and channels?

Yes. The same input list can resolve users, bots, channels, groups, and supergroups. Each result uses the shared sparse contract and populates only its applicable fields.

#### How do I check telegram profile details in bulk?

Submit up to 1,000 supported identifiers in `telegram_url`. Free runs keep the first 10 unique targets. Start with a small batch, then compare returned statuses and row count before scaling.

#### Does every row contain 41 fields?

No. Forty-one is the top-level union. A user, bot, channel, group, supergroup, and not-found result have different applicable subsets.

#### Are normal not-found rows charged?

Yes. They are persisted source outcomes and use the Result event. A transient target that yields no row does not create a Result charge.

#### Can it reveal who viewed a Telegram profile?

No. Telegram does not expose a supported profile-viewer list through this contract. The Actor does not infer or fabricate one.

#### Does it require my Telegram credentials?

No credential input is exposed. The Actor uses managed source accounts. This does not guarantee access to private entities or hidden fields.

### Related TrueFetch Actors

- [Telegram Channel Message](https://apify.com/truefetch/telegram-channel-message) exports public channel, group, and forum message history with optional media.
- [Telegram Group Member](https://apify.com/truefetch/telegram-group-member) exports visible participant facts from a permitted Telegram community.
- [Reddit User Profile](https://apify.com/truefetch/reddit-user-profile) resolves a different network's public account profile into structured data.

### Support

For help, contact the [TrueFetch Telegram group](https://t.me/TrueFetch) with the Actor name, run ID, sanitized input form, expected unique-target count, returned row count, and relevant statuses. Never post API tokens, phone numbers, invite tokens, session data, downloaded personal files, or other secrets.

Use only data you are authorized to process. Follow Telegram's terms, applicable law, privacy duties, copyright, and retention requirements. Verify consequential facts at the original Telegram surface.

**Last Updated:** August 15, 2026

# Actor input Schema

## `telegram_url` (type: `array`):

Telegram profiles to resolve, one per line. Accepts 1 to 1,000 bare usernames, @handles, canonical t.me and t.me/s URLs, accessible invite references, or authorized international phone numbers. Equivalent identifiers are deduplicated, sensitive phone and invite correlations are masked, and free-plan runs keep the first 10 unique targets.

## Actor input object example

```json
{
  "telegram_url": [
    "telegram"
  ]
}
```

# Actor output Schema

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

Source-backed success and not-found records in the default Dataset.

# 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 = {
    "telegram_url": [
        "telegram"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("truefetch/telegram-profile").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 = { "telegram_url": ["telegram"] }

# Run the Actor and wait for it to finish
run = client.actor("truefetch/telegram-profile").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "telegram_url": [
    "telegram"
  ]
}' |
apify call truefetch/telegram-profile --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,truefetch/telegram-profile"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/awbkkk1w2CKtNBScC/builds/gz1YdCuCY4bhO2nti/openapi.json