# Telegram Search API (https://www.socialcrawl.dev/platforms/telegram/search)

> Finds public Telegram channels by keyword, so you can pick the channels to read with `/v1/telegram/profile` and `/v1/telegram/profile/posts`. Channels are discovered through a public web search index limited to t.me pages, so this finds what that index has already seen: it is not real time, a channel or message from the last few days may not appear yet, and private channels and invite-only groups never appear. Returns one row per channel, in the order the search found them, on the same Author shape `/v1/telegram/profile` returns: `author.username` is the public handle (pass it as `handle`), `author.url` is `https://t.me/<handle>`, and `author.display_name` is the channel's title when the search result carried it (null when the result showed only the handle). `author.ext.search_hit` says how the channel was found: `match` is `channel_page` (the channel's own page) or `post_in_channel` (a message or the message preview), `title` and `snippet` are the hit as the index showed it, `evidence_url` is the first page that matched, and `matched_urls` lists every t.me page the search matched for that channel, so you can open the exact messages. The snippet is the index's text, not the channel's description, so `author.bio` stays null on a plain call, as do `author.followers`, `author.avatar_url` and `author.verified`. Send `include=details` and every channel is joined, in the same call, to the profile lookup: the exact subscriber count (`author.followers`), the description (`author.bio`), the avatar, the verified flag and, where it was null, the title land on each row. Words in `query` match loosely; put a phrase in double quotes to require it, and add `-word` to exclude a word. Cost: 2 credits for the page, plus 1 credit per channel filled from a fresh lookup with `include=details` (at most 10 a page, so 12 credits at most); channels already in cache are free, channels that could not be filled are refunded, and a search that finds no public channel is a 404 at 0 credits. Time: a plain page takes about 2 to 12 seconds; `include=details` adds a few seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 10 seconds) and nothing when the channels are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. A page holds up to 10 channels, fewer when several hits belong to one channel. Forward `pagination.next_cursor` as `cursor` for the next page; the same channel can appear again on a later page.

TL;DR: `GET /v1/telegram/search` costs 2 credits for the page. include=details holds 1 credit per channel (at most 10 a page, fewer with limit) and keeps only the channels filled from a fresh lookup, so a page is at most 12 credits; channels served from cache are free, unfilled channels are refunded, and a search that finds no public channel costs 0. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Keywords describing the channels or messages to find, for example `byd spare parts`. Put a phrase in double quotes to require it. Keywords only: the search is already limited to public Telegram pages, so a `site:` operator is refused before billing. |
| `page` | no | Page number, starting at 1. Forwarding `pagination.next_cursor` as `cursor` does the same. |
| `date_posted` | no | Only pages the search index dates within this window: last-hour, last-day, last-week, last-month or last-year. Useful for monitoring new activity. (last-hour \| last-day \| last-week \| last-month \| last-year) |
| `region` | no | Two-letter country code (US, AE, IN, KR) whose results to prefer. |
| `limit` | no | Return at most this many channels from the page (1 to 10). With `include=details` it also lowers the credits held, one per channel. |
| `include` | no | Set to `details` (one token only) to fill, on every channel in this one call, `author.followers` (the exact subscriber count), `author.bio` (the description), `author.avatar_url`, `author.verified`, and the title where it was null. Holds 1 credit per channel (at most 10 a page) and keeps only the channels filled from a fresh lookup; channels already in cache and channels the lookup cannot fill are refunded, so a page is never more than 12 credits. Read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. (details) |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/telegram/search" \
  --data-urlencode "query=byd spare parts" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

See the full Telegram API: https://www.socialcrawl.dev/platforms/telegram

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing