Migrar desde la API de Twitter/X: guía de endpoints y código

Conclusión clave: Migrar de la API oficial de Twitter/X a una API REST de terceros implica cuatro cambios: reemplazar OAuth por un único encabezado de clave API, cambiar la URL base y remapear las rutas de los endpoints, aplanar el parseo de respuestas y cambiar la paginación a un solo campo de cursor. Una migración del flujo de lectura suele tomar de uno a tres días.

Por Sorsa Editorial · Actualizado el 4 de julio de 2026: agregada la opción de arranque gratuito (100 solicitudes gratis, sin tarjeta), movido el precio a una base por unidad de cada 1,000 y re-verificado el mapeo de endpoints contra la cobertura v3 vigente de Sorsa de 40 endpoints.

Este es el recorrido técnico para los equipos que ya decidieron irse y necesitan la migración real: autenticación, mapeo de endpoints, parseo de respuestas, paginación, métodos HTTP y código funcional. Usamos Sorsa API, una API alternativa de Twitter/X que construimos y operamos, como destino de migración a lo largo del texto, porque el mapeo desde los endpoints oficiales v2 es uno de los más limpios disponibles. Reemplazar OAuth por un encabezado ApiKey, el cobro de tarifa plana por solicitud donde una sola llamada por lotes devuelve hasta 100 tweets o perfiles, 20 solicitudes por segundo en todos los planes y sin aprobación de cuenta de desarrollador que esperar son las razones prácticas por las que una migración del flujo de lectura aterriza en días y no en semanas. Las lecturas salen desde $0.02 por cada 1,000 tweets y desde $0.01 por cada 1,000 perfiles, y 100 solicitudes gratis (sin tarjeta, por única vez) cubren una pasada completa de prueba con diff en paralelo antes de comprometerte. Si todavía estás eligiendo proveedor, empieza con nuestra comparación de alternativas a la API de Twitter/X; esta guía asume que la decisión ya está tomada.

Hemos corrido esta migración para equipos desde 2022, a lo largo de más de 5 mil millones de solicitudes procesadas, así que los pasos de abajo siguen una lista de verificación fija en lugar de un recorrido. Los principios se transfieren a cualquier proveedor REST de solo lectura; los nombres de endpoints, los campos de respuesta y el código son específicos de Sorsa.

Contenido

• ¿Qué implica migrar desde la API de Twitter/X?
• Paso 1: reemplaza OAuth por una clave API
• Paso 2: cambia la URL base y remapea los endpoints
• Paso 3: aplana el parseo de respuestas y remapea los campos
• Paso 4: cambia la paginación a un cursor
• Paso 5: cambia GET a POST donde haga falta
• Paso 6: migra el código
• Paso 7: conserva tus consultas de búsqueda y maneja los errores
• Lista de verificación de migración
• En la práctica: la migración de archivo de un grupo académico
• Preguntas frecuentes
• Cómo verificamos esta guía
• Cómo empezar

