# 🚀 TGStat Channel Parser (`backhoe/tgstat-channel-parser`) Actor

Extract comprehensive Telegram channel statistics from TGStat.com using intelligent AI-powered search...

- **URL**: https://apify.com/backhoe/tgstat-channel-parser.md
- **Developed by:** [D](https://apify.com/backhoe) (community)
- **Categories:** E-commerce, Automation, Social media
- **Stats:** 27 total users, 0 monthly users, 100.0% runs succeeded, 3 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

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

## 🚀 TGStat Channel Parser - Free Telegram Analytics

**Unlock the power of Telegram channel data with zero cost!** This Apify actor scrapes comprehensive channel statistics from TGStat.com, the leading Telegram analytics platform. Perfect for marketers, researchers, and growth hackers looking to discover trending channels, analyze competitors, and build targeted audiences.

### 🎯 Why Choose This Actor?

**100% Free** • **AI-Powered Search** • **Residential Proxies Included** • **Real-Time Data** • **Unlimited Channels** • **No Rate Limits**

Discover thousands of Telegram channels in minutes, not hours. Our intelligent half-division algorithm efficiently navigates TGStat's database to find exactly what you need.

### ✨ Premium Features (All Free!)

- ✅ **Smart Search Algorithm** - Adaptive half-division strategy finds channels 10x faster
- ✅ **Zero Rate Limits** - Built-in exponential backoff handles TGStat restrictions automatically
- ✅ **Premium Proxies Included** - Residential proxy support at no extra cost
- ✅ **Real-Time Streaming** - Results pushed to your dataset as they're discovered
- ✅ **Flexible Filtering** - Target exact subscriber ranges, languages, and countries
- ✅ **Memory Optimized** - Runs efficiently on just 128 MB
- ✅ **Comprehensive Data** - Get subscribers, engagement rates, daily reach, and more
- ✅ **100% Free** - No hidden costs, no credit card required

### 📥 Input Parameters

**Simple configuration, powerful results!** Just set your subscriber range and let the actor do the rest.

```json
{
  "min_subscribers": 100,
  "max_subscribers": 100000000000,
  "limit": null,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
````

#### 🎛️ Parameter Details:

##### **min\_subscribers** (default: `100`)

- **Type**: Integer
- **Description**: Set the minimum subscriber count threshold. Perfect for filtering out small channels and focusing on established communities. Start from 100 to discover growing channels or set higher (e.g., 1000+) for premium audiences.
- **Example**: `1000` - Find channels with at least 1K subscribers
- **💡 Pro Tip**: Use 100-500 for emerging influencers, 5K+ for established channels
- **100% Free** - No limits on range size!

##### **max\_subscribers** (default: `100000000000`)

- **Type**: Integer
- **Description**: Define the upper limit for subscriber count. Ideal for targeting specific audience sizes or avoiding mega-channels. Set to 100B for unlimited reach.
- **Example**: `50000` - Cap at 50K subscribers for mid-tier channels
- **💡 Pro Tip**: Use 10K-100K range for highly engaged communities
- **Free Unlimited Scraping** - No caps on results!

##### **limit** (default: `null`)

- **Type**: Integer or null
- **Description**: Cap the total number of channels to collect. Leave empty (`null`) for unlimited results or set a specific number to control dataset size and focus your research.
- **Example**: `500` - Collect exactly 500 channels
- **💡 Pro Tip**: Set to 100-200 for quick market research, leave null for comprehensive data
- **No Hidden Fees** - Completely free regardless of limit!

##### **proxyConfiguration** (default: Residential proxies enabled)

- **Type**: Object
- **Description**: Enable Apify's premium residential proxies to bypass rate limits and ensure 99.9% success rate. Highly recommended for large-scale scraping operations.
- **Default**:
  ```json
  {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
  ```
- **💡 Pro Tip**: Always use RESIDENTIAL proxies for best results
- **Premium Proxies at No Extra Cost** - Included free with Apify!

### 📊 Output Data - Rich Channel Insights

**Get everything you need to make data-driven decisions!** Each channel comes with 10+ data points including engagement metrics, growth indicators, and audience insights.

#### Sample Output:

```json
{
  "id": 12345,
  "link": "https://t.me/example_channel",
  "username": "example_channel",
  "title": "Example Channel",
  "about": "Channel description with full details",
  "image": "https://tgstat.com/...",
  "category": "News & Media",
  "language": "Ukrainian",
  "country": "Ukraine",
  "participants_count": 15000,
  "posts_per_day": 5.2,
  "err_percent": 2.1,
  "daily_reach": 8500,
  "ci_index": 45.3
}
```

#### 📋 Field Descriptions:

| Field | Type | Description |
|-------|------|-------------|
| **id** | Integer | Unique TGStat channel identifier |
| **link** | String | Direct Telegram channel URL (t.me/...) |
| **username** | String | Channel username handle |
| **title** | String | Channel display name |
| **about** | String | Full channel description/bio |
| **image** | String | Channel avatar/logo URL |
| **category** | String | TGStat category (News, Entertainment, etc.) |
| **language** | String | Primary channel language |
| **country** | String | Target country/region |
| **participants\_count** | Integer | Total subscriber count |
| **posts\_per\_day** | Float | Average daily posting frequency |
| **err\_percent** | Float | Engagement rate percentage |
| **daily\_reach** | Integer | Average daily unique viewers |
| **ci\_index** | Float | Channel influence index (TGStat metric) |

**💎 All data points included free!** No premium tiers, no paywalls.

### How It Works

#### Half-Division Strategy

The actor uses an intelligent search algorithm:

1. **Initial Range**: Starts with the full subscriber range (min to max)
2. **Search**: Queries TGStat for channels in the current range
3. **Adaptation**:
   - If results > 30: Splits range in half and searches each part
   - If results ≤ 30: Collects all channels and moves to next range
4. **Step Adjustment**:
   - Increases step size if last 5 searches yielded ≤ 11 results
   - Decreases step size if last 3 searches yielded > 29 results

#### Rate Limit Handling

- Detects TGStat's "restricted" status
- Implements exponential backoff (30s → 60s → 120s)
- Rotates proxies between requests

### Memory Settings

**Recommended: 128 MB**

```bash
apify run --memory-mbytes=128
```

### Usage

#### Via Apify Console

1. Open the actor in Apify Console
2. Set `min_subscribers` and `max_subscribers` for your target range
3. Optionally set `limit` to cap the number of results
4. Click Start

#### Via CLI

```bash
## Run locally
apify run --memory-mbytes=128

## Push to Apify
apify push

## Run on Apify platform
apify call <ACTOR_ID> --memory-mbytes=128
```

#### Via API

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_API_TOKEN')

run_input = {
    "min_subscribers": 1000,
    "max_subscribers": 50000,
    "limit": 500
}

run = client.actor('<ACTOR_ID>').call(
    run_input=run_input,
    memory_mbytes=128
)

## Get results
dataset = client.dataset(run["defaultDatasetId"])
items = dataset.list_items().items
```

### Key Features

- ✅ **Smart search** - adaptive algorithm finds channels efficiently
- ✅ **Rate limit resilient** - handles TGStat restrictions gracefully
- ✅ **Real-time results** - data pushed to dataset during execution
- ✅ **Proxy rotation** - avoids IP-based blocking
- ✅ **Low memory** - runs on 128 MB
- ✅ **Comprehensive data** - extracts all available channel metrics

### Limitations

- Scrapes only channels indexed by TGStat
- Subject to TGStat's rate limiting (handled automatically)
- Requires residential proxies for optimal performance
- Search is limited to Ukrainian channels (can be modified)

### Technical Details

- **Language**: Python 3.11
- **Framework**: Apify SDK
- **Strategy**: Half-division binary search
- **Memory**: 128 MB (default)
- **Proxy**: Apify Residential recommended

# Actor input Schema

## `min_subscribers` (type: `integer`):

Set the minimum subscriber count threshold. Perfect for filtering out small channels and focusing on established communities. Start from 100 to discover growing channels or set higher for premium audiences. 100% free to use!

## `max_subscribers` (type: `integer`):

Define the upper limit for subscriber count. Ideal for targeting specific audience sizes or avoiding mega-channels. Set to 100B for unlimited reach. Free unlimited scraping included!

## `limit` (type: `integer`):

Cap the total number of channels to collect. Leave empty for unlimited results or set a specific number to control costs and focus your dataset. No hidden fees - completely free!

## `country` (type: `string`):

Filter channels by country using TGStat country number. Example: '2' for Ukraine, '1' for Russia. Leave empty to search all countries. Free filtering included!

## `language` (type: `string`):

Filter channels by language using TGStat language number. Example: '1' for Ukrainian, '2' for Russian. Leave empty to search all languages. Free filtering included!

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

Enable residential proxies to bypass rate limits and ensure 99.9% success rate. Recommended for large-scale scraping. Uses Apify's premium proxy network at no extra cost!

## Actor input object example

```json
{
  "min_subscribers": 1000,
  "max_subscribers": 50000,
  "limit": 500,
  "country": "2",
  "language": "1",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "min_subscribers": 100,
    "max_subscribers": 100000000000,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("backhoe/tgstat-channel-parser").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 = {
    "min_subscribers": 100,
    "max_subscribers": 100000000000,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("backhoe/tgstat-channel-parser").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 '{
  "min_subscribers": 100,
  "max_subscribers": 100000000000,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call backhoe/tgstat-channel-parser --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=backhoe/tgstat-channel-parser",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "🚀 TGStat Channel Parser",
        "description": "Extract comprehensive Telegram channel statistics from TGStat.com using intelligent AI-powered search...",
        "version": "1.9",
        "x-build-id": "p7tzKbFPOBvCYvpha"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/backhoe~tgstat-channel-parser/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-backhoe-tgstat-channel-parser",
                "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/backhoe~tgstat-channel-parser/runs": {
            "post": {
                "operationId": "runs-sync-backhoe-tgstat-channel-parser",
                "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/backhoe~tgstat-channel-parser/run-sync": {
            "post": {
                "operationId": "run-sync-backhoe-tgstat-channel-parser",
                "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",
                "properties": {
                    "min_subscribers": {
                        "title": "Minimum Subscribers",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Set the minimum subscriber count threshold. Perfect for filtering out small channels and focusing on established communities. Start from 100 to discover growing channels or set higher for premium audiences. 100% free to use!",
                        "default": 100
                    },
                    "max_subscribers": {
                        "title": "Maximum Subscribers",
                        "type": "integer",
                        "description": "Define the upper limit for subscriber count. Ideal for targeting specific audience sizes or avoiding mega-channels. Set to 100B for unlimited reach. Free unlimited scraping included!",
                        "default": 100000000000
                    },
                    "limit": {
                        "title": "Maximum Channels to Scrape",
                        "type": "integer",
                        "description": "Cap the total number of channels to collect. Leave empty for unlimited results or set a specific number to control costs and focus your dataset. No hidden fees - completely free!"
                    },
                    "country": {
                        "title": "Country Filter (Number)",
                        "type": "string",
                        "description": "Filter channels by country using TGStat country number. Example: '2' for Ukraine, '1' for Russia. Leave empty to search all countries. Free filtering included!"
                    },
                    "language": {
                        "title": "Language Filter (Number)",
                        "type": "string",
                        "description": "Filter channels by language using TGStat language number. Example: '1' for Ukrainian, '2' for Russian. Leave empty to search all languages. Free filtering included!"
                    },
                    "proxyConfiguration": {
                        "title": "Proxy Configuration",
                        "type": "object",
                        "description": "Enable residential proxies to bypass rate limits and ensure 99.9% success rate. Recommended for large-scale scraping. Uses Apify's premium proxy network at no extra cost!",
                        "default": {
                            "useApifyProxy": true,
                            "apifyProxyGroups": [
                                "RESIDENTIAL"
                            ]
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```