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_xxxxxxxxxxxxxxxx

Scopes: 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

MethodePfadBeschreibungKosten
GET/v1/categoriesKategorienbaumkostenlos
GET/v1/languagesSprachen mit Kanalanzahlkostenlos
GET/v1/geoLänder mit Kanalanzahl; ?country= – Regionen des Landes (Codes für den Filter regions)kostenlos
GET/v1/usageGuthaben, tägliche Nutzung, Limitskostenlos
POST/v1/channels/searchFilter + q, cursor, bis zu 100 pro SeiteAnfrage + Zeilen
POST/v1/channels/countZählungen und FacettenAnfrage
GET/v1/channels/{id|username}Kanalkarte (?fields=base,metrics,ads; reach — Tagesreichweite)Anfrage + Zeile
GET/v1/channels/{id}/historyTägliche Abonnenten, Kennzahlen und Tagesreichweite (?days=)Anfrage + History
GET/v1/channels/{id}/postsNeueste Beiträge (?limit= bis 100)Anfrage + Beiträge
GET/v1/channels/{id}/referencesZitiert von / zitiertAnfrage + Zeilen
GET/v1/advertisersWerbetreibende 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/searchVolltextsuche in BeiträgenAnfrage + Beiträge
POST/v1/posts/trendErwähnungen eines Wortes im Zeitverlauf: Beiträge, Kanäle und Aufrufe pro Tag (group=day|week)Anfrage + 0,01 pro Datenpunkt
POST/v1/exportsAsynchroner Export (Scope export)Exportpreis
POST/v1/exports/quoteExportpreis vor der Bestellung: Zeilen, kostenlose Zeilen, RabatteAnfrage
GET/v1/exports/{id}Status und Download-Linkkostenlos
GET/v1/feedsEnterprise: 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.

qstringText: Titel, Username, Beschreibung, Beiträge
category_ids / exclude_category_idsint[]Kategorien (Themenbereiche oder Unterkategorien)
channel_idsint[]bestimmte Kanäle
languages / exclude_languagesstring[]Sprachcodes: ru, en, uk…
countries / regions / exclude_countriesstring[]Geo: ISO-Ländercodes (IN, US) und Regionen „US:Texas“ aus /v1/geo; eine Region schränkt nur ihr eigenes Land ein
kindall | channel | groupTyp
subscribers_min / subscribers_maxintAbonnenten
avg_views_min, reach_24h_minnumberAufrufe und Reichweite 24 h
er_min, err_24h_minnumberER / ERR, %
growth_7d_min, growth_30d_min, growth_pct_30d_minnumberWachstum
posts_30d_min, last_post_afterint, dateAktivität
chat_mau_minintaktive Kommentatoren: eindeutige Autoren im Diskussionschat, 30 T.
daily_reach_minintTagesreichweite (Schätzung): 24-h-Aufrufe der Beiträge eines Tages, summiert; Mittel über 30 T.
reach_48h_minintBeitragsreichweite nach 48 Std.: durchschnittliche Aufrufe 48 Std. nach Veröffentlichung, über 30 T.
premium_share_min0..100Anteil Telegram Premium unter Diskussionsautoren, %, Schätzung (ab 50 Autoren)
female_share_min0..100Frauenanteil unter Diskussionsautoren mit erkanntem Vornamen, %, Schätzung — min
female_share_max0..100dasselbe — max
created_after / created_beforedateErstellungsdatum
has_ads_contact, ad_share_maxbool, 0..1Werbung
fraud_max0..1Schwellenwert des Betrugs-Scores
verified_only, exclude_scamboolFlags (standardmäßig exclude_scam=true)
sort, orderstringSortierfeld; 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üssel
  • 402 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_allowed
  • 429 rate_limited — RPS überschritten; warten Sie die Anzahl Sekunden aus dem Header Retry-After
  • 400 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/webhooksEndpunkte mit Abos; Tariflimit und Verbrauch 30 Tage
POST/v1/webhooksEndpunkt 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-secretNeues Signatur-Secret (das alte gilt sofort nicht mehr)
POST/v1/webhooks/{id}/testSofort ein ping-Ereignis senden (kostenlos)
POST/v1/webhooks/{id}/subscriptionsAbo 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}/retryFehlgeschlagene 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.