¿Qué implica migrar desde la API de Twitter/X? {#what-does-migrating-from-the-twitterx-api-involve}

Migrar de la API oficial de Twitter/X a una API REST de tarifa plana es, más que nada, una resta: quitas OAuth, borras las cadenas de selección de campos, descartas los sobres de respuesta y remapeas un puñado de rutas de endpoints. El trabajo central toca la autenticación, las rutas de los endpoints, el parseo de respuestas y la paginación, y un código de flujo de lectura moderado se mueve en uno a tres días.

Aquí está el conjunto completo de cambios de un vistazo, antes del detalle paso a paso:

• Reemplaza Authorization: Bearer ... por un encabezado ApiKey.
• Cambia la URL base de https://api.x.com/2 a https://api.sorsa.io/v3.
• Remapea las rutas de los endpoints (tablas en el Paso 2).
• Cambia los endpoints de tweets y búsqueda de GET a POST (Paso 5).
• Borra tweet.fields, user.fields y expansions: cada campo se devuelve por defecto.
• Aplana los parsers: quita los sobres data, includes y meta.
• Renombra campos: name a display_name, text a full_text, las métricas suben al nivel superior.
• Reemplaza pagination_token y next_token por next_cursor.
• Simplifica el manejo de errores: los errores regresan como un único campo de mensaje.

La tabla de abajo mapea las diferencias relevantes para la migración. Es la única comparación que importa aquí, porque decide cuánto de tu código cambia.

Cada línea es una simplificación salvo una: la API oficial puede escribir en X, y una API de lectura de tarifa plana no. Si publicas, envías DMs o corres anuncios, eso se queda en la API oficial. Para leer datos públicos, el cambio quita OAuth, la capa de selección de campos y las ventanas de tasa por endpoint, que es la mayor parte de la migración.

Paso 1: reemplaza OAuth por una clave API {#step-1-replace-oauth-with-an-api-key}

La autenticación es el cambio que quita más código. La API oficial usa bearer tokens de OAuth 2.0 para solicitudes de solo app y OAuth 1.0a (consumer keys, access tokens, firmas HMAC por solicitud) para cualquier cosa que necesite un contexto de usuario. Un proveedor de tarifa plana reemplaza todo eso con una clave en un encabezado.

Antes, en la API oficial:

curl -X GET "https://api.x.com/2/users/by/username/elonmusk" \
  -H "Authorization: Bearer AAAAAAAAAAAAAAAAAAAA..."

Después:

curl -X GET "https://api.sorsa.io/v3/info?username=elonmusk" \
  -H "ApiKey: YOUR_API_KEY"

No hay refresco de token, ni generación de firma, ni URL de callback. Genera una clave una vez, guárdala en una variable de entorno, y cada solicitud lleva el mismo encabezado ApiKey. La referencia completa está en la documentación de autenticación.

Paso 2: cambia la URL base y remapea los endpoints {#step-2-swap-the-base-url-and-remap-endpoints}

Cada ruta oficial v2 mapea a una ruta nueva. La mayoría de las llamadas cambian solo su URL y, para los endpoints de tweets, su método HTTP.

La URL base se convierte en https://api.sorsa.io/v3. Los usuarios mapean así:

GET /info-batch admite hasta 100 nombres de usuario o IDs por llamada. GET /followers y GET /follows devuelven hasta 200 perfiles completos por página, donde el endpoint oficial devuelve IDs que luego rehidratas con una segunda llamada.

Tweets:

POST /tweet-info-bulk devuelve hasta 100 tweets en una solicitud, donde iterar /tweet-info costaría 100. POST /user-tweets no tiene techo de 3,200 tweets: pagina con next_cursor hasta el primer post de la cuenta. El campo del cuerpo tweet_link acepta una URL completa o solo el ID numérico. Para patrones que recortan el número de solicitudes, consulta la guía de optimización del uso de la API.

Búsqueda:

POST /search-tweets cubre la búsqueda histórica en el mismo endpoint, y POST /mentions agrega filtros de engagement que la API oficial no expone: min_likes, min_replies, min_retweets, since_date y until_date.

Las listas, comunidades, verificación y analítica también mapean, y varias no tienen equivalente en la API oficial. Las listas usan GET /list-members, GET /list-followers y GET /list-tweets. Las comunidades, que la API oficial no expone en absoluto, usan POST /community-members, POST /community-tweets y POST /community-search-tweets. Las comprobaciones de verificación de una sola llamada (POST /check-follow, GET /check-comment, POST /check-quoted, POST /check-retweet, POST /check-community-member) responden una pregunta de sí/no que de otra forma requeriría recorrer listas completas de seguidores o retweeters. La tabla completa ruta por ruta vive en la referencia de mapeo de endpoints.

Paso 3: aplana el parseo de respuestas y remapea los campos {#step-3-flatten-response-parsing-and-remap-fields}

Este paso toca más código que ningún otro después de la autenticación. La API oficial divide una respuesta en data, includes y meta. Un proveedor de tarifa plana devuelve un objeto plano con el autor incrustado dentro de cada tweet, así que la lógica de unir el usuario desaparece.

Un perfil de usuario, antes:

{
  "data": {
    "id": "44196397",
    "name": "Elon Musk",
    "username": "elonmusk",
    "public_metrics": {
      "followers_count": 100000000,
      "following_count": 500,
      "tweet_count": 30000
    }
  }
}

Después:

{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "followers_count": 100000000,
  "followings_count": 500,
  "tweets_count": 30000,
  "verified": false,
  "created_at": "2009-06-02T20:12:29Z"
}

Los renombres de campos son pequeños pero fáciles de pasar por alto en las pruebas. Mapéalos una vez y el resto sigue:

Una inconsistencia a notar para que no te cueste tiempo de depuración: los likes y los follows se pluralizan (likes_count, followings_count) mientras que retweet_count, reply_count y quote_count se quedan en singular. El perfil del autor vive bajo user en cada respuesta de tweet, así que la tabla de búsqueda includes.users que mantenías en la API oficial se puede borrar de plano.

Paso 4: cambia la paginación a un cursor {#step-4-switch-pagination-to-a-cursor}

La paginación se colapsa a un solo campo. La API oficial usa pagination_token en la consulta y devuelve meta.next_token; un proveedor de tarifa plana usa next_cursor en el nivel superior de la respuesta.

Para endpoints GET, pasa next_cursor como parámetro de consulta. Para endpoints POST, inclúyelo en el cuerpo JSON:

curl -X POST "https://api.sorsa.io/v3/search-tweets" \
  -H "ApiKey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "from:elonmusk", "next_cursor": "ABC123" }'

La respuesta es plana, y un next_cursor ausente o null significa que llegaste a la última página:

{ "tweets": [], "next_cursor": "XYZ789" }

El patrón completo, incluyendo la paginación de listas de seguidores, está en la documentación de paginación por cursor.

Paso 5: cambia GET a POST donde haga falta {#step-5-switch-get-to-post-where-required}

Este es el cambio que los equipos olvidan y luego depuran por diez minutos. En la API oficial, las lecturas de tweets y búsqueda son GET. En una API REST de tarifa plana, cualquier cosa que tome un identificador de tweet o una consulta de búsqueda se vuelve POST, mientras que cualquier cosa que tome un identificador de usuario o un ID de lista se queda en GET.

La regla de oro: un identificador de tweet o una consulta de búsqueda significan POST; un identificador de usuario o un ID de lista significan GET.

Paso 6: migra el código {#step-6-migrate-the-code}

Siguen tres migraciones representativas, cada una en curl, Python y JavaScript. Estos son los patrones que repites a lo largo de un código de flujo de lectura.

Obtener un perfil de usuario

Antes:

import requests

r = requests.get(
    "https://api.x.com/2/users/by/username/elonmusk",
    params={"user.fields": "public_metrics,verified,created_at"},
    headers={"Authorization": f"Bearer {BEARER_TOKEN}"},
)
user = r.json()["data"]
followers = user["public_metrics"]["followers_count"]
name = user["name"]

Después:

import requests

r = requests.get(
    "https://api.sorsa.io/v3/info",
    params={"username": "elonmusk"},
    headers={"ApiKey": API_KEY},
)
user = r.json()
followers = user["followers_count"]
name = user["display_name"]

La cadena de selección de campos desaparece y las métricas están en el nivel superior.

Buscar tweets

Antes, unir el autor es obligatorio:

const params = new URLSearchParams({
  query: "from:elonmusk since:2024-01-01",
  "tweet.fields": "created_at,public_metrics",
  expansions: "author_id",
  "user.fields": "username,name",
});
const res = await fetch(`https://api.x.com/2/tweets/search/recent?${params}`, {
  headers: { Authorization: `Bearer ${BEARER_TOKEN}` },
});
const data = await res.json();
const users = Object.fromEntries((data.includes?.users || []).map(u => [u.id, u]));
for (const t of data.data || []) {
  console.log(t.text, "by", users[t.author_id].username);
}

Después, cada tweet ya lleva su autor:

const res = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: { ApiKey: API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "from:elonmusk since:2024-01-01" }),
});
const data = await res.json();
for (const t of data.tweets) {
  console.log(t.full_text, "by", t.user.username);
}

La tabla de unión de usuarios desaparece porque el autor está incrustado en cada tweet.

Paginar cada seguidor

def fetch_all_followers(user_id, api_key):
    url = "https://api.sorsa.io/v3/followers"
    headers = {"ApiKey": api_key}
    followers, next_cursor = [], None
    while True:
        params = {"user_id": user_id}
        if next_cursor:
            params["next_cursor"] = next_cursor
        data = requests.get(url, headers=headers, params=params).json()
        followers.extend(data.get("users", []))
        next_cursor = data.get("next_cursor")
        if not next_cursor:
            break
    return followers

Cada página devuelve hasta 200 perfiles completamente hidratados, así que una extracción de grafo de seguidores que necesitaba una llamada de IDs más una llamada de rehidratación en la API oficial se convierte en una sola pasada. Para detalle específico por lenguaje, nuestra guía de la API de Twitter con Python cubre el flujo de lectura completo.

Paso 7: conserva tus consultas de búsqueda y maneja los errores {#step-7-keep-your-search-queries-and-handle-errors}

Tus consultas de búsqueda se transfieren sin cambios. Un proveedor de tarifa plana que admite los mismos operadores de la búsqueda avanzada de Twitter lee from:, to:, since:, until:, frases entre comillas, hashtags, OR y -is:retweet exactamente como lo hace el endpoint oficial de búsqueda reciente, así que las cadenas de consulta existentes no necesitan ediciones.

Copia tus cadenas de consulta existentes; la referencia de operadores de búsqueda avanzada lista el conjunto completo. El endpoint mentions también expone filtros de engagement (min_likes, min_replies, min_retweets, since_date, until_date), así que cualquier lógica de "filtrar por piso de engagement" del lado del cliente que escribiste contra la API oficial puede moverse al lado del servidor.

El manejo de errores también se simplifica. Donde la API oficial devuelve un array de errores estructurado, un proveedor de tarifa plana devuelve un único campo de mensaje con códigos de estado estándar: 400, 401, 403, 404, 429 y 500. Para un 429, la política es esperar un segundo y reintentar, porque el límite es fijo, de 20 solicitudes por segundo en cada endpoint y plan, sin ventana por endpoint que rastrear. Un envoltorio de reintento defensivo:

import time, requests

def call_with_retry(method, url, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        r = requests.request(method, url, **kwargs)
        if r.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError(f"failed after {max_retries} retries")

La lista completa de códigos de estado está en la referencia de códigos de error.

Lista de verificación de migración {#migration-checklist}

Usa esto como la lista de trabajo para una migración del flujo de lectura:

1. Reemplaza Authorization: Bearer ... por el encabezado ApiKey en todos lados.
2. Quita la lógica de firma de OAuth 1.0a (consumer keys, access tokens, firmas).
3. Actualiza la URL base a https://api.sorsa.io/v3.
4. Remapea cada ruta de endpoint usando las tablas del Paso 2.
5. Cambia GET a POST para los endpoints de tweets, búsqueda, comentarios, citas y retweeters.
6. Borra tweet.fields, user.fields y expansions.
7. Quita el desempaquetado de data / includes / meta.
8. Renombra los campos en tus modelos (name, text, el bloque public_metrics).
9. Reemplaza pagination_token y next_token por next_cursor.
10. Actualiza el manejo de errores para la forma de un único campo de mensaje.
11. Fija la lógica de límite de tasa a un límite fijo de 20 solicitudes por segundo, sin ventanas por endpoint.
12. Prueba los endpoints críticos en el API Playground antes de desplegar.
13. Rastrea el consumo de cuota con el endpoint key-usage-info (revisa la referencia de uso de clave).
14. Conserva la clave oficial si además escribes en X; solo el flujo de lectura se mueve.

En la práctica: la migración de archivo de un grupo académico {#in-practice-an-academic-groups-archival-migration}

Un grupo de investigación académica llegó a nosotros a mediados de 2025 corriendo un pipeline de recolección de tweets para un estudio longitudinal en la API oficial. Dos problemas los habían estancado: el endpoint de cronología de usuario topaba en los 3,200 tweets más recientes por cuenta, lo que rompía su cobertura histórica, y el endpoint de seguidores devolvía solo IDs que necesitaban una segunda consulta para volverse perfiles usables.

La migración del flujo de lectura tomó unos dos días para un investigador. POST /user-tweets eliminó el techo de 3,200 tweets, paginando con next_cursor hacia el primer post de cada cuenta, así que el hueco de archivo se cerró. La extracción de seguidores se colapsó a una sola pasada porque GET /followers devuelve hasta 200 perfiles completos por página, lo que aproximadamente redujo a la mitad el número de solicitudes de esa parte del trabajo. La única fricción real fueron los renombres de campos (name a display_name, text a full_text y el pluralizado likes_count), detectados en unas pocas horas de pruebas en lugar de en el diseño. Los números exactos varían por carga; la forma de la migración no.

Preguntas frecuentes {#frequently-asked-questions}

¿Se puede migrar de la API de Twitter/X un endpoint a la vez?

Sí, y una migración gradual suele ser la opción más segura. Pon una capa de abstracción delgada delante de tus llamadas de datos, apunta un endpoint al nuevo proveedor, valida su salida contra la API oficial por unos días y luego mueve el siguiente. El código de la aplicación nunca tiene que cambiar en una gran reescritura, y puedes revertir un endpoint de forma independiente si algo se ve mal.

¿Cómo probar una migración de la API de Twitter/X sin romper producción?

Corre las dos APIs en paralelo y compara la salida parseada antes de cambiar. La opción más ligera es el playground del navegador, que envía solicitudes sin código de integración. Una opción más fuerte es un script lado a lado que llama a ambas APIs y compara resultados, y la más exhaustiva es un feature flag que enruta un porcentaje del tráfico al nuevo proveedor para que puedas revertir al instante.

¿Las consultas de búsqueda avanzada de Twitter siguen funcionando tras migrar?

Sí, si el proveedor admite los mismos operadores de búsqueda avanzada. Los endpoints de búsqueda de tweets y menciones de Sorsa leen from:, to:, since:, until:, frases entre comillas, hashtags, OR y -is:retweet exactamente como lo hace el endpoint oficial de búsqueda reciente, así que las cadenas de consulta existentes se transfieren sin ediciones. El endpoint de menciones agrega filtros de engagement, como min_likes y min_retweets, que la API oficial no expone.

¿Cómo manejar los límites de tasa y los errores tras migrar?

El manejo de errores se vuelve más simple. Sorsa devuelve cada error como un único campo de mensaje en lugar del array de errores estructurado de la API oficial, con códigos de estado estándar (400, 401, 403, 404, 429 y 500). El límite de tasa es fijo, de 20 solicitudes por segundo en todos los planes, sin ventanas de 15 minutos por endpoint. Ante un 429, espera un segundo y reintenta; no hay encabezado de reinicio que rastrear.

¿Migrar elimina el límite de 3,200 tweets de la cronología?

Sí. El endpoint oficial v2 de cronología de usuario topa en los 3,200 tweets más recientes por cuenta. El POST /user-tweets de Sorsa no tiene ese tope: pagina con next_cursor hasta que la respuesta deje de devolver uno, y llegas al primer post de la cuenta. Para trabajo de archivo, historial de sentimiento y datos de entrenamiento, esta suele ser la razón de que la migración ocurra siquiera.

¿Cómo seguir escribiendo en X si la alternativa es de solo lectura?

Conservas la API oficial de X para las acciones de escritura y migras solo el flujo de lectura. Publicar, responder, DMs, likes, follows y anuncios se quedan todos en la API oficial, que es el único sistema que puede actuar en nombre de un usuario. La mayoría de los equipos termina con un esquema híbrido: un presupuesto pequeño de API oficial para escrituras y una API de lectura de tarifa plana para extracciones de datos de alto volumen. Sorsa es de solo lectura por diseño, lo que también elimina toda una clase de riesgo de permisos de escritura y de suspensión de cuenta.

Cómo verificamos esta guía {#how-we-verified-this-guide}

Este recorrido se apoya en nuestro trabajo directo operando una API alternativa de X desde 2022 y en migraciones del flujo de lectura que hemos corrido para equipos que dejan la plataforma oficial. Las rutas de endpoints, los nombres de parámetros, los campos de respuesta y el encabezado ApiKey se verificaron contra la documentación de Sorsa API en vivo, y el modelo de autenticación de la API oficial de X, sus sobres de respuesta y sus tarifas de pago por uso se revisaron contra la documentación de desarrolladores y la página de precios de X, reflejando el cambio del 20 de abril de 2026. Para el lado de costo de la decisión, consulta nuestro desglose de precios de la API de X vigente. Cada ejemplo de código se escribió para correr tal como se muestra. Verificado el 13 de junio de 2026.

Revisado por Keksich, fundador de Sorsa, especialista en marketing e investigador de la API de X.

Cómo empezar {#getting-started}

Si tu pipeline lee tweets, perfiles, seguidores o resultados de búsqueda, la forma más rápida de dimensionar una migración es correr unas cuantas llamadas y comparar la forma de la respuesta contra tu parser actual. El inicio rápido de Sorsa API te lleva a una primera solicitud en minutos detrás de una clave, y la documentación de datos históricos muestra cómo los endpoints de cronología llegan hasta 2006 sin el tope de 3,200 tweets. Las primeras 100 solicitudes son gratis, por única vez, sin tarjeta y sin vencimiento, lo que cubre una prueba completa de diff en paralelo antes de pagar. Después, las lecturas salen desde $0.02 por cada 1,000 tweets y desde $0.01 por cada 1,000 perfiles, con planes desde $49 al mes por 10,000 solicitudes, las mismas 20 solicitudes por segundo en cada nivel, y sin aprobación de cuenta de desarrollador entre tú y tu primera llamada. Apunta un endpoint hacia ella detrás de un flag, compara la salida y migra el resto.