API-Dokumentation
REST API v1 zum Suchen und Exportieren von Telegram-Kanälen. JSON, Cursor-Paginierung, dasselbe Filterschema wie in der Oberfläche und bei Exporten. Das maschinenlesbare Schema ist das OpenAPI des Backends (/openapi.json).
Basis-URL: https://tgmarket.io/api. Alle folgenden Pfade sind relativ dazu.
KI-Assistenten per MCP verbinden →
Authentifizierung
Erstellen Sie einen Schlüssel unter Dashboard → API-Schlüssel (kostenpflichtige Tarife). Schlüsselformat: mk_live_<prefix>_<secret>, wird nur einmal angezeigt. Senden Sie ihn im Header:
Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# oder
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxxScopes: read (Standard) und export — für POST /v1/exports, POST/PATCH/DELETE /v1/webhooks. Höchstens zwei aktive Schlüssel, damit Sie ohne Ausfallzeit rotieren können.
Abrechnung
Sie zahlen für gelieferte Daten, nicht für Aufrufe. Alles wird in Credits abgerechnet: 1 Credit = $0,001.
- Jede kostenpflichtige Anfrage — 1 Credit ($1 pro 1.000 Anfragen).
- Jede Kanalzeile — zum Satz des Feldsets: Base 0,5 Credits, +Metrics 1,5, +Ads 2, History 3.
- Jeder Beitrag — 0,5 Credits.
- Ein Kanal, den dieser Schlüssel innerhalb von 30 Tagen bereits bezahlt hat, wird kostenlos geliefert.
- /count und Facetten — nur die Anfragegebühr.
Der abgebuchte Betrag steht im Header X-Credits-Charged. Guthaben und Nutzung — GET /v1/usage. Exportpreise — siehe Preise.
Endpunkte
| Methode | Pfad | Beschreibung | Kosten |
|---|---|---|---|
| GET | /v1/categories | Kategorienbaum | kostenlos |
| GET | /v1/languages | Sprachen mit Kanalanzahl | kostenlos |
| GET | /v1/geo | Länder mit Kanalanzahl; ?country= – Regionen des Landes (Codes für den Filter regions) | kostenlos |
| GET | /v1/usage | Guthaben, tägliche Nutzung, Limits | kostenlos |
| POST | /v1/channels/search | Filter + q, cursor, bis zu 100 pro Seite | Anfrage + Zeilen |
| POST | /v1/channels/count | Zählungen und Facetten | Anfrage |
| GET | /v1/channels/{id|username} | Kanalkarte (?fields=base,metrics,ads; reach — Tagesreichweite) | Anfrage + Zeile |
| GET | /v1/channels/{id}/history | Tägliche Abonnenten, Kennzahlen und Tagesreichweite (?days=) | Anfrage + History |
| GET | /v1/channels/{id}/posts | Neueste Beiträge (?limit= bis 100) | Anfrage + Beiträge |
| GET | /v1/channels/{id}/references | Zitiert von / zitiert | Anfrage + Zeilen |
| GET | /v1/advertisers | Werbetreibende nach Zahl der Kanäle in 30 Tagen (group, lang, country, q) | Anfrage |
| GET | /v1/advertisers/{key} | Werbetreibender und seine Kanäle (limit, offset) | Anfrage + Zeilen |
| POST | /v1/posts/search | Volltextsuche in Beiträgen | Anfrage + Beiträge |
| POST | /v1/posts/trend | Erwähnungen eines Wortes im Zeitverlauf: Beiträge, Kanäle und Aufrufe pro Tag (group=day|week) | Anfrage + 0,01 pro Datenpunkt |
| POST | /v1/exports | Asynchroner Export (Scope export) | Exportpreis |
| POST | /v1/exports/quote | Exportpreis vor der Bestellung: Zeilen, kostenlose Zeilen, Rabatte | Anfrage |
| GET | /v1/exports/{id} | Status und Download-Link | kostenlos |
| GET | /v1/feeds | Enterprise: Tage des täglichen Feeds (neue, geänderte und gelöschte Kanäle, Parquet) | kostenlos |
| GET | /v1/feeds/{date} | Enterprise: signierter Link zur Tagesdatei (Scope export) | Zeilen des Tages zum Vertragssatz, einmalig |
Filter (ChannelQuery)
Das query-Objekt ist für /channels/search, /channels/count und /exports identisch. Leere Felder weglassen.
| q | string | Text: Titel, Username, Beschreibung, Beiträge |
| category_ids / exclude_category_ids | int[] | Kategorien (Themenbereiche oder Unterkategorien) |
| channel_ids | int[] | bestimmte Kanäle |
| languages / exclude_languages | string[] | Sprachcodes: ru, en, uk… |
| countries / regions / exclude_countries | string[] | Geo: ISO-Ländercodes (IN, US) und Regionen „US:Texas“ aus /v1/geo; eine Region schränkt nur ihr eigenes Land ein |
| kind | all | channel | group | Typ |
| subscribers_min / subscribers_max | int | Abonnenten |
| avg_views_min, reach_24h_min | number | Aufrufe und Reichweite 24 h |
| er_min, err_24h_min | number | ER / ERR, % |
| growth_7d_min, growth_30d_min, growth_pct_30d_min | number | Wachstum |
| posts_30d_min, last_post_after | int, date | Aktivität |
| chat_mau_min | int | aktive Kommentatoren: eindeutige Autoren im Diskussionschat, 30 T. |
| daily_reach_min | int | Tagesreichweite (Schätzung): 24-h-Aufrufe der Beiträge eines Tages, summiert; Mittel über 30 T. |
| reach_48h_min | int | Beitragsreichweite nach 48 Std.: durchschnittliche Aufrufe 48 Std. nach Veröffentlichung, über 30 T. |
| premium_share_min | 0..100 | Anteil Telegram Premium unter Diskussionsautoren, %, Schätzung (ab 50 Autoren) |
| female_share_min | 0..100 | Frauenanteil unter Diskussionsautoren mit erkanntem Vornamen, %, Schätzung — min |
| female_share_max | 0..100 | dasselbe — max |
| created_after / created_before | date | Erstellungsdatum |
| has_ads_contact, ad_share_max | bool, 0..1 | Werbung |
| fraud_max | 0..1 | Schwellenwert des Betrugs-Scores |
| verified_only, exclude_scam | bool | Flags (standardmäßig exclude_scam=true) |
| sort, order | string | Sortierfeld; 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 |
Beispiele
Kanäle suchen
curl -X POST https://tgmarket.io/api/v1/channels/search \
-H "Authorization: Bearer $MK_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": {"q": "Aktienmarkt", "languages": ["de"], "subscribers_min": 5000, "sort": "growth_30d"},
"fields": ["base", "metrics"],
"limit": 100
}'Antwort:
{
"items": [{"id": 2365318039, "username": "GPTronhub", "title": "…", "subscribers": 169432, "er": 0.16, …}],
"total": 605,
"next_cursor": "eyJoIjoi…" // als cursor in der nächsten Anfrage übergeben
}Nur zählen
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]}}'Kanalkarte und Verlauf
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": "Krypto"}, "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://…", …}Ratenlimits
- Premium — 1 Anfrage pro Sekunde, Business — 3, Super — 10, Enterprise — laut Vertrag.
- Jede Antwort enthält
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset. - Mehr als 10.000 Ergebnisse pro Abfrage — verwenden Sie /v1/exports.
- Ein festes Tageslimit für eindeutige Kanäle pro Schlüssel; bei Überschreitung wird der Schlüssel bis zur manuellen Prüfung gesperrt.
Fehler
Alle Fehler haben dasselbe Format:
{"error": {"code": "payment_required", "message": "…"}}401 invalid_api_key— ungültiger oder widerrufener Schlüssel402 payment_required/402 insufficient_funds— Guthaben aufgebraucht, laden Sie es im Dashboard auf (need/have im Body)403 api_not_in_plan,403 scope_required,403 key_frozen,403 ip_not_allowed429 rate_limited— RPS überschritten; warten Sie die Anzahl Sekunden aus dem HeaderRetry-After400 too_deep,400 bad_cursor,422— ungültige Parameter
Webhooks
Neue Beiträge beobachteter Kanäle werden an Ihren Server gepusht: ein HTTP-POST mit JSON-Body pro Beitrag, optional nach Stichwörtern gefiltert.
Ehrlich zur Latenz: Unser Crawler besucht jeden Kanal alle 3–14 Tage, Beiträge kommen daher gebündelt, oft Tage nach der Veröffentlichung. Nach dem Erfassen wird ein Beitrag in etwa einer Minute zugestellt; das Ereignis enthält das Originaldatum und delay_seconds. Webhooks sind kein Echtzeit-Feed.
Legen Sie einen Endpunkt unter Dashboard → Webhooks oder per API an und fügen Sie Abos hinzu: eine Kanalliste (IDs oder @usernames) und optionale Stichwörter — ein Beitrag wird zugestellt, wenn er eines davon enthält (ohne Groß-/Kleinschreibung).
- Jeder mit 2xx zugestellte Beitrag kostet 0,5 Credits vom Guthaben des Schlüssels (bzw. der Organisation). Verwaltung, Test-Pings und fehlgeschlagene Versuche sind kostenlos. Bei Guthaben null warten Zustellungen (bis 72 Stunden), statt verworfen zu werden.
- Beobachtete Kanäle über alle Abos: Premium — 100, Business — 300, Super — 1.000. Bis zu 5 Endpunkte, 50 Abos pro Endpunkt.
| GET | /v1/webhooks | Endpunkte mit Abos; Tariflimit und Verbrauch 30 Tage |
| POST | /v1/webhooks | Endpunkt anlegen {name, url}; das Signatur-Secret kommt einmalig zurück |
| GET · PATCH · DELETE | /v1/webhooks/{id} | Endpunkt abrufen, ändern {name, url, active} oder löschen |
| POST | /v1/webhooks/{id}/rotate-secret | Neues Signatur-Secret (das alte gilt sofort nicht mehr) |
| POST | /v1/webhooks/{id}/test | Sofort ein ping-Ereignis senden (kostenlos) |
| POST | /v1/webhooks/{id}/subscriptions | Abo hinzufügen {channels, keywords?, name?} |
| PATCH · DELETE | /v1/webhooks/{id}/subscriptions/{sub_id} | Abo ändern oder löschen |
| GET | /v1/webhooks/{id}/deliveries[/{delivery_id}] | Zustellprotokoll, neueste zuerst (?status=, ?before_id=) |
| POST | /v1/webhooks/{id}/deliveries/{delivery_id}/retry | Fehlgeschlagene oder abgelaufene Zustellung erneut einreihen |
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"]}'Ereignis-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
}Signatur
Jede Anfrage enthält die Header X-TGMarket-Event (post.created oder ping), X-TGMarket-Delivery, X-TGMarket-Idempotency-Key, X-TGMarket-Timestamp und X-TGMarket-Signature: v1=<hex>, wobei hex = HMAC-SHA256(secret, timestamp + "." + Roh-Body). Lehnen Sie Anfragen ab, deren Zeitstempel mehr als 5 Minuten abweicht.
Signatur prüfen (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"])- Wiederholungen: Jede Nicht-2xx-Antwort, Timeout (10 s) oder Verbindungsfehler wird mit exponentiellem Backoff wiederholt — 1, 2, 4 … Minuten, höchstens 6 Stunden Abstand, 10 Versuche. Weiterleitungen werden nicht verfolgt. Halten die Fehler 24 Stunden an (mindestens 20 in Folge), wird der Endpunkt deaktiviert und der Inhaber per E-Mail informiert; mit PATCH active=true reaktivieren, ausstehende Zustellungen laufen weiter.
- Deduplizieren Sie über X-TGMarket-Idempotency-Key (= Ereignis-ID): Er ist für alle Versuche eines Beitrags an einen Endpunkt gleich, und ein Beitrag wird pro Endpunkt nie zweimal eingereiht.
- URL-Anforderungen: nur https, öffentliche Domain oder IP; private, Loopback- und Link-Local-Adressen (auch als DNS-Ergebnis beim Senden) werden abgelehnt; keine Zugangsdaten in der URL. Schnell mit 2xx antworten und asynchron verarbeiten.