Documentation API

REST API v1 pour rechercher et exporter des chaînes Telegram. JSON, pagination par curseur, même schéma de filtres que l'interface et les exports. Le schéma lisible par machine est l'OpenAPI du backend (/openapi.json).

URL de base: https://tgmarket.io/api. Tous les chemins ci-dessous sont relatifs à cette URL.

Connecter des assistants IA via MCP →

Authentification

Créez une clé dans Tableau de bord → Clés API (offres payantes). Format de la clé : mk_live_<prefix>_<secret>, affichée une seule fois. Envoyez-la dans l'en-tête :

Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# ou
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxx

Scopes : read (par défaut) et export — pour POST /v1/exports, POST/PATCH/DELETE /v1/webhooks. Deux clés actives au maximum, pour pouvoir effectuer une rotation sans interruption.

Facturation

Vous payez les données renvoyées, pas les appels. Tout est facturé en crédits : 1 crédit = 0,001 $.

  • Chaque requête payante — 1 crédit (1 $ les 1 000 requêtes).
  • Chaque ligne de chaîne — au tarif de l'ensemble de champs : Base 0,5 crédit, +Metrics 1,5, +Ads 2, History 3.
  • Chaque publication — 0,5 crédit.
  • Une chaîne déjà payée par cette clé au cours des 30 derniers jours est renvoyée gratuitement.
  • /count et facettes — frais de requête uniquement.

Le montant débité est renvoyé dans l'en-tête X-Credits-Charged. Solde et consommation — GET /v1/usage. Prix des exports — voir les tarifs.

Endpoints

MéthodeCheminDescriptionCoût
GET/v1/categoriesArborescence des catégoriesgratuit
GET/v1/languagesLangues avec nombre de chaînesgratuit
GET/v1/geoPays avec le nombre de canaux ; ?country= — ses régions (codes pour le filtre regions)gratuit
GET/v1/usageSolde, consommation quotidienne, limitesgratuit
POST/v1/channels/searchFiltres + q, cursor, jusqu'à 100 par pagerequête + lignes
POST/v1/channels/countComptages et facettesrequête
GET/v1/channels/{id|username}Fiche de la chaîne (?fields=base,metrics,ads; reach — portée quotidienne)requête + ligne
GET/v1/channels/{id}/historyAbonnés, métriques et portée quotidienne par jour (?days=)requête + History
GET/v1/channels/{id}/postsPublications récentes (?limit= jusqu'à 100)requête + publications
GET/v1/channels/{id}/referencesCité par / citerequête + lignes
GET/v1/advertisersAnnonceurs classés par nombre de chaînes sur 30 jours (group, lang, country, q)requête
GET/v1/advertisers/{key}Annonceur et ses chaînes hôtes (limit, offset)requête + lignes
POST/v1/posts/searchRecherche plein texte dans les publicationsrequête + publications
POST/v1/posts/trendMentions d'un mot dans le temps : publications, chaînes et vues par jour (group=day|week)requête + 0,01 par point
POST/v1/exportsExport asynchrone (scope export)prix de l'export
POST/v1/exports/quotePrix de l'export avant commande : lignes, lignes gratuites, remisesrequête
GET/v1/exports/{id}Statut et lien de téléchargementgratuit
GET/v1/feedsEnterprise : jours du flux quotidien (chaînes nouvelles, modifiées et supprimées, Parquet)gratuit
GET/v1/feeds/{date}Enterprise : lien signé vers le fichier du jour (scope export)lignes du jour au tarif du contrat, une fois

Filtres (ChannelQuery)

L'objet query est le même pour /channels/search, /channels/count et /exports. Omettez les champs vides.

qstringtexte : titre, username, description, publications
category_ids / exclude_category_idsint[]catégories (domaines ou sous-catégories)
channel_idsint[]chaînes précises
languages / exclude_languagesstring[]codes de langue : ru, en, uk…
countries / regions / exclude_countriesstring[]géo : codes pays ISO (IN, US) et régions « US:Texas » de /v1/geo ; une région ne restreint que son propre pays
kindall | channel | grouptype
subscribers_min / subscribers_maxintabonnés
avg_views_min, reach_24h_minnumbervues et portée 24 h
er_min, err_24h_minnumberER / ERR, %
growth_7d_min, growth_30d_min, growth_pct_30d_minnumbercroissance
posts_30d_min, last_post_afterint, dateactivité
chat_mau_minintcommentateurs actifs : auteurs uniques dans le chat de discussion, 30 j
daily_reach_minintportée quotidienne (estimation) : vues à 24 h des publications du jour, additionnées ; moyenne sur 30 j
reach_48h_minintportée d'une publication à 48 h : vues moyennes 48 h après publication, sur 30 j
premium_share_min0..100part de Telegram Premium parmi les auteurs de la discussion, %, estimation (50+ auteurs)
female_share_min0..100part de femmes parmi les auteurs au prénom reconnu, %, estimation — min
female_share_max0..100idem — max
created_after / created_beforedatedate de création
has_ads_contact, ad_share_maxbool, 0..1publicité
fraud_max0..1seuil du score de fraude
verified_only, exclude_scamboolindicateurs (exclude_scam=true par défaut)
sort, orderstringchamp de tri ; 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

Exemples

Rechercher des chaînes

curl -X POST https://tgmarket.io/api/v1/channels/search \
  -H "Authorization: Bearer $MK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {"q": "bourse", "languages": ["fr"], "subscribers_min": 5000, "sort": "growth_30d"},
    "fields": ["base", "metrics"],
    "limit": 100
  }'

Réponse :

{
  "items": [{"id": 2365318039, "username": "GPTronhub", "title": "…", "subscribers": 169432, "er": 0.16, …}],
  "total": 605,
  "next_cursor": "eyJoIjoi…"   // à passer comme cursor dans la requête suivante
}

Comptage seul

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]}}'

Fiche et historique

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": "crypto"}, "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://…", …}

Limites de débit

  • Premium — 1 requête par seconde, Business — 3, Super — 10, Enterprise — selon contrat.
  • Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
  • Au-delà de 10 000 résultats par requête — utilisez /v1/exports.
  • Un plafond quotidien strict de chaînes uniques par clé ; le dépasser gèle la clé jusqu'à vérification manuelle.

Erreurs

Toutes les erreurs partagent le même format :

{"error": {"code": "payment_required", "message": "…"}}
  • 401 invalid_api_key — clé invalide ou révoquée
  • 402 payment_required / 402 insufficient_funds — solde épuisé, rechargez-le dans le tableau de bord (need/have dans le corps)
  • 403 api_not_in_plan, 403 scope_required, 403 key_frozen, 403 ip_not_allowed
  • 429 rate_limited — RPS dépassé ; attendez le nombre de secondes indiqué dans Retry-After
  • 400 too_deep, 400 bad_cursor, 422 — paramètres invalides

Webhooks

Recevez sur votre serveur les nouvelles publications des chaînes suivies : un POST HTTP avec un corps JSON par publication, éventuellement filtré par mots-clés.

Latence, en toute franchise : notre robot repasse sur chaque chaîne tous les 3 à 14 jours ; les publications arrivent donc par lots, souvent plusieurs jours après leur parution. Une fois collectée, une publication est livrée en une minute environ ; l’événement contient la date d’origine et delay_seconds. Ce n’est pas un flux temps réel.

Créez un point de terminaison dans Tableau de bord → Webhooks ou via l’API ci-dessous, puis ajoutez des abonnements : une liste de chaînes (id ou @username) et des mots-clés facultatifs — une publication est livrée si elle contient l’un d’eux (sans tenir compte de la casse).

  • Chaque publication livrée avec une réponse 2xx coûte 0,5 crédit, débité du solde de la clé (ou de l’organisation). La gestion, les pings de test et les tentatives échouées sont gratuits. Avec un solde nul, les livraisons attendent (jusqu’à 72 heures) au lieu d’être perdues.
  • Chaînes suivies sur tous les abonnements : Premium — 100, Business — 300, Super — 1 000. Jusqu’à 5 points de terminaison, 50 abonnements chacun.
GET/v1/webhooksPoints de terminaison et abonnements ; limite du forfait et usage sur 30 jours
POST/v1/webhooksCréer {name, url} ; le secret de signature n’est renvoyé qu’une fois
GET · PATCH · DELETE/v1/webhooks/{id}Lire, modifier {name, url, active} ou supprimer
POST/v1/webhooks/{id}/rotate-secretNouveau secret de signature (l’ancien cesse aussitôt de fonctionner)
POST/v1/webhooks/{id}/testEnvoyer un événement ping immédiatement (gratuit)
POST/v1/webhooks/{id}/subscriptionsAjouter un abonnement {channels, keywords?, name?}
PATCH · DELETE/v1/webhooks/{id}/subscriptions/{sub_id}Modifier ou supprimer un abonnement
GET/v1/webhooks/{id}/deliveries[/{delivery_id}]Journal des livraisons, du plus récent (?status=, ?before_id=)
POST/v1/webhooks/{id}/deliveries/{delivery_id}/retryRemettre en file une livraison échouée ou expirée
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"]}'

Corps de l’événement

{
  "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

Chaque requête porte les en-têtes X-TGMarket-Event (post.created ou ping), X-TGMarket-Delivery, X-TGMarket-Idempotency-Key, X-TGMarket-Timestamp et X-TGMarket-Signature: v1=<hex>, où hex = HMAC-SHA256(secret, timestamp + "." + corps brut). Rejetez les requêtes dont l’horodatage s’écarte de plus de 5 minutes.

Vérifier la 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"])
  • Nouvelles tentatives : toute réponse non 2xx, délai dépassé (10 s) ou erreur de connexion est réessayé avec un délai exponentiel — 1, 2, 4… minutes, au plus 6 heures d’écart, 10 tentatives. Les redirections ne sont pas suivies. Si les échecs durent 24 heures (au moins 20 d’affilée), le point de terminaison est désactivé et le propriétaire reçoit un e-mail ; réactivez-le avec PATCH active=true, les livraisons en attente reprennent.
  • Dédupliquez avec X-TGMarket-Idempotency-Key (= id de l’événement) : il est identique pour toutes les tentatives d’une publication vers un point de terminaison, et une publication n’est jamais mise deux fois en file pour un même point.
  • Exigences d’URL : https uniquement, domaine ou IP publics ; les adresses privées, loopback et link-local (y compris la résolution DNS au moment de l’envoi) sont refusées ; pas d’identifiants dans l’URL. Répondez vite en 2xx et traitez en asynchrone.