API డాక్యుమెంటేషన్
Telegram ఛానెల్లను వెతకడానికి, Export చేయడానికి REST API v1. JSON, cursor పేజినేషన్, UI మరియు Exportలలో ఉన్న అదే ఫిల్టర్ స్కీమా. మెషీన్ చదవగలిగే స్కీమా బ్యాకెండ్ OpenAPI (/openapi.json).
బేస్ URL: https://tgmarket.io/api. కింద ఉన్న అన్ని పాత్లు దీనికి సంబంధించినవి.
MCP ద్వారా AI అసిస్టెంట్లను కనెక్ట్ చేయండి →
ఆథెంటికేషన్
కీని ఇక్కడ సృష్టించండి: డ్యాష్బోర్డ్ → API keys (చెల్లింపు ప్లాన్లు). కీ ఫార్మాట్: mk_live_<prefix>_<secret>, ఇది ఒక్కసారి మాత్రమే చూపబడుతుంది. దీన్ని హెడర్లో పంపండి:
Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# లేదా
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxxScopes: read (డిఫాల్ట్) మరియు export — POST /v1/exports, POST/PATCH/DELETE /v1/webhooks కోసం. గరిష్టంగా రెండు యాక్టివ్ కీలు, కాబట్టి డౌన్టైమ్ లేకుండా కీలను మార్చవచ్చు.
బిల్లింగ్
మీరు కాల్స్కు కాదు, తిరిగి వచ్చిన డేటాకు చెల్లిస్తారు. అన్నీ క్రెడిట్లలో ఛార్జ్ అవుతాయి: 1 క్రెడిట్ = $0.001.
- ప్రతి పెయిడ్ రిక్వెస్ట్ — 1 క్రెడిట్ (1,000 రిక్వెస్ట్లకు $1).
- ప్రతి ఛానెల్ రో — ఫీల్డ్ సెట్ రేటు ప్రకారం: Base 0.5 క్రెడిట్లు, +Metrics 1.5, +Ads 2, History 3.
- ప్రతి పోస్ట్ — 0.5 క్రెడిట్లు.
- ఈ కీ గత 30 రోజుల్లో ఇప్పటికే చెల్లించిన ఛానెల్ ఉచితంగా వస్తుంది.
- /count మరియు facets — రిక్వెస్ట్ ఫీజు మాత్రమే.
ఛార్జ్ అయిన మొత్తం X-Credits-Charged హెడర్లో వస్తుంది. బ్యాలెన్స్, వినియోగం — GET /v1/usage. Export ధరల కోసం చూడండి: ప్రైసింగ్.
ఎండ్పాయింట్లు
| మెథడ్ | పాత్ | వివరణ | ఖర్చు |
|---|---|---|---|
| GET | /v1/categories | కేటగిరీ ట్రీ | ఉచితం |
| GET | /v1/languages | ఛానెల్ కౌంట్లతో భాషలు | ఉచితం |
| GET | /v1/geo | ఛానెల్ సంఖ్యతో దేశాలు; ?country= — ఆ దేశ ప్రాంతాలు (regions ఫిల్టర్ కోసం కోడ్లు) | ఉచితం |
| GET | /v1/usage | బ్యాలెన్స్, రోజువారీ వినియోగం, లిమిట్లు | ఉచితం |
| POST | /v1/channels/search | ఫిల్టర్లు + q, cursor, ఒక్కో పేజీకి గరిష్టంగా 100 | రిక్వెస్ట్ + రోలు |
| POST | /v1/channels/count | కౌంట్లు మరియు facets | రిక్వెస్ట్ |
| GET | /v1/channels/{id|username} | ఛానెల్ కార్డ్ (?fields=base,metrics,ads; reach — రోజువారీ రీచ్) | రిక్వెస్ట్ + రో |
| GET | /v1/channels/{id}/history | రోజువారీ సబ్స్క్రైబర్లు, మెట్రిక్స్ & రోజువారీ రీచ్ (?days=) | రిక్వెస్ట్ + History |
| GET | /v1/channels/{id}/posts | ఇటీవలి పోస్ట్లు (?limit= గరిష్టంగా 100) | రిక్వెస్ట్ + పోస్ట్లు |
| GET | /v1/channels/{id}/references | సైట్ చేసినవి / సైట్ చేస్తున్నవి | రిక్వెస్ట్ + రోలు |
| GET | /v1/advertisers | 30 రోజుల్లో ఛానెళ్ల సంఖ్య ప్రకారం ప్రకటనదారులు (group, lang, country, q) | రిక్వెస్ట్ |
| GET | /v1/advertisers/{key} | ప్రకటనదారు మరియు దాని ఛానెళ్లు (limit, offset) | రిక్వెస్ట్ + రోలు |
| POST | /v1/posts/search | పోస్ట్లలో ఫుల్-టెక్స్ట్ సెర్చ్ | రిక్వెస్ట్ + పోస్ట్లు |
| POST | /v1/posts/trend | పదం ప్రస్తావనల ధోరణి: రోజుకు పోస్ట్లు, ఛానెల్లు, వీక్షణలు (group=day|week) | రిక్వెస్ట్ + ప్రతి పాయింట్కు 0.01 |
| POST | /v1/exports | అసింక్ Export (export scope) | Export ధర |
| POST | /v1/exports/quote | ఆర్డర్కు ముందు ఎగుమతి ధర: వరుసలు, ఉచిత వరుసలు, తగ్గింపులు | రిక్వెస్ట్ |
| GET | /v1/exports/{id} | స్టేటస్ మరియు డౌన్లోడ్ లింక్ | ఉచితం |
| GET | /v1/feeds | Enterprise: రోజువారీ ఫీడ్ రోజులు (కొత్త, మారిన, తొలగించిన ఛానెల్లు, Parquet) | ఉచితం |
| GET | /v1/feeds/{date} | Enterprise: రోజు ఫైల్కు సంతకం చేసిన లింక్ (export scope) | రోజు వరుసలు ఒప్పంద రేటుకు, ఒక్కసారి |
ఫిల్టర్లు (ChannelQuery)
query ఆబ్జెక్ట్ /channels/search, /channels/count మరియు /exports కోసం ఒకటే. ఖాళీ ఫీల్డ్లను వదిలేయండి.
| q | string | టెక్స్ట్: టైటిల్, username, వివరణ, పోస్ట్లు |
| category_ids / exclude_category_ids | int[] | కేటగిరీలు (విభాగాలు లేదా సబ్కేటగిరీలు) |
| channel_ids | int[] | నిర్దిష్ట ఛానెల్లు |
| languages / exclude_languages | string[] | భాష కోడ్లు: ru, en, uk… |
| countries / regions / exclude_countries | string[] | భౌగోళికం: ISO దేశ కోడ్లు (IN, US) మరియు /v1/geo నుండి ప్రాంతాలు "US:Texas"; ప్రాంతం తన దేశాన్నే పరిమితం చేస్తుంది |
| kind | all | channel | group | రకం |
| subscribers_min / subscribers_max | int | సబ్స్క్రైబర్లు |
| avg_views_min, reach_24h_min | number | వ్యూస్ మరియు 24 గం. రీచ్ |
| er_min, err_24h_min | number | ER / ERR, % |
| growth_7d_min, growth_30d_min, growth_pct_30d_min | number | గ్రోత్ |
| posts_30d_min, last_post_after | int, date | యాక్టివిటీ |
| chat_mau_min | int | యాక్టివ్ కామెంటర్లు: డిస్కషన్ చాట్లో యూనిక్ రచయితలు, 30 రోజులు |
| daily_reach_min | int | రోజువారీ రీచ్ (అంచనా): రోజు పోస్ట్ల 24 గంటల వీక్షణల మొత్తం; 30 రోజుల సగటు |
| reach_48h_min | int | 48 గంటల పోస్ట్ రీచ్: ప్రచురించిన 48 గంటల తర్వాత పోస్ట్ సగటు వీక్షణలు, 30 రోజుల్లో |
| premium_share_min | 0..100 | చర్చ రచయితల్లో Telegram Premium వాటా, %, అంచనా (50+ రచయితలు) |
| female_share_min | 0..100 | గుర్తించిన పేరు ఉన్న రచయితల్లో మహిళల వాటా, %, అంచనా — కనీసం |
| female_share_max | 0..100 | అదే — గరిష్టం |
| created_after / created_before | date | సృష్టించిన తేదీ |
| has_ads_contact, ad_share_max | bool, 0..1 | యాడ్స్ |
| fraud_max | 0..1 | ఫ్రాడ్ స్కోర్ పరిమితి |
| verified_only, exclude_scam | bool | ఫ్లాగ్లు (డిఫాల్ట్గా exclude_scam=true) |
| sort, order | string | సార్ట్ ఫీల్డ్; order — desc|asc relevance, subscribers, growth_7d, growth_30d, growth_pct_30d, reach_24h, avg_views, er, citation_index, created_at, last_post_at, chat_mau, daily_reach, reach_48h, premium_share |
ఉదాహరణలు
ఛానెల్లను వెతకండి
curl -X POST https://tgmarket.io/api/v1/channels/search \
-H "Authorization: Bearer $MK_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": {"q": "స్టాక్ మార్కెట్", "languages": ["te"], "subscribers_min": 5000, "sort": "growth_30d"},
"fields": ["base", "metrics"],
"limit": 100
}'రెస్పాన్స్:
{
"items": [{"id": 2365318039, "username": "GPTronhub", "title": "…", "subscribers": 169432, "er": 0.16, …}],
"total": 605,
"next_cursor": "eyJoIjoi…" // తదుపరి రిక్వెస్ట్లో cursor గా పంపండి
}కౌంట్ మాత్రమే
curl -X POST https://tgmarket.io/api/v1/channels/count -H "Authorization: Bearer $MK_KEY" \
-H "Content-Type: application/json" -d '{"query": {"category_ids": [21]}}'కార్డ్ మరియు హిస్టరీ
curl "https://tgmarket.io/api/v1/channels/durov?fields=base,metrics" -H "Authorization: Bearer $MK_KEY"
curl "https://tgmarket.io/api/v1/channels/1006503122/history?days=90" -H "Authorization: Bearer $MK_KEY"Export
curl -X POST https://tgmarket.io/api/v1/exports -H "Authorization: Bearer $MK_KEY" -H "Content-Type: application/json" \
-d '{"query": {"q": "క్రిప్టో"}, "fields": ["base","metrics"], "format": "csv", "row_limit": 20000}'
# → {"export_id": "…", "rows": 20000, "price_credits": 32000, "status": "queued"}
curl https://tgmarket.io/api/v1/exports/<export_id> -H "Authorization: Bearer $MK_KEY"
# → {"status": "done", "progress": 100, "download_url": "https://…", …}రేట్ లిమిట్లు
- Premium — సెకనుకు 1 రిక్వెస్ట్, Business — 3, Super — 10, Enterprise — ఒప్పందం ప్రకారం.
- ప్రతి రెస్పాన్స్లో ఈ హెడర్లు ఉంటాయి:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset. - ఒక query కి 10,000 ఫలితాలు దాటితే — /v1/exports ఉపయోగించండి.
- ఒక్కో కీకి యూనిక్ ఛానెల్లపై కఠినమైన రోజువారీ పరిమితి ఉంది; అది దాటితే మాన్యువల్ రివ్యూ వరకు కీ ఫ్రీజ్ అవుతుంది.
ఎర్రర్లు
అన్ని ఎర్రర్లకు ఒకే ఫార్మాట్ ఉంటుంది:
{"error": {"code": "payment_required", "message": "…"}}401 invalid_api_key— చెల్లని లేదా రద్దు చేసిన కీ402 payment_required/402 insufficient_funds— బ్యాలెన్స్ అయిపోయింది, డ్యాష్బోర్డ్లో టాప్ అప్ చేయండి (బాడీలో need/have)403 api_not_in_plan,403 scope_required,403 key_frozen,403 ip_not_allowed429 rate_limited— RPS మించిపోయింది; ఈ హెడర్లో ఉన్నన్ని సెకన్లు వేచి ఉండండి:Retry-After400 too_deep,400 bad_cursor,422— చెల్లని పారామీటర్లు
Webhooks
మీరు గమనిస్తున్న ఛానెల్ల కొత్త పోస్ట్లు నేరుగా మీ సర్వర్కు: ప్రతి పోస్ట్కు JSON bodyతో ఒక HTTP POST, కావాలంటే keyword ఫిల్టర్తో.
ఆలస్యం గురించి నిజాయితీగా: మా crawler ప్రతి ఛానెల్ను 3–14 రోజులకు ఒకసారి చూస్తుంది, కాబట్టి పోస్ట్లు బ్యాచ్లుగా, తరచుగా ప్రచురణ తర్వాత కొన్ని రోజులకు వస్తాయి. మాకు చేరిన తర్వాత పోస్ట్ సుమారు ఒక నిమిషంలో పంపబడుతుంది; eventలో అసలు తేదీ, delay_seconds ఉంటాయి. ఇది real-time feed కాదు.
Endpointను సృష్టించండి డాష్బోర్డ్ → Webhooksలో లేదా కింది APIతో, ఆపై subscriptions జోడించండి: ఛానెల్ల జాబితా (id లేదా @username), ఐచ్ఛిక keywords — వాటిలో ఏదైనా ఉంటే పోస్ట్ పంపబడుతుంది (case-insensitive).
- 2xx స్పందనతో పంపిన ప్రతి పోస్ట్కు 0.5 క్రెడిట్, key (లేదా సంస్థ) బ్యాలెన్స్ నుంచి తీసివేయబడుతుంది. నిర్వహణ, టెస్ట్ ping, విఫల ప్రయత్నాలు ఉచితం. బ్యాలెన్స్ సున్నా అయితే deliveries పోవు, 72 గంటల వరకు వేచి ఉంటాయి.
- అన్ని subscriptionsలో గమనిస్తున్న ఛానెల్లు: Premium — 100, Business — 300, Super — 1,000. గరిష్ఠంగా 5 endpoints, ఒక్కోదానికి 50 subscriptions.
| GET | /v1/webhooks | Subscriptionsతో endpoints; ప్లాన్ పరిమితి, 30 రోజుల వినియోగం |
| POST | /v1/webhooks | Endpoint సృష్టించండి {name, url}; signing secret ఒక్కసారే తిరిగి వస్తుంది |
| GET · PATCH · DELETE | /v1/webhooks/{id} | Endpoint చూడండి, మార్చండి {name, url, active} లేదా తొలగించండి |
| POST | /v1/webhooks/{id}/rotate-secret | కొత్త signing secret (పాతది వెంటనే చెల్లదు) |
| POST | /v1/webhooks/{id}/test | ఇప్పుడే ping event పంపండి (ఉచితం) |
| POST | /v1/webhooks/{id}/subscriptions | Subscription జోడించండి {channels, keywords?, name?} |
| PATCH · DELETE | /v1/webhooks/{id}/subscriptions/{sub_id} | Subscription మార్చండి లేదా తొలగించండి |
| GET | /v1/webhooks/{id}/deliveries[/{delivery_id}] | Delivery log, కొత్తవి ముందు (?status=, ?before_id=) |
| POST | /v1/webhooks/{id}/deliveries/{delivery_id}/retry | విఫలమైన లేదా గడువు ముగిసిన deliveryని మళ్లీ క్యూలో పెట్టండి |
curl -X POST https://tgmarket.io/api/v1/webhooks -H "Authorization: Bearer $MK_KEY" -H "Content-Type: application/json" \
-d '{"name": "crm", "url": "https://example.com/hooks/tgmarket"}'
# → {"id": "…", "secret": "whsec_…", …}
curl -X POST https://tgmarket.io/api/v1/webhooks/<id>/subscriptions -H "Authorization: Bearer $MK_KEY" \
-H "Content-Type: application/json" -d '{"channels": ["@durov", 1006503122], "keywords": ["bitcoin"]}'Event body
{
"id": "evt_3f2a…", // = X-TGMarket-Idempotency-Key
"type": "post.created",
"created_at": "2026-10-05T12:00:41+00:00",
"endpoint_id": "…",
"subscription_ids": ["…"],
"matched_keywords": ["bitcoin"],
"channel": {"id": 1006503122, "username": "durov", "title": "Durov's Channel"},
"post": {
"id": 98765432, "message_id": 321, "date": "2026-09-30T08:15:00+00:00",
"url": "https://t.me/durov/321", "text": "…", "views": 1200000, "forwards": 3100,
"replies": 0, "reactions": 45000, "has_media": true, "media_type": "photo",
"forward_from_channel_id": null, "reply_to_message_id": null, "mentioned_usernames": []
},
"collected_at": "2026-10-05T12:00:20+00:00",
"delay_seconds": 445520
}Signature
ప్రతి requestలో headers: X-TGMarket-Event (post.created లేదా ping), X-TGMarket-Delivery, X-TGMarket-Idempotency-Key, X-TGMarket-Timestamp మరియు X-TGMarket-Signature: v1=<hex>, ఇక్కడ hex = HMAC-SHA256(secret, timestamp + "." + raw body). Timestamp 5 నిమిషాల కంటే ఎక్కువ తేడా ఉన్న requestsను తిరస్కరించండి.
Signature తనిఖీ (Python)
import hashlib, hmac, time
def verify(secret: str, headers, raw_body: bytes) -> bool:
ts = int(headers["X-TGMarket-Timestamp"])
if abs(time.time() - ts) > 300:
return False
mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(f"v1={mac}", headers["X-TGMarket-Signature"])- మళ్లీ ప్రయత్నాలు: ఏ non-2xx స్పందన, timeout (10 s) లేదా connection లోపం అయినా exponential backoffతో మళ్లీ ప్రయత్నించబడుతుంది — 1, 2, 4… నిమిషాలు, గరిష్ఠంగా 6 గంటల వ్యవధి, 10 ప్రయత్నాలు. Redirects అనుసరించబడవు. వైఫల్యాలు 24 గంటలు కొనసాగితే (కనీసం వరుసగా 20) endpoint ఆపివేయబడుతుంది, ownerకు ఇమెయిల్ వస్తుంది; PATCH active=trueతో ప్రారంభించండి, పెండింగ్ deliveries కొనసాగుతాయి.
- X-TGMarket-Idempotency-Key (= event id) ద్వారా నకిలీలను తొలగించండి: ఒక endpointకు ఒక పోస్ట్ యొక్క అన్ని ప్రయత్నాల్లో ఇది ఒకటే, ఒక పోస్ట్ ఒకే endpointకు రెండుసార్లు క్యూలోకి రాదు.
- URL నిబంధనలు: https మాత్రమే, పబ్లిక్ domain లేదా IP; private, loopback, link-local చిరునామాలు (పంపేటప్పుడు DNS ఇచ్చేవి కూడా) తిరస్కరించబడతాయి; URLలో login/password వద్దు. త్వరగా 2xx ఇచ్చి asyncగా ప్రాసెస్ చేయండి.