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étodo | Ruta | Descripción | Coste |
|---|---|---|---|
| GET | /v1/categories | Árbol de categorías | gratis |
| GET | /v1/languages | Idiomas con número de canales | gratis |
| GET | /v1/geo | Países con número de canales; ?country= — sus regiones (códigos para el filtro regions) | gratis |
| GET | /v1/usage | Saldo, consumo diario, límites | gratis |
| POST | /v1/channels/search | Filtros + q, cursor, hasta 100 por página | solicitud + filas |
| POST | /v1/channels/count | Recuentos y facetas | solicitud |
| GET | /v1/channels/{id|username} | Ficha del canal (?fields=base,metrics,ads; reach — alcance diario) | solicitud + fila |
| GET | /v1/channels/{id}/history | Suscriptores, métricas y alcance diario por día (?days=) | solicitud + History |
| GET | /v1/channels/{id}/posts | Publicaciones recientes (?limit= hasta 100) | solicitud + publicaciones |
| GET | /v1/channels/{id}/references | Citado por / cita a | solicitud + filas |
| GET | /v1/advertisers | Anunciantes 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/search | Búsqueda de texto completo en publicaciones | solicitud + publicaciones |
| POST | /v1/posts/trend | Menciones de una palabra en el tiempo: publicaciones, canales y vistas por día (group=day|week) | solicitud + 0,01 por punto |
| POST | /v1/exports | Exportación asíncrona (ámbito export) | precio de exportación |
| POST | /v1/exports/quote | Precio de la exportación antes de pedir: filas, filas gratuitas, descuentos | solicitud |
| GET | /v1/exports/{id} | Estado y enlace de descarga | gratis |
| GET | /v1/feeds | Enterprise: 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.
| q | string | texto: título, username, descripción, publicaciones |
| category_ids / exclude_category_ids | int[] | categorías (áreas o subcategorías) |
| channel_ids | int[] | canales concretos |
| languages / exclude_languages | string[] | códigos de idioma: ru, en, uk… |
| countries / regions / exclude_countries | string[] | 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 |
| kind | all | channel | group | tipo |
| subscribers_min / subscribers_max | int | suscriptores |
| avg_views_min, reach_24h_min | number | vistas y alcance en 24 h |
| er_min, err_24h_min | number | ER / ERR, % |
| growth_7d_min, growth_30d_min, growth_pct_30d_min | number | crecimiento |
| posts_30d_min, last_post_after | int, date | actividad |
| chat_mau_min | int | comentaristas activos: autores únicos en el chat de discusión, 30 d |
| daily_reach_min | int | alcance diario (estimación): vistas a 24 h de las publicaciones del día, sumadas; media de 30 d |
| reach_48h_min | int | alcance de la publicación a 48 h: vistas medias 48 h después de publicar, en 30 d |
| premium_share_min | 0..100 | cuota de Telegram Premium entre autores de la discusión, %, estimación (50+ autores) |
| female_share_min | 0..100 | cuota de mujeres entre autores con nombre reconocido, %, estimación — mín. |
| female_share_max | 0..100 | lo mismo — máx. |
| created_after / created_before | date | fecha de creación |
| has_ads_contact, ad_share_max | bool, 0..1 | publicidad |
| fraud_max | 0..1 | umbral del índice de fraude |
| verified_only, exclude_scam | bool | indicadores (exclude_scam=true por defecto) |
| sort, order | string | campo 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 revocada402 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_allowed429 rate_limited— RPS superado; espera los segundos indicados enRetry-After400 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/webhooks | Endpoints con suscripciones; límite del plan y uso en 30 días |
| POST | /v1/webhooks | Crear 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-secret | Nuevo secreto de firma (el anterior deja de funcionar al instante) |
| POST | /v1/webhooks/{id}/test | Enviar un evento ping ahora (gratis) |
| POST | /v1/webhooks/{id}/subscriptions | Añ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}/retry | Volver 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.