API डॉक्यूमेंटेशन

Telegram चैनलों को खोजने और Export करने के लिए REST API v1। JSON, cursor पेजिनेशन, और वही फ़िल्टर स्कीमा जो UI और Export में है। मशीन-रीडेबल स्कीमा बैकएंड का OpenAPI (/openapi.json) है।

बेस URL: https://tgmarket.io/api. नीचे दिए गए सभी पाथ इसी के सापेक्ष हैं।

MCP से AI असिस्टेंट जोड़ें →

ऑथेंटिकेशन

API key यहाँ बनाएँ: डैशबोर्ड → API keys (पेड प्लान)। Key का फ़ॉर्मेट: mk_live_<prefix>_<secret>, यह सिर्फ़ एक बार दिखाई जाती है। इसे हेडर में भेजें:

Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# या
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxx

Scopes: read (डिफ़ॉल्ट) और export — POST /v1/exports, POST/PATCH/DELETE /v1/webhooks के लिए। अधिकतम दो सक्रिय keys, ताकि आप बिना डाउनटाइम के key बदल सकें।

बिलिंग

आप लौटाए गए डेटा के लिए भुगतान करते हैं, कॉल के लिए नहीं। सब कुछ क्रेडिट में चार्ज होता है: 1 क्रेडिट = $0.001।

  • हर पेड रिक्वेस्ट — 1 क्रेडिट ($1 प्रति 1,000 रिक्वेस्ट)।
  • हर चैनल रो — फ़ील्ड-सेट की दर से: Base 0.5 क्रेडिट, +Metrics 1.5, +Ads 2, History 3।
  • हर पोस्ट — 0.5 क्रेडिट।
  • जिस चैनल के लिए इस key से 30 दिनों के भीतर भुगतान हो चुका है, वह मुफ़्त लौटाया जाता है।
  • /count और facets — सिर्फ़ रिक्वेस्ट शुल्क।

कितना चार्ज हुआ, यह X-Credits-Charged हेडर में लौटाया जाता है। बैलेंस और उपयोग — GET /v1/usage। Export की कीमतें — देखें प्लान और कीमतें.

Endpoints

