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_xxxxxxxxxxxxxxxxScopes : 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éthode | Chemin | Description | Coût |
|---|---|---|---|
| GET | /v1/categories | Arborescence des catégories | gratuit |
| GET | /v1/languages | Langues avec nombre de chaînes | gratuit |
| GET | /v1/geo | Pays avec le nombre de canaux ; ?country= — ses régions (codes pour le filtre regions) | gratuit |
| GET | /v1/usage | Solde, consommation quotidienne, limites | gratuit |
| POST | /v1/channels/search | Filtres + q, cursor, jusqu'à 100 par page | requête + lignes |
| POST | /v1/channels/count | Comptages et facettes | requê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}/history | Abonnés, métriques et portée quotidienne par jour (?days=) | requête + History |
| GET | /v1/channels/{id}/posts | Publications récentes (?limit= jusqu'à 100) | requête + publications |
| GET | /v1/channels/{id}/references | Cité par / cite | requête + lignes |
| GET | /v1/advertisers | Annonceurs 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/search | Recherche plein texte dans les publications | requête + publications |
| POST | /v1/posts/trend | Mentions d'un mot dans le temps : publications, chaînes et vues par jour (group=day|week) | requête + 0,01 par point |
| POST | /v1/exports | Export asynchrone (scope export) | prix de l'export |
| POST | /v1/exports/quote | Prix de l'export avant commande : lignes, lignes gratuites, remises | requête |
| GET | /v1/exports/{id} | Statut et lien de téléchargement | gratuit |
| GET | /v1/feeds | Enterprise : 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.
| q | string | texte : titre, username, description, publications |
| category_ids / exclude_category_ids | int[] | catégories (domaines ou sous-catégories) |
| channel_ids | int[] | chaînes précises |
| languages / exclude_languages | string[] | codes de langue : ru, en, uk… |
| countries / regions / exclude_countries | string[] | géo : codes pays ISO (IN, US) et régions « US:Texas » de /v1/geo ; une région ne restreint que son propre pays |
| kind | all | channel | group | type |
| subscribers_min / subscribers_max | int | abonnés |
| avg_views_min, reach_24h_min | number | vues et portée 24 h |
| er_min, err_24h_min | number | ER / ERR, % |
| growth_7d_min, growth_30d_min, growth_pct_30d_min | number | croissance |
| posts_30d_min, last_post_after | int, date | activité |
| chat_mau_min | int | commentateurs actifs : auteurs uniques dans le chat de discussion, 30 j |
| daily_reach_min | int | portée quotidienne (estimation) : vues à 24 h des publications du jour, additionnées ; moyenne sur 30 j |
| reach_48h_min | int | portée d'une publication à 48 h : vues moyennes 48 h après publication, sur 30 j |
| premium_share_min | 0..100 | part de Telegram Premium parmi les auteurs de la discussion, %, estimation (50+ auteurs) |
| female_share_min | 0..100 | part de femmes parmi les auteurs au prénom reconnu, %, estimation — min |
| female_share_max | 0..100 | idem — max |
| created_after / created_before | date | date de création |
| has_ads_contact, ad_share_max | bool, 0..1 | publicité |
| fraud_max | 0..1 | seuil du score de fraude |
| verified_only, exclude_scam | bool | indicateurs (exclude_scam=true par défaut) |
| sort, order | string | champ 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ée402 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_allowed429 rate_limited— RPS dépassé ; attendez le nombre de secondes indiqué dansRetry-After400 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/webhooks | Points de terminaison et abonnements ; limite du forfait et usage sur 30 jours |
| POST | /v1/webhooks | Cré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-secret | Nouveau secret de signature (l’ancien cesse aussitôt de fonctionner) |
| POST | /v1/webhooks/{id}/test | Envoyer un événement ping immédiatement (gratuit) |
| POST | /v1/webhooks/{id}/subscriptions | Ajouter 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}/retry | Remettre 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.