Channel profile
1 credit/v1/telegram/profileName, description, avatar, verified badge, and an exact subscriber count. Groups return a member count on the same field. A channel with no public preview returns 404 and is not charged.
handle
Telegram APIScrape public Telegram data with one API
Fetch public Telegram channel data as structured JSON with one SocialCrawl API key. Same Post and Author schema as every other platform. Reads are priced in credits.
/v1/telegram
3 active endpoints
- GET /v1/telegram/profile
- GET /v1/telegram/profile/posts
- GET /v1/telegram/post
What Telegram endpoints does SocialCrawl ship?
3 live read endpoints for public Telegram channels and groups. Channel profile, paginated post history, and a single post by URL.
Channel posts
1 credit/v1/telegram/profile/postsOne page of public posts with text, publish time, views, the per emoji reaction breakdown, and direct photo and video URLs. Pass the cursor to walk further back. Page size varies, so keep paging until the cursor is absent.
handle, cursor
Single post
1 credit/v1/telegram/postOne post from its t.me link, with the same fields as a list row. Every image in an album is returned, not just the first. View and reaction counts are rounded by the public Telegram surface.
url
Telegram API4 endpoints supported
View docsProfiles
Returns a public Telegram channel or group profile: display name, description, avatar URL, verified badge, and an exact subscriber count.
Use it when you have a handle and want the channel snapshot, or to confirm a channel is public before paging its posts.
1 credit
GET/v1/telegram/profile?handle=telegram
handle · Public Telegram handle, with or without the leading @, or a t.me channel URL
$ curl https://www.socialcrawl.dev/v1/telegram/profile?handle=telegram \
-H "x-api-key: sc_YOUR_API_KEY"idle
// Running this live needs your own API key. Hit "Try it" to see an example responseHow does the SocialCrawl Telegram API work?
Telegram is a normal SocialCrawl social surface. You call GET /v1/telegram/… with an API key, spend credits on live misses, and get a single JSON envelope back. No bot token, no phone number, no MTProto session.
Authenticate every call
Send your key in the x-api-key header. The same key works across the SocialCrawl catalog.
GET with query params
Routes are GET. Pass the handle, the post URL, and the cursor as query strings. Formats are validated before charging, so a private invite link is rejected without a credit.
Pay in credits, not seats
Every Telegram route is 1 credit on a live miss. Cache hits cost 0. Not found and invalid input are never charged.
Read one JSON envelope
Every response is the same shape: success, data, credits_used, credits_remaining, request_id, cached.
The usual integration chain
Most products resolve the channel, page its history, then deepen only the posts that matter.
01Channel
GET /v1/telegram/profileAuthor-shaped profile with an exact subscriber count
Resolve the handle once and confirm the channel is public.
02History
GET /v1/telegram/profile/postsPostList of recent public posts
Page with the cursor until it comes back absent.
03Backfill
GET /v1/telegram/profile/postsOlder pages from the same cursor
A short page is not the end of the channel. Keep going.
04Post
GET /v1/telegram/postFull Post for one t.me link
Use it when you already hold a link and do not need the feed.
request
GET /v1/telegram/profile
?handle=telegram
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_hereresponse envelope
{
"success": true,
"data": { "/* Author | Post | PostList */": true },
"credits_used": 1,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}What lands in data
Field names match the rest of SocialCrawl where archetypes align.
Authorprofile
id, username, display_name, avatar_url, bio, followers, verified, url
PostListprofile/posts
items[].post with id, url, content, engagement, author, published_at, ext
Postpost
id, url, content.text, content.media_urls, engagement.views, published_at
Reactionsprofile/posts
post.ext.reaction_counts with the emoji and the count for each reaction
Inside the gateway
Same request lifecycle as every other /v1 platform endpoint.
- 01
Edge receives the call
Next.js catch-all routes into the Hono social API. We mint a request_id, authenticate the key, then enforce rate limit and concurrency.
- 02
Validate, then debit
Registry lookup finds the route. Handle and URL formats run first, so a malformed handle or an invite link returns 400 with no charge.
- 03
Cache or fetch
A deterministic cache key is built from platform, resource, and params. Hit: credits_used is 0. Miss: upstream fetch with retries and circuit breaker.
- 04
Normalize and return
Upstream JSON is mapped to Author, Post, and PostList, validated, wrapped in the success envelope, and logged for billing audit.
Billing rules that matter in production
- Channel profile: 1 credit
- Channel posts: 1 credit per page
- Single post: 1 credit
- Cache hit: 0 credits
- Channel not found: 404, never charged
- Bad handle or non-Telegram URL: 400, never charged
- Private or invite-only link: 400, rejected before the upstream call
- No credits: 402, never charged
- Disabled routes: 503, never charged
How does SocialCrawl get Telegram data?
Telegram is public-read data on SocialCrawl. We normalize the public channel surface into the shared schema so your code does not learn the Bot API or MTProto.
What Telegram is for this API
Public channels and groups that publish a public preview. Read-only for research, monitoring, and product jobs.
How SocialCrawl reaches it
A social-read upstream behind one gateway. No bot has to be an administrator of the channel you are reading.
What leaves our edge
Unified JSON envelope: success, data, credits_used, request_id, cached. Media arrives as direct URLs you can fetch or embed.
What we do not ship live
No write endpoints, no private channels, no direct messages, and no member lists. Post comments live in a separate discussion group and are not exposed.
field map sketch
public channel profile→ author.*channel identity, subscriber count, and avatar
public channel post→ post.* / items[].postpost text, views, media, and publish time
per emoji reaction counts→ post.ext.reaction_countsper emoji reaction counts
What is the Telegram API used for?
The jobs this API is most often used for.
3active Telegram endpoints in the registry
1 / 1 / 1credits for profile, posts, and single post
Telegram channel monitoring and content archiving
Callers concentrate on channel post history, then deepen single posts they already hold links to. Full channel history behind a resumable cursor, with playable media URLs and no bot token, at 1 credit a page.
Channel reads are typically a few seconds on a live miss. Cache hits return immediately.
Use case examples
Common ways teams put this data to work, and the stack each one tends to run.
Channel monitoring
Python, cron, Slack botsPoll a channel's latest page and alert when a post lands or when views climb fast.
Research and archiving
Node, notebooks, BI loadsWalk a channel's full history once with the cursor, then keep it current from page one.
Backend product jobs
Go, workers, ExplorerResolve a channel, page its posts, and pull media URLs straight into your own pipeline.
How do I call the Telegram API?
Live misses spend 1 credit. Cache hits are free. Not found and invalid input are never charged.
curl "https://www.socialcrawl.dev/v1/telegram/profile?handle=telegram" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/telegram/profile/posts?handle=telegram" \
-H "x-api-key: sc_your_api_key_here"Same key as the rest of the catalog
Endpoints
What data does the Telegram API return?
Every endpoint returns structured JSON in a unified envelope. Computed fields such as engagement rate and content category are included only where the endpoint supports them and the required source inputs are present.
Comparison
How does SocialCrawl compare to Official Telegram API for Telegram data?
Same Telegram data, two very different paths. Auth, rate limits, schema, and cost, side by side.
| Feature | SocialCrawl | Official Telegram API |
|---|---|---|
| Read any public channel | Yes, by handle or t.me URL | Bot API reads only channels your bot administers |
| Credentials needed | One x-api-key | Bot token, or an account on a real phone number for MTProto |
| Post history | Cursor pagination through the whole public archive | Bot API cannot read history it did not receive live |
| Media | Playable CDN URLs on every photo and video | File ids that need a second authenticated download call |
| Response shape | Same canonical JSON as every other platform | Raw MTProto objects with protocol flags and int64 ids |
| Rate limits | Standard account limits, no per-channel throttle | Per-bot and per-chat flood limits enforced by Telegram |
Read any public channel
SocialCrawl
Yes, by handle or t.me URL
Official Telegram API
Bot API reads only channels your bot administers
Credentials needed
SocialCrawl
One x-api-key
Official Telegram API
Bot token, or an account on a real phone number for MTProto
Post history
SocialCrawl
Cursor pagination through the whole public archive
Official Telegram API
Bot API cannot read history it did not receive live
Media
SocialCrawl
Playable CDN URLs on every photo and video
Official Telegram API
File ids that need a second authenticated download call
Response shape
SocialCrawl
Same canonical JSON as every other platform
Official Telegram API
Raw MTProto objects with protocol flags and int64 ids
Rate limits
SocialCrawl
Standard account limits, no per-channel throttle
Official Telegram API
Per-bot and per-chat flood limits enforced by Telegram
FAQ
Have a question? We got answers
Find answers to frequently asked questions about SocialCrawl's API, pricing, and capabilities.
Contact usHow do I scrape Telegram channel data with an API?
SocialCrawl exposes 4 Telegram endpoints: channel profile, channel post history, and a single post by URL. Send a GET request with your x-api-key and a channel handle or t.me URL, and you get normalized JSON back. There is no bot token to create, no phone number to register, and no MTProto session to keep alive.
Do I need a Telegram bot token or a phone number?
No. The official Bot API only reads channels your bot administers, and MTProto requires an account registered to a real phone number. SocialCrawl reads the public channel surface directly, so you can pull any public channel you have the handle for without holding credentials of your own.
Which Telegram channels can I read?
Public channels and groups that expose a public preview page. Private channels, invite-only groups, and channels whose owner has disabled the public preview are not readable and return a clear not-found response rather than an empty result you would have to guess about.
Are Telegram view and reaction counts exact?
Subscriber counts on the channel profile are exact. View and reaction counts on individual posts are rounded to three significant figures by Telegram's own public surface, so a post showing 931,193 views reads as 931,000. Use them for ranking and comparison rather than for hour-by-hour delta tracking.
How do I page through a channel's whole history?
Pass the cursor from each response back on the next call until it comes back absent. Page size varies because photo albums count as one post and service messages are skipped, so a short page is not the end of the channel. A full walk of a 546-message channel returned 426 posts across 24 pages with no duplicate rows.
What does the Telegram API cost?
All 4 Telegram endpoints cost 1 credit per call. Cached responses and not-found lookups are free, and new accounts start with 100 credits, so you can test the whole surface before paying anything.
Is scraping Telegram data legal?
SocialCrawl returns publicly available Telegram data and does not access private or login-gated content. Whether scraping fits your project depends on your use case and jurisdiction. You are responsible for complying with Telegram's terms of service and applicable data-protection laws such as GDPR and CCPA. This is general information, not legal advice.
Telegram scraping API vs the official Telegram API: what's the difference?
With SocialCrawl there is no app review or approval queue. Sign up and call Telegram endpoints immediately with a single x-api-key. Responses share one unified schema with every other SocialCrawl platform, and credit-based pricing replaces per-platform quotas. Official APIs are still the right choice for posting and other write actions: SocialCrawl is read-only data.
Ask AI about SocialCrawl