Documentación de la API

REST API v1 para buscar y exportar canales de Telegram. JSON, paginación por cursor y el mismo esquema de filtros que la interfaz y las exportaciones. El esquema legible por máquina es el OpenAPI del backend (/openapi.json).

URL base: https://tgmarket.io/api. Todas las rutas siguientes son relativas a ella.

Conectar asistentes de IA por MCP →

Autenticación

Crea una clave en Panel → Claves API (planes de pago). Formato de la clave: mk_live_<prefix>_<secret>; se muestra una sola vez. Envíala en la cabecera:

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

Ámbitos: read (por defecto) y export, para POST /v1/exports, POST/PATCH/DELETE /v1/webhooks. Como máximo dos claves activas, para que puedas rotarlas sin interrupciones.

Facturación

Pagas por los datos devueltos, no por las llamadas. Todo se cobra en créditos: 1 crédito = $0,001.

  • Cada solicitud de pago: 1 crédito ($1 por cada 1000 solicitudes).
  • Cada fila de canal: según la tarifa del conjunto de campos: Base 0,5 créditos, +Metrics 1,5, +Ads 2, History 3.
  • Cada publicación: 0,5 créditos.
  • Un canal que esta clave ya pagó en los últimos 30 días se devuelve gratis.
  • /count y facetas: solo la tarifa de solicitud.

El importe cobrado se devuelve en la cabecera X-Credits-Charged. Saldo y consumo: GET /v1/usage. Precios de exportación: consulta los precios.

Endpoints

MétodoRutaDescripciónCoste
GET/v1/categoriesÁrbol de categoríasgratis
GET/v1/languagesIdiomas con número de canalesgratis
GET/v1/geoPaíses con número de canales; ?country= — sus regiones (códigos para el filtro regions)gratis
GET/v1/usageSaldo, consumo diario, límitesgratis
POST/v1/channels/searchFiltros + q, cursor, hasta 100 por páginasolicitud + filas
POST/v1/channels/countRecuentos y facetassolicitud
GET/v1/channels/{id|username}Ficha del canal (?fields=base,metrics,ads; reach — alcance diario)solicitud + fila
GET/v1/channels/{id}/historySuscriptores, métricas y alcance diario por día (?days=)solicitud + History
GET/v1/channels/{id}/postsPublicaciones recientes (?limit= hasta 100)solicitud + publicaciones
GET/v1/channels/{id}/referencesCitado por / cita asolicitud + filas
GET/v1/advertisersAnunciantes por número de canales en 30 días (group, lang, country, q)solicitud
GET/v1/advertisers/{key}Anunciante y sus canales anfitriones (limit, offset)solicitud + filas
POST/v1/posts/searchBúsqueda de texto completo en publicacionessolicitud + publicaciones
POST/v1/posts/trendMenciones de una palabra en el tiempo: publicaciones, canales y vistas por día (group=day|week)solicitud + 0,01 por punto
POST/v1/exportsExportación asíncrona (ámbito export)precio de exportación
POST/v1/exports/quotePrecio de la exportación antes de pedir: filas, filas gratuitas, descuentossolicitud
GET/v1/exports/{id}Estado y enlace de descargagratis
GET/v1/feedsEnterprise: días del feed diario (canales nuevos, modificados y eliminados, Parquet)gratis
GET/v1/feeds/{date}Enterprise: enlace firmado al archivo del día (scope export)filas del día a la tarifa del contrato, una vez

Filtros (ChannelQuery)

El objeto query es el mismo para /channels/search, /channels/count y /exports. Omite los campos vacíos.

qstringtexto: título, username, descripción, publicaciones
category_ids / exclude_category_idsint[]categorías (áreas o subcategorías)
channel_idsint[]canales concretos
languages / exclude_languagesstring[]códigos de idioma: ru, en, uk…
countries / regions / exclude_countriesstring[]geo: códigos de país ISO (IN, US) y regiones «US:Texas» de /v1/geo; una región solo acota su propio país
kindall | channel | grouptipo
subscribers_min / subscribers_maxintsuscriptores
avg_views_min, reach_24h_minnumbervistas y alcance en 24 h
er_min, err_24h_minnumberER / ERR, %
growth_7d_min, growth_30d_min, growth_pct_30d_minnumbercrecimiento
posts_30d_min, last_post_afterint, dateactividad
chat_mau_minintcomentaristas activos: autores únicos en el chat de discusión, 30 d
daily_reach_minintalcance diario (estimación): vistas a 24 h de las publicaciones del día, sumadas; media de 30 d
reach_48h_minintalcance de la publicación a 48 h: vistas medias 48 h después de publicar, en 30 d
premium_share_min0..100cuota de Telegram Premium entre autores de la discusión, %, estimación (50+ autores)
female_share_min0..100cuota de mujeres entre autores con nombre reconocido, %, estimación — mín.
female_share_max0..100lo mismo — máx.
created_after / created_beforedatefecha de creación
has_ads_contact, ad_share_maxbool, 0..1publicidad
fraud_max0..1umbral del índice de fraude
verified_only, exclude_scamboolindicadores (exclude_scam=true por defecto)
sort, orderstringcampo de ordenación; 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

Ejemplos

Buscar canales

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

Respuesta:

{
  "items": [{"id": 2365318039, "username": "GPTronhub", "title": "…", "subscribers": 169432, "er": 0.16, …}],
  "total": 605,
  "next_cursor": "eyJoIjoi…"   // pásalo como cursor en la siguiente solicitud
}

Solo el recuento

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

Ficha e historial

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"

Exportación

curl -X POST https://tgmarket.io/api/v1/exports -H "Authorization: Bearer $MK_KEY" -H "Content-Type: application/json" \
  -d '{"query": {"q": "cripto"}, "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://…", …}

Límites de uso

  • Premium: 1 solicitud por segundo; Business: 3; Super: 10; Enterprise: según contrato.
  • Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
  • Más allá de 10.000 resultados por consulta, usa /v1/exports.
  • Hay un límite diario estricto de canales únicos por clave; si se supera, la clave se congela hasta una revisión manual.

Errores

Todos los errores comparten un mismo formato:

{"error": {"code": "payment_required", "message": "…"}}
  • 401 invalid_api_key — clave no válida o revocada
  • 402 payment_required / 402 insufficient_funds — saldo agotado, recárgalo en el panel (need/have en el cuerpo)
  • 403 api_not_in_plan, 403 scope_required, 403 key_frozen, 403 ip_not_allowed
  • 429 rate_limited — RPS superado; espera los segundos indicados en Retry-After
  • 400 too_deep, 400 bad_cursor, 422 — parámetros no válidos

Webhooks

Recibe en tu servidor las nuevas publicaciones de los canales que sigues: un POST HTTP con cuerpo JSON por publicación, con filtro opcional por palabras clave.

La latencia, con franqueza: nuestro rastreador vuelve a cada canal cada 3–14 días, así que las publicaciones llegan en lotes, a menudo días después de publicarse. Una vez recogida, la publicación se entrega en aproximadamente un minuto; el evento incluye la fecha original y delay_seconds. No es un flujo en tiempo real.

Crea un endpoint en Panel → Webhooks o con la API de abajo y añade suscripciones: una lista de canales (id o @username) y palabras clave opcionales; la publicación se entrega si contiene alguna (sin distinguir mayúsculas).

  • Cada publicación entregada con respuesta 2xx cuesta 0,5 créditos del saldo de la clave (u organización). La gestión, los ping de prueba y los intentos fallidos son gratis. Con saldo cero, las entregas esperan (hasta 72 horas) en lugar de perderse.
  • Canales seguidos en todas las suscripciones: Premium — 100, Business — 300, Super — 1.000. Hasta 5 endpoints y 50 suscripciones por endpoint.
GET/v1/webhooksEndpoints con suscripciones; límite del plan y uso en 30 días
POST/v1/webhooksCrear endpoint {name, url}; el secreto de firma se devuelve una sola vez
GET · PATCH · DELETE/v1/webhooks/{id}Obtener, modificar {name, url, active} o eliminar
POST/v1/webhooks/{id}/rotate-secretNuevo secreto de firma (el anterior deja de funcionar al instante)
POST/v1/webhooks/{id}/testEnviar un evento ping ahora (gratis)
POST/v1/webhooks/{id}/subscriptionsAñadir suscripción {channels, keywords?, name?}
PATCH · DELETE/v1/webhooks/{id}/subscriptions/{sub_id}Modificar o eliminar una suscripción
GET/v1/webhooks/{id}/deliveries[/{delivery_id}]Registro de entregas, de la más reciente (?status=, ?before_id=)
POST/v1/webhooks/{id}/deliveries/{delivery_id}/retryVolver a encolar una entrega fallida o caducada
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"]}'

Cuerpo del evento

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

Firma

Cada solicitud lleva las cabeceras X-TGMarket-Event (post.created o ping), X-TGMarket-Delivery, X-TGMarket-Idempotency-Key, X-TGMarket-Timestamp y X-TGMarket-Signature: v1=<hex>, donde hex = HMAC-SHA256(secret, timestamp + "." + cuerpo sin modificar). Rechaza solicitudes cuya marca de tiempo difiera más de 5 minutos.

Verificar la firma (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"])
  • Reintentos: cualquier respuesta no 2xx, tiempo agotado (10 s) o error de conexión se reintenta con espera exponencial — 1, 2, 4… minutos, hasta 6 horas entre intentos, 10 intentos. No se siguen redirecciones. Si los fallos continúan 24 horas (al menos 20 seguidos), el endpoint se desactiva y el propietario recibe un correo; reactívalo con PATCH active=true y las entregas pendientes continúan.
  • Elimina duplicados con X-TGMarket-Idempotency-Key (= id del evento): es igual en todos los intentos de una publicación a un endpoint, y una publicación nunca se encola dos veces para el mismo endpoint.
  • Requisitos de la URL: solo https, dominio o IP públicos; se rechazan direcciones privadas, loopback y link-local (también lo que resuelva el DNS al enviar); sin credenciales en la URL. Responde rápido con 2xx y procesa de forma asíncrona.