# Telegram Username Search & Enumeration (`arjuna-x_official-owner/telegram-username-enum`) Actor

Telegram suffix-range enumeration: scan bitcoin1–bitcoin200 in one run. Brand protection & lookalike discovery tool & not a single-username checker. Pay per valid account only (~$7/1k valid accounts); empty checks not billed. No login.

- **URL**: https://apify.com/arjuna-x\_official-owner/telegram-username-enum.md
- **Developed by:** [Arjuna-X Official](https://apify.com/arjuna-x_official-owner) (community)
- **Categories:** Social media, Automation, Developer tools
- **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $5.00 / 1,000 valid telegram accounts

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?

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 Username Search & Enumeration

### What does Telegram Username Search & Enumeration do?

**Range enumeration for Telegram** — not a single-username checker. Enter a base keyword (for example `bitcoin`) and a suffix range (`1` to `100`, `a` to `z`), and this Actor expands every candidate in one run: `bitcoin1`, `bitcoin2`, … `bitcoin100`.

That is the workflow brand protection, security, and OSINT teams need for **lookalike discovery** and **suffix sweeps** — coverage a list-based checker cannot give you without building the list yourself.

Built for teams that need wide range coverage at speed. **Pay only for valid accounts found**; empty checks are not billed.

### Range enumeration, not username checking

Most Store Actors check **one username at a time** or a list you supply. This Actor **generates and scans the full suffix range** from a single base keyword — numeric (`1`–`1000`), alphabetic (`a`–`z`, `aa`–`zz`), or custom start/end.

Use it when you need to answer: *"Which `bitcoin*` Telegram accounts exist in this suffix range?"* — not *"Does `@bitcoin42` exist?"*

### What you get for each valid account

For every existing account found, the Dataset includes:

- **Account name**
- **Handle / members / subscribers**
- **Description**
- **Type of account** (`user`, `group`, or `channel`)
- **Direct Telegram URL** and full username

### Why this pricing is different

Most username tools bill **per check**: every candidate in your list or range costs money, whether the account exists or not. Scan 1,000 lookalikes and you pay for 1,000 attempts — even when almost all are empty.

**We bill per valid account.** Empty candidates are not charged by the custom result event. Your budget buys signal (real accounts with metadata), not noise.

That matters most on brand and lookalike sweeps, where hit rates are often low. Large ranges stay affordable because unused names do not drain spend. Set a **maximum cost per run** anytime you want a hard cap.

Illustrative costs for a **1,000-candidate** run (example rates — check the **Pricing** tab for live numbers):

| Hit rate | Valids found | Typical per-check tool (~$0.015–$0.02 / check) | This Actor (pay per valid, example ~$0.007 / valid) |
|----------|--------------|--------------------------------------------------|-----------------------------------------------------|
| Sparse (~2%) | 20 | ~$15–$20 | **~$0.14** |
| Moderate (~14%) | 140 | ~$15–$20 | **~$0.98** |
| Dense (~40%) | 400 | ~$15–$20 | **~$2.80** |

Per-check pricing stays roughly flat no matter how few accounts exist. Pay-per-valid scales with finds — so sparse brand protection work costs less here, and you never pay just to learn a name is unused.

### Features

- **Suffix-range enumeration** — the only workflow you need for `base + suffix` sweeps; not a one-off username checker
- **Built for sourcing at speed** — concurrent checks so large ranges finish fast
- **Numeric or letter ranges** — `1` to `1000`, `a` to `z`, `aa` to `zz`, and similar
- **Pay per valid account** — never billed for empty checks (default); you buy finds, not attempts
- **Rich public metadata** — name, member/subscriber hint, description, and account type on every hit
- **Deduplication** — skip accounts you already collected on earlier runs
- **Large-range auto-tuning** — ranges over 100 candidates auto-enable Apify Proxy, concurrency 5, and 300 ms delay
- **No Telegram login** — start from the Console; no QR code or Live View required

### Why enumerate Telegram accounts?

Brands and investigators need to know which lookalike accounts exist: `bitcoin1`, `bitcoin99`, `bitcoin_hq`, and similar patterns. Doing that by hand does not scale. This Actor turns a base keyword plus suffix range into a dataset you can export, monitor, and act on.

### How to run

1. Click **Try for free** / open the Actor.
2. Set **Base username prefix** (letters, digits, underscore - no `@`).
3. Set **Range start** and optional **Range end** (or leave end empty to scan `1` to start for numbers).
4. For ranges **over 100**, Apify Proxy, concurrency **5**, and **300 ms** delay are applied automatically. Set a **maximum cost per run** for large jobs.
5. Click **Start**.
6. When the run finishes, open the **Output** / **Dataset** tab to preview or download results.

#### Tips

- Start with a small range to estimate cost, then scale up.
- Ranges over **100** auto-enable proxy + gentler pacing — avoids datacenter rate limits on `t.me`.
- Use a proxy region that matches the audience you care about (visibility can differ by country).
- Keep `onlyNewResults: true` for recurring brand monitoring.

### How much will it cost?

**Pay per valid account found.** Platform usage is included.

- Valid accounts = billed
- Empty / non-existent candidates = **not billed** (when `includeMisses` is off, the default)

You are not paying to learn that a name is unused. You are paying for accounts that exist, with metadata ready to use.

Check the **Pricing** tab for current rates. Before a large job, set a **maximum cost per run** so spend never surprises you.

Apify also gives monthly free usage credits on the Free plan. A short test run is the fastest way to see real cost for your range.

### Input example

```json
{
  "base": "bitcoin",
  "start": "1",
  "end": "100",
  "concurrency": 10,
  "maxCandidates": 2000,
  "onlyNewResults": true,
  "includeMisses": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

| Field | Meaning |
|-------|---------|
| `base` | Prefix to expand (required) |
| `start` / `end` | Suffix range (digits or equal-length letters) |
| `concurrency` | Parallel workers (lower if you hit rate limits) |
| `onlyNewResults` | Skip URLs already seen in prior runs |
| `includeMisses` | Also store non-existent names (usually leave off) |

### Output example

One Dataset item per found account:

```json
[
  {
    "url": "https://t.me/bitcoin42",
    "username": "bitcoin42",
    "base": "bitcoin",
    "suffix": "42",
    "exists": true,
    "title": "Example Brand",
    "extra": "@bitcoin42",
    "description": "Official brand account",
    "pageType": "user",
    "httpStatus": 200
  }
]
```

### Compliance

Use only for legitimate research, brand protection, or investigations you are authorized to perform. Respect Telegram's Terms of Service and applicable law.

# Actor input Schema

## `base` (type: `string`):

Prefix of the Telegram username to enumerate (letters/digits/underscore; no @).

## `start` (type: `string`):

Start of the suffix range. Digits (1, 01, 100) or lowercase letters of equal length (a, aa). If end is empty, treats start as max and scans 1 → start.

## `end` (type: `string`):

End of the suffix range. Leave empty to scan 1 → start (numeric only).

## `maxCandidates` (type: `integer`):

Hard safety cap on how many usernames to check in one run.

## `concurrency` (type: `integer`):

How many checks to run in parallel. For ranges over 100 candidates the Actor auto-uses 5 to reduce rate limits.

## `requestTimeoutSec` (type: `integer`):

Maximum wait time for each account check before retrying or moving on.

## `maxRetries` (type: `integer`):

Retries on temporary network errors (not on a definitive miss).

## `delayMs` (type: `integer`):

Optional pause after each attempt. For ranges over 100 candidates the Actor auto-uses 300 ms.

## `onlyNewResults` (type: `boolean`):

If true, skip accounts already returned in your earlier runs of this Actor. Other users' runs never affect yours.

## `includeMisses` (type: `boolean`):

If true, also include rows for usernames that do not resolve (exists=false).

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

Apify Proxy. Auto-enabled when the range exceeds 100 candidates (unless custom proxy URLs are set).

## `userAgent` (type: `string`):

Optional client identity string used for account checks.

## Actor input object example

```json
{
  "base": "bitcoin",
  "start": "1",
  "end": "20",
  "maxCandidates": 2000,
  "concurrency": 10,
  "requestTimeoutSec": 15,
  "maxRetries": 2,
  "delayMs": 0,
  "onlyNewResults": true,
  "includeMisses": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
}
```

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "base": "bitcoin",
    "start": "1",
    "end": "20"
};

// Run the Actor and wait for it to finish
const run = await client.actor("arjuna-x_official-owner/telegram-username-enum").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 = {
    "base": "bitcoin",
    "start": "1",
    "end": "20",
}

# Run the Actor and wait for it to finish
run = client.actor("arjuna-x_official-owner/telegram-username-enum").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 '{
  "base": "bitcoin",
  "start": "1",
  "end": "20"
}' |
apify call arjuna-x_official-owner/telegram-username-enum --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,arjuna-x_official-owner/telegram-username-enum"
        }
    }
}

```

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/JZbQychnBgtTdvVfA/builds/Oh31ycLa8N4Z1rKzZ/openapi.json