मेथडपाथविवरणकीमत
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/advertisers30 दिनों में चैनलों की संख्या के अनुसार विज्ञापनदाता (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/exportsAsync Export (export scope)Export की कीमत
POST/v1/exports/quoteऑर्डर से पहले Export की कीमत: पंक्तियाँ, मुफ़्त पंक्तियाँ, छूटरिक्वेस्ट
GET/v1/exports/{id}स्थिति और डाउनलोड लिंकमुफ़्त
GET/v1/feedsEnterprise: दैनिक फ़ीड के दिन (नए, बदले और हटाए गए चैनल, Parquet)मुफ़्त
GET/v1/feeds/{date}Enterprise: दिन की फ़ाइल का साइन किया हुआ लिंक (export scope)दिन की पंक्तियाँ अनुबंध दर पर, एक बार

फ़िल्टर (ChannelQuery)

query ऑब्जेक्ट /channels/search, /channels/count और /exports के लिए एक जैसा है। खाली फ़ील्ड न भेजें।

qstringटेक्स्ट: शीर्षक, username, विवरण, पोस्ट
category_ids / exclude_category_idsint[]श्रेणियाँ (क्षेत्र या उप-श्रेणियाँ)
channel_idsint[]विशिष्ट चैनल
languages / exclude_languagesstring[]भाषा कोड: ru, en, uk…
countries / regions / exclude_countriesstring[]भूगोल: ISO देश कोड (IN, US) और /v1/geo से क्षेत्र "US:Texas"; क्षेत्र केवल अपने देश को सीमित करता है
kindall | channel | groupप्रकार
subscribers_min / subscribers_maxintसब्सक्राइबर
avg_views_min, reach_24h_minnumberव्यूज़ और 24 घंटे की रीच
er_min, err_24h_minnumberER / ERR, %
growth_7d_min, growth_30d_min, growth_pct_30d_minnumberग्रोथ
posts_30d_min, last_post_afterint, dateगतिविधि
chat_mau_minintसक्रिय कमेंट करने वाले: डिस्कशन चैट में यूनिक लेखक, 30 दिन
daily_reach_minintदैनिक रीच (अनुमान): दिन की पोस्ट के 24 घंटे के व्यूज़ का योग; 30 दिन का औसत
reach_48h_minint48 घंटे पर पोस्ट रीच: प्रकाशन के 48 घंटे बाद पोस्ट के औसत व्यूज़, 30 दिनों में
premium_share_min0..100चर्चा लेखकों में Telegram Premium हिस्सा, %, अनुमान (50+ लेखक)
female_share_min0..100पहचाने गए नाम वाले लेखकों में महिलाओं का हिस्सा, %, अनुमान — न्यूनतम
female_share_max0..100वही — अधिकतम
created_after / created_beforedateबनाए जाने की तारीख
has_ads_contact, ad_share_maxbool, 0..1विज्ञापन
fraud_max0..1फ्रॉड स्कोर की सीमा
verified_only, exclude_scamboolफ़्लैग (exclude_scam=true डिफ़ॉल्ट रूप से)
sort, orderstringसॉर्ट फ़ील्ड; 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": ["hi"], "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 का इस्तेमाल करें।
  • हर key के लिए यूनिक चैनलों की एक सख़्त दैनिक सीमा है; इसे पार करने पर key मैनुअल जाँच तक फ़्रीज़ हो जाती है।

एरर

सभी एरर का फ़ॉर्मेट एक जैसा है:

{"error": {"code": "payment_required", "message": "…"}}
  • 401 invalid_api_key — अमान्य या रद्द की गई key
  • 402 payment_required / 402 insufficient_funds — बैलेंस खत्म हो गया, डैशबोर्ड में टॉप-अप करें (body में need/have)
  • 403 api_not_in_plan, 403 scope_required, 403 key_frozen, 403 ip_not_allowed
  • 429 rate_limited — RPS सीमा पार हो गई; उतने सेकंड रुकें जितने यहाँ बताए गए हैं: Retry-After
  • 400 too_deep, 400 bad_cursor, 422 — अमान्य पैरामीटर

Webhooks

देखे जा रहे चैनलों की नई पोस्ट सीधे आपके सर्वर पर: हर पोस्ट के लिए JSON body वाला एक HTTP POST, चाहें तो कीवर्ड फ़िल्टर के साथ।

देरी के बारे में साफ़ बात: हमारा crawler हर चैनल को 3–14 दिन में एक बार देखता है, इसलिए पोस्ट बैच में आती हैं, अक्सर प्रकाशन के कई दिन बाद। हमारे पास आने के बाद पोस्ट लगभग एक मिनट में डिलीवर होती है; event में असली तारीख और delay_seconds होते हैं। यह real-time फ़ीड नहीं है।

Endpoint बनाएँ डैशबोर्ड → Webhooks में या नीचे दिए API से, फिर subscriptions जोड़ें: चैनलों की सूची (id या @username) और वैकल्पिक कीवर्ड — पोस्ट तब डिलीवर होती है जब उसमें इनमें से कोई हो (case-insensitive)।

  • 2xx जवाब के साथ डिलीवर हर पोस्ट 0.5 क्रेडिट की है, जो key (या संगठन) के बैलेंस से कटती है। मैनेजमेंट, टेस्ट ping और विफल प्रयास मुफ़्त हैं। बैलेंस शून्य होने पर डिलीवरी गुम नहीं होती, 72 घंटे तक इंतज़ार करती है।
  • सभी subscriptions में देखे जा रहे चैनल: Premium — 100, Business — 300, Super — 1,000। अधिकतम 5 endpoints, हर endpoint पर 50 subscriptions।
GET/v1/webhooksSubscriptions के साथ endpoints; प्लान लिमिट और 30 दिन का उपयोग
POST/v1/webhooksEndpoint बनाएँ {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}/subscriptionsSubscription जोड़ें {channels, keywords?, name?}
PATCH · DELETE/v1/webhooks/{id}/subscriptions/{sub_id}Subscription बदलें या हटाएँ
GET/v1/webhooks/{id}/deliveries[/{delivery_id}]डिलीवरी लॉग, नई पहले (?status=, ?before_id=)
POST/v1/webhooks/{id}/deliveries/{delivery_id}/retryविफल या समय-समाप्त डिलीवरी को फिर से कतार में डालें
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)। जिन requests का timestamp 5 मिनट से ज़्यादा अलग हो, उन्हें अस्वीकार करें।

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 error exponential backoff से दोहराया जाता है — 1, 2, 4… मिनट, अधिकतम 6 घंटे का अंतर, 10 प्रयास। Redirects फ़ॉलो नहीं होते। अगर विफलताएँ 24 घंटे तक चलती रहें (कम से कम लगातार 20), तो endpoint बंद हो जाता है और owner को ईमेल जाता है; PATCH active=true से चालू करें, बाकी डिलीवरी फिर शुरू होंगी।
  • X-TGMarket-Idempotency-Key (= event id) से duplicates हटाएँ: एक endpoint पर एक पोस्ट के हर प्रयास में यह एक जैसा रहता है, और कोई पोस्ट एक endpoint के लिए दो बार कतार में नहीं आती।
  • URL की शर्तें: सिर्फ़ https, सार्वजनिक domain या IP; private, loopback और link-local पते (भेजते समय DNS से मिले पते भी) अस्वीकार; URL में login/password नहीं। जल्दी 2xx लौटाएँ और प्रोसेसिंग async करें।