# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/tgstat/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/tgstat/get-channel-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/tgstat/get-ratings-channels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/tgstat/get-ratings-groups \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/tgstat/search-channels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","country":"<integer>","page":"<integer>","query":"<string>","sort":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.