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_xxxxxxxxxxxxxxxx

Scopes: 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/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/exportsఅసింక్ Export (export scope)Export ధర
POST/v1/exports/quoteఆర్డర్‌కు ముందు ఎగుమతి ధర: వరుసలు, ఉచిత వరుసలు, తగ్గింపులురిక్వెస్ట్
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": ["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_allowed
  • 429 rate_limited — RPS మించిపోయింది; ఈ హెడర్‌లో ఉన్నన్ని సెకన్లు వేచి ఉండండి: Retry-After
  • 400 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/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}]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‌గా ప్రాసెస్ చేయండి.