Documentación de TweetAPI

Usa la API REST de TweetAPI para obtener datos públicos de Twitter, publicar posts y gestionar interacciones.

Haz tu primera solicitud

Empieza con 100 unidades de API de prueba, de una sola vez, a 10 solicitudes por minuto. La mayoría de las llamadas medidas usan una unidad. No necesitas tarjeta de crédito ni un plan de pago, y las unidades de prueba no vencen.

Crea una cuenta de TweetAPI (disponible en inglés). Configuramos tu acceso gratuito a la API automáticamente.
Abre API Keys (disponible en inglés), elige Create Key, ponle un nombre y guarda la clave completa. Solo puedes verla completa al crearla; si no la guardaste, crea otra.
Abre la solicitud ya preparada que tienes abajo. Elige tu clave y presiona Try It! para consultar un perfil público. Esta solicitud no necesita autorizar ninguna cuenta de X.
Comprueba que recibes un 200 y un objeto JSON con data. El Playground llama a la API real y usa tus unidades de API.
Define la variable de entorno de abajo y ejecuta un ejemplo en tu propia aplicación.

Abrir el Playground con la solicitud preparada (el Playground está en inglés).

Ejecuta la misma solicitud en tu equipo

Reemplaza YOUR_API_KEY por la clave completa que guardaste. Define la variable en la terminal donde vas a ejecutar tu código. Guarda las claves en tu servidor: nunca las pongas en código de frontend ni las subas a Git.

macOS / Linux:

export TWEETAPI_API_KEY='YOUR_API_KEY'

PowerShell:

$env:TWEETAPI_API_KEY = 'YOUR_API_KEY'

cURL (Bash)

curl --fail-with-body \
  'https://api.tweetapi.com/tw-v2/user/by-username?username=elonmusk' \
  -H "X-API-Key: ${TWEETAPI_API_KEY:?Set TWEETAPI_API_KEY first}"

SDK de Python

Instala el SDK con pip install tweetapi. Guarda esto como quickstart.py y ejecuta python quickstart.py.

import os
from tweetapi import TweetAPI

client = TweetAPI(api_key=os.environ["TWEETAPI_API_KEY"])
user = client.user.get_by_username(username="elonmusk")
print(user["data"])

SDK de Node.js (Node.js 18 o superior)

Instala el SDK con npm install tweetapi-node. Guarda esto como quickstart.mjs y ejecuta node quickstart.mjs.

import TweetAPI from "tweetapi-node";

const apiKey = process.env.TWEETAPI_API_KEY;
if (!apiKey) throw new Error("Set TWEETAPI_API_KEY first");
const client = new TweetAPI({ apiKey });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data);

Si tu primera solicitud falla

Variable sin definir o un 401: asigna a TWEETAPI_API_KEY la clave completa, no la vista enmascarada de la lista de claves.
La configuración de tu cuenta sigue pendiente: usa Check again en la pantalla de configuración. Si el acceso no se activa, escribe a soporte.
429: revisa el campo code. Con RATE_LIMITED, espera los segundos que indica el header Retry-After y vuelve a intentarlo. Con QUOTA_EXHAUSTED o SUBSCRIPTION_INACTIVE, revisa Billing (disponible en inglés).
503: el servicio no está disponible temporalmente. Respeta Retry-After cuando venga y limita la cantidad de reintentos.

URL base

Envía las solicitudes a la API a:

https://api.tweetapi.com/tw-v2/

Autenticación

Incluye tu clave de API en el header X-API-Key:

headers: {
  'X-API-Key': 'YOUR_API_KEY'
}

Antes de llamar a la API

Las respuestas son JSON.
Los límites del plan se aplican por cuenta de TweetAPI, sumando todas sus claves de API: una cuota de unidades de API y un límite de solicitudes por minuto.
Los endpoints que devuelven colecciones usan paginación por cursor cuando está disponible.
Los endpoints de publicación, interacción, perfil, DMs y X Chat pueden necesitar campos de autorización de la cuenta además de tu clave de TweetAPI. Revisa la página de cada endpoint para ver los parámetros exactos que requiere.
Un 429 provocado por los límites de tu plan incluye un code que explica el motivo: RATE_LIMITED (superaste el límite por minuto; el header Retry-After indica cuántos segundos faltan para que se reinicie), QUOTA_EXHAUSTED (se agotaron tu cuota y tu saldo prepago) o SUBSCRIPTION_INACTIVE (tu suscripción venció o no está activa). Reintentar no soluciona los dos últimos. Un 429 sin code es temporal: vuelve a intentarlo con un backoff limitado. Las respuestas no incluyen headers X-RateLimit-*.
Ante un 503, respeta el header Retry-After si viene. Evita reintentar una y otra vez si el error continúa. Antes de repetir una acción cuyo resultado no está claro, comprueba si ya se completó.

SDKs de TweetAPI

Los SDKs de Python y Node.js incluyen tipos, reintentos automáticos y paginación. Desde la versión 2.5.0 exponen el campo code como error.code y esperan automáticamente lo que indique Retry-After.

Python

pip install tweetapi

from tweetapi import TweetAPI

client = TweetAPI(api_key="YOUR_API_KEY")
user = client.user.get_by_username(username="elonmusk")
print(user["data"]["followerCount"])

Ver en GitHub

Node.js / TypeScript

npm install tweetapi-node

import TweetAPI from "tweetapi-node";

const client = new TweetAPI({ apiKey: "YOUR_API_KEY" });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data.followerCount);

Ver en GitHub

Recursos para desarrolladores

Especificación OpenAPI (disponible en inglés) para generadores de código y herramientas de API.
Colección completa de Postman (disponible en inglés) con las 83 operaciones documentadas.
Inicio rápido de Postman, de solo lectura (disponible en inglés), con solicitudes de perfil público, búsqueda y detalles de tweets.

Estos recursos están en inglés.

Funciones principales

Obtén perfiles públicos, tweets, seguidores y métricas de interacción
Publica tweets y gestiona me gusta, retweets, guardados y mensajes directos
Busca tweets, usuarios y multimedia con parámetros de consulta documentados
Obtén posts, perfiles y métricas actualizados (disponible en inglés) en el momento en que tu aplicación hace la solicitud (guía en inglés)
Recorre colecciones con cursores
Trabaja con imágenes, videos y GIFs

Endpoints disponibles

Endpoints de usuarios

Obtener un usuario por nombre de usuario
Obtener un usuario por ID
Obtener varios usuarios por ID
Listas de seguidores y seguidos
Tweets y respuestas de un usuario
Información de suscripciones

Endpoints de tweets

Detalles de tweets e hilos de conversación
Citas y retweets
Traducción de tweets
Métricas de interacción

Endpoints de interacción

Crear, responder y eliminar posts
Dar me gusta y guardar tweets
Retuitear y citar tweets
Gestión de listas

Endpoints de listas y comunidades

Detalles y miembros de listas
Información de comunidades
Tweets del timeline

Endpoints de búsqueda

Buscar tweets, usuarios y multimedia
Operadores de búsqueda avanzada
Opciones de filtrado y orden

Límites de los planes

Los planes públicos tienen actualmente estos límites de solicitudes por minuto:

Free: 10 solicitudes por minuto
Pro: 60 solicitudes por minuto
Ultra: 120 solicitudes por minuto
Mega: 180 solicitudes por minuto
Giga: 300 solicitudes por minuto
Tera: 500 solicitudes por minuto

Los planes privados, antiguos o a medida pueden tener otros límites. Si recibes un 429 por el límite por minuto (RATE_LIMITED), espera los segundos de Retry-After y baja la concurrencia. Si agotaste la cuota de unidades de API de tu plan (QUOTA_EXHAUSTED), revisa el uso y las opciones de suscripción en el panel, o llama a GET /tw-v2/account/usage (disponible en inglés) desde tu código. Un reintento rápido no recupera la cuota.

Los precios, el costo en unidades de cada endpoint y las reglas de cobro también se publican en JSON legible por máquinas en /pricing.json (disponible en inglés).

Pago por uso como respaldo

Puedes comprar paquetes de pago por uso (PAYG) de forma manual y única en Billing: 10,000 unidades por $5 USD, 20,000 por $10 USD, 40,000 por $20 USD o 100,000 por $50 USD. Las recargas no se renuevan automáticamente. TweetAPI usa primero la cuota disponible de tu plan gratuito o de tu suscripción, y después usa automáticamente tu saldo PAYG vigente. Si cancelas una suscripción, las unidades PAYG vigentes se pueden seguir usando. El acceso solo con PAYG está limitado a 60 solicitudes por minuto; si tienes un plan activo con un límite mayor, se mantiene ese límite mayor.

Las unidades PAYG vencen 365 días después de que se confirme el pago. Cada recarga lleva todo tu saldo a la fecha más tardía entre su vencimiento actual y 365 días después de confirmarse el nuevo pago, siempre que el saldo siga vigente cuando se aplique la recarga. Las unidades vencidas no se pueden recuperar. Si pagaste antes del vencimiento pero la recarga se aplicó tarde, escribe a support@tweetapi.com y corregiremos cualquier error de procesamiento confirmado. Billing y las confirmaciones de pago muestran el vencimiento resultante en UTC.

Las unidades se cobran por cada llamada medida a la API, no por cada tweet devuelto. La mayoría de las llamadas cuestan 1 unidad; /tw-v2/xchat/send cuesta 10 y /tw-v2/auth/login cuesta 50. Se cobran las respuestas con estado HTTP 200–499, excepto 400, 401, 403, 409, 422 y 429, así que los resultados vacíos, las solicitudes de paginación, los reintentos y las solicitudes repetidas usan unidades cada una. Un 404 devuelto porque ningún endpoint coincide con la ruta o el método no se cobra.

Consultar tu saldo con GET /tw-v2/account/usage (disponible en inglés) es gratis; solo cuenta para tu límite de solicitudes por minuto.

Los reembolsos retiran unidades de forma proporcional, redondeando hacia arriba a unidades enteras. Una disputa de pago retira todas las unidades de la compra relacionada, menos las que ya se hayan retirado por reembolsos. Un saldo negativo bloquea el PAYG, pero no una suscripción que siga siendo válida. Las recargas cubren primero el saldo negativo y luego suman unidades disponibles. Escribe a support@tweetapi.com si hay descuentos incorrectos, unidades que no llegaron o disputas de pago; no hace falta comprar más unidades para pedir una solución. Consulta los términos y la información sobre reembolsos (disponible en inglés) (en inglés). Esto no limita los derechos que te otorgue la ley.

Manejo de errores

TweetAPI usa códigos de estado HTTP estándar para indicar si una solicitud tuvo éxito o falló.

Códigos de error comunes

400s Errors

400Bad Request - Invalid parameters

401Unauthorized - Invalid API key

404Not Found - Resource doesn't exist

429RATE_LIMITEDToo Many Requests - Per-minute limit

429QUOTA_EXHAUSTEDToo Many Requests - Allowance used up

429SUBSCRIPTION_INACTIVEToo Many Requests - Subscription inactive

500s Errors

500Internal Server Error

Formato de las respuestas de error

Todos los errores siguen el mismo formato:

{
  "statusCode": 400,
  "message": "Invalid username parameter"
}

Algunos errores incluyen también un campo code con un motivo estable que puedes revisar en tu código:

{
  "statusCode": 429,
  "message": "Rate limit quota exceeded - 60 requests per minute allowed",
  "code": "RATE_LIMITED"
}

Los códigos actuales son RATE_LIMITED, QUOTA_EXHAUSTED y SUBSCRIPTION_INACTIVE en un 429; ACCOUNT_SUSPENDED y ACCOUNT_LOCKED cuando la cuenta de X ya no se puede usar; PROXY_ERROR y PROXY_TIMEOUT cuando falla tu proxy; y los resultados de inicio de sesión que se listan en la página de login (disponible en inglés). Los errores sin un motivo no tienen campo code. Podemos agregar códigos nuevos, así que trata un código desconocido como un error sin code.

Buenas prácticas

Revisa el código de estado de la respuesta y, si viene, el campo code
Registra las respuestas de error para depurar
Usa un backoff exponencial limitado para los reintentos, y espera lo que indique Retry-After cuando venga
No reintentes QUOTA_EXHAUSTED ni SUBSCRIPTION_INACTIVE; revisa Billing (disponible en inglés)

Buenas prácticas de seguridad

Nunca compartas tu clave de API en público ni la subas a un control de versiones
Rota tus claves con regularidad
Usa variables de entorno para guardar las claves de API en tus aplicaciones
Revisa el uso en tu panel para detectar actividad inusual

Soporte

Si necesitas ayuda, escribe a support@tweetapi.com o contacta a @tweetapi en Telegram.

Documentación lista para IA