# TGStat — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and discover Telegram channels and groups by keyword or category, view detailed channel ratings and performance metrics, and access comprehensive profile information including subscriber counts and engagement data. Monitor top-performing channels and groups to find the most popular content across categories and regions.

**Category:** Social Media | **Website:** [in.tgstat.com/](https://in.tgstat.com/) | **Docs:** [parse.bot/marketplace/e54381ef-3f16-4d1c-b043-380d5f2548d8/tgstat-api](https://parse.bot/marketplace/e54381ef-3f16-4d1c-b043-380d5f2548d8/tgstat-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-tgstat-api-e54381ef/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_channel_profile

Detailed public profile for a single Telegram channel. Returns the display title, description, subscriber metrics, category, geo/language information, and the TGStat profile URL. The metrics and info fields are open dictionaries whose keys depend on the channel's available data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Telegram handle (with or without @ prefix, e.g. 'durov' or '@durov') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tgstat-api-e54381ef/get_channel_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"<string>"}'
```

### get_ratings_channels

Ranked list of top Telegram channels by subscribers or reach. Supports category filtering. Returns a single page of channel summaries ordered by the chosen sort metric. Categories are path-based slugs matching TGStat's taxonomy.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category name to filter by (e.g. education, news, blogs, cryptocurrencies) |
| `sort` | string | No | Sort order. Known working values: members, reach |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tgstat-api-e54381ef/get_ratings_channels \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","sort":"<string>"}'
```

### get_ratings_groups

Ranked list of top Telegram groups (chats) by member count. Supports category filtering. Returns a single page of group summaries. Groups differ from channels in that they support two-way communication among members.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category name to filter by (e.g. education, news) |
| `sort` | string | No | Sort order. Known working value: members |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tgstat-api-e54381ef/get_ratings_groups \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","sort":"<string>"}'
```

### search_channels

Full-text search over Telegram channels with filters for country, category, and sort order. Returns a paginated list of channel summaries. Pagination advances via the integer page counter returned in nextPage. Each result includes the channel name, handle, and subscriber count but not full profile details — use get_channel_profile for those.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category name to filter by (e.g. education, cryptocurrencies, news) |
| `country` | integer | No | Country ID to filter results by (e.g. 8 for India, 1 for Russia). Omit to search globally. |
| `page` | integer | No | Pagination page number (zero-based), use nextPage from previous response to get next page of results |
| `query` | string | No | Keyword to search for in channel name or description |
| `sort` | string | No | Sort order for results |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tgstat-api-e54381ef/search_channels \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","country":"<integer>","page":"<integer>","query":"<string>","sort":"<string>"}'
```