API de Twitter en PHP: obtén datos de X con cURL, Guzzle y Laravel

#¿Hay un SDK oficial de la API de X para PHP?

No. X publica SDKs oficiales solo para Python y TypeScript, y su página de herramientas lista tres clientes de PHP de la comunidad que X no mantiene: twitter-api-v2-php, bird-elephant y TwitterOAuth (herramientas y librerías de X (se abre en una pestaña nueva)). TwitterOAuth es el más instalado de los tres, con unas 240 mil instalaciones de Composer al mes. Su versión 9.0.0, publicada el 1 de noviembre de 2026, solo habla con la API v2 y exige PHP 8.3 o posterior.

Los tres son clientes de la API oficial de X, así que cada llamada que hacen necesita una cuenta de desarrollador, las claves de una app y créditos prepagados. Los desarrolladores nuevos no tienen nivel gratuito, y X cobra cada objeto que devuelve una respuesta: $0.005 por post y $0.010 por usuario, hasta 3 millones de lecturas de posts al mes (tabla de precios de X (se abre en una pestaña nueva)). A partir del 22 de noviembre de 2026, los autores y los medios que llegan mediante expansiones se cobran a las mismas tarifas (aviso de X del 23 de octubre (se abre en una pestaña nueva)), así que la búsqueda habitual con TwitterOAuth paga por cada autor que adjunta:

use Abraham\TwitterOAuth\TwitterOAuth;

$x = new TwitterOAuth($apiKey, $apiSecret, null, $bearerToken);
$posts = $x->get('tweets/search/recent', [
    'query' => 'laravel lang:en',
    'max_results' => 100,
    'expansions' => 'author_id',
]);
// 100 posts: $0.50. From Nov 22, 2026, with authors: up to $1.50

Las respuestas viejas apuntan más atrás. El primer resultado de Google para esta búsqueda es J7mbo/twitter-api-php, un wrapper de llamadas v1.1 cuyo repositorio de GitHub está archivado y cuyo último cambio fue en abril de 2020. Todas las tarifas, topes y fechas vigentes de la vía oficial están en precios de la API de X.

Lo que exige la vía oficial antes de la primera llamada

• Una cuenta de desarrollador en console.x.com, abierta con una cuenta de X y con el Acuerdo para Desarrolladores de X aceptado.
• Una app con su clave de API, su secreto de API y su bearer token, que X muestra una sola vez (guía de acceso de X (se abre en una pestaña nueva)).
• Créditos comprados por adelantado y gastados por cada post y cada usuario que se devuelve.
• Tokens de usuario de OAuth 1.0a, un token de acceso y su secreto, para todo lo que publique; el constructor de cuatro argumentos de TwitterOAuth los recibe.

Nada de eso hace falta para leer posts y perfiles públicos. La sección siguiente lo hace con una sola clave y la extensión cURL que la mayoría de las compilaciones de PHP ya incluyen.

#Obtén tweets en PHP con una sola clave de API

Para leer datos de X desde PHP, usa Sorsa API, una API y scraper de Twitter (X): un solo encabezado ApiKey en lugar de OAuth, 20 solicitudes por segundo en todos los planes, también en las cuentas gratuitas, y timelines y búsqueda desde $0.07 por 1,000 tweets. Cada respuesta es JSON simple que json_decode convierte en arreglos, con el perfil completo del autor dentro de cada tweet. Nunca pide tu inicio de sesión de X, así que tu cuenta de X no corre ningún riesgo.

1. Obtén una clave. Regístrate y copia tu clave de API desde el panel. Las primeras 100 solicitudes son gratis, no piden tarjeta y nunca vencen.

2. Mantén la clave fuera del código. Defínela como variable de entorno, o en .env para Laravel, y llama a la API solo desde PHP del lado del servidor: una clave en JavaScript del navegador la ve cualquier visitante.

   export SORSA_API_KEY="your_key"  # PowerShell: $env:SORSA_API_KEY="your_key"
   

3. Obtén los últimos tweets de una cuenta. Envía el nombre de usuario a POST /user-tweets (se abre en una pestaña nueva) con la clave en el encabezado ApiKey. Pruébalo primero desde la terminal:

   curl -X POST "https://api.sorsa.io/v3/user-tweets" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"username": "php_release_notes"}'
   

4. Llámalo desde PHP. El cURL simple no necesita ningún paquete de Composer. Con Guzzle, termina base_uri con una barra y empieza la ruta sin ella, o se pierde la parte /v3.

   <?php
   $key = getenv('SORSA_API_KEY') ?: 'YOUR_API_KEY';
   
   $ch = curl_init('https://api.sorsa.io/v3/user-tweets');
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_HTTPHEADER => [
           'ApiKey: ' . $key,
           'Content-Type: application/json',
       ],
       CURLOPT_POSTFIELDS => json_encode(['username' => 'php_release_notes']),
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_TIMEOUT => 30,
   ]);
   $body = curl_exec($ch);
   $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
   
   $data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
   if ($status !== 200) {
       exit("HTTP $status: {$data['message']}\n");
   }
   foreach ($data['tweets'] as $tweet) {
       echo $tweet['created_at'], ' ', mb_substr($tweet['full_text'], 0, 60), "\n";
   }
   

   <?php
   require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle
   
   $http = new GuzzleHttp\Client([
       'base_uri' => 'https://api.sorsa.io/v3/',
       'headers' => ['ApiKey' => getenv('SORSA_API_KEY') ?: 'YOUR_API_KEY'],
       'timeout' => 30,
   ]);
   
   $res = $http->post('user-tweets', [
       'json' => ['username' => 'php_release_notes'],
   ]);
   $data = json_decode($res->getBody(), true, flags: JSON_THROW_ON_ERROR);
   
   foreach ($data['tweets'] as $tweet) {
       echo $tweet['created_at'], ' ', mb_substr($tweet['full_text'], 0, 60), "\n";
   }
   

5. Lee la página. Cada respuesta trae hasta 20 tweets y un next_cursor mientras quedan más. Los valores de abajo son datos de demostración con la forma documentada.

   {
     "tweets": [
       {
         "id": "1985432176540981234",
         "full_text": "PHP 8.5.12 is out with two security fixes. Upgrade today.",
         "created_at": "2026-11-01T18:42:07Z",
         "lang": "en",
         "likes_count": 42,
         "retweet_count": 7,
         "reply_count": 3,
         "quote_count": 1,
         "view_count": 3810,
         "bookmark_count": 5,
         "is_reply": false,
         "user": {
           "id": "1592041833471827968",
           "username": "php_release_notes",
           "display_name": "PHP Release Notes",
           "followers_count": 1840,
           "verified": false
         }
       }
     ],
     "next_cursor": "DAABCgABF7Y8kQ3wAAA"
   }
   

   Ver respuesta completa

Cada tweet llega con sus conteos y su autor, así que un script de PHP no define expansiones ni listas de campos. Estos son los campos que lee la mayoría de los scripts:

• id

  Qué contiene

  El ID del tweet: 19 dígitos, enviado como string

• full_text

  Qué contiene

  El texto completo del post

• created_at

  Qué contiene

  La hora en ISO 8601, UTC, lista para new DateTimeImmutable()

• likes_count, retweet_count, reply_count, quote_count

  Qué contiene

  Conteos de interacción

• view_count, bookmark_count

  Qué contiene

  Vistas y guardados

• user

  Qué contiene

  El perfil del autor: 19 campos como username y followers_count

• quoted_status, retweeted_status

  Qué contiene

  El tweet citado o republicado, con la misma forma

#Una función de solicitud con reintentos

Envía cada llamada por una sola función que reintente solo lo que un reintento puede arreglar. Un 429 significa que más de 20 solicitudes empezaron dentro de un mismo segundo con tu clave, y un 5xx o una conexión cortada es una falla temporal; ambos se resuelven solos. sorsa() los reintenta hasta cuatro veces, esperando 1, 2, 4 y 8 segundos, y envía los parámetros GET como claves repetidas, la forma que leen los endpoints por lotes de más abajo. El resto de esta guía se apoya en ella.

<?php
const SORSA_API = 'https://api.sorsa.io/v3';
const RETRY = [429, 500, 502, 503, 504];

/** Build a query string; a list becomes a repeated key: a=1&a=2. */
function query(array $params): string
{
    $parts = [];
    foreach ($params as $name => $value) {
        foreach ((array) $value as $one) {
            $parts[] = rawurlencode($name) . '=' . rawurlencode($one);
        }
    }
    return implode('&', $parts);
}

/** Send one request; retry 429, 5xx and network errors up to 4 times. */
function sorsa(string $method, string $path, array $params = []): array
{
    $url = SORSA_API . $path;
    $headers = ['ApiKey: ' . (getenv('SORSA_API_KEY') ?: 'YOUR_API_KEY')];
    $options = [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30];

    if ($method === 'GET') {
        $url .= $params ? '?' . query($params) : '';
    } else {
        $headers[] = 'Content-Type: application/json';
        $options[CURLOPT_POSTFIELDS] = json_encode($params);
    }
    $options[CURLOPT_HTTPHEADER] = $headers;

    for ($attempt = 0; ; $attempt++) {
        $ch = curl_init($url);
        curl_setopt_array($ch, $options);
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 0: no answer
        $again = in_array($status, [0, ...RETRY], true);
        if (!$again || $attempt === 4) {
            break;
        }
        sleep(2 ** $attempt); // 1, 2, 4, 8 seconds
    }

    if ($raw === false) {
        throw new RuntimeException('Network error: ' . curl_error($ch));
    }
    $data = json_decode($raw, true, flags: JSON_THROW_ON_ERROR);
    if ($status !== 200) {
        throw new RuntimeException("HTTP $status: " . ($data['message'] ?? ''));
    }
    return $data;
}

Un 401 o un 403 nunca merece un reintento: la clave es incorrecta o falta, o sus solicitudes se agotaron, y el campo message dice cuál es el caso. Las solicitudes fallidas nunca se cobran, así que un reintento no cuesta nada, y todos los endpoints de Sorsa API solo leen, de modo que repetir un POST no puede crear nada dos veces. La función corre en PHP 8.0 y posteriores. Omite curl_close(), que no hace nada desde PHP 8.0, porque los handles de cURL ahora se cierran solos.

#Recorre los resultados con next_cursor

Un cursor es una clave opaca hacia la página siguiente de resultados: devuelve next_cursor sin cambios y detente cuando una respuesta llegue sin él. Los timelines y POST /search-tweets (se abre en una pestaña nueva) devuelven hasta 20 tweets por página, y una página puede traer menos mientras quedan más, así que la cantidad de elementos nunca te dice que llegó el final. Un generador entrega una página a la vez y mantiene la memoria estable sin importar cuánto dure el trabajo.

require 'sorsa.php';

/** Yield pages of a POST endpoint until the cursor runs out. */
function pages(string $path, array $body, int $maxPages = 100): Generator
{
    for ($i = 0; $i < $maxPages; $i++) {
        $page = sorsa('POST', $path, $body);
        yield $page;
        if (empty($page['next_cursor'])) {
            return;
        }
        $body['next_cursor'] = $page['next_cursor'];
    }
}

foreach (pages('/search-tweets', ['query' => 'laravel lang:en']) as $page) {
    foreach ($page['tweets'] as $tweet) {
        echo $tweet['id'], ' @', $tweet['user']['username'], "\n";
    }
}

Mantén sin cambios la consulta y order mientras corre un cursor, y trata $maxPages como un presupuesto: 100 páginas son 100 solicitudes y, como máximo, 2,000 tweets. Los endpoints GET reciben el cursor en la cadena de consulta. GET /followers (se abre en una pestaña nueva) devuelve hasta 200 perfiles por página:

$params = ['username' => 'php_release_notes'];
$followers = [];
do {
    $page = sorsa('GET', '/followers', $params);
    array_push($followers, ...$page['users']);
    $params['next_cursor'] = $page['next_cursor'] ?? null;
} while ($params['next_cursor']);

Dos tareas tienen scripts completos propios: descargar todos los tweets de un usuario retoma un timeline entero desde un cursor guardado, y la guía para exportar seguidores de Twitter escribe listas de seguidores a CSV.

#Obtén 100 tweets o perfiles por solicitud

Cuando ya tienes IDs de tweets o nombres de usuario, envíalos en lotes. POST /tweet-info-bulk (se abre en una pestaña nueva) acepta hasta 100 IDs o enlaces de tweets, y GET /info-batch (se abre en una pestaña nueva) acepta hasta 100 nombres de usuario. Las respuestas por lote no traen cursor: una respuesta contiene el lote completo.

$tweets = [];
foreach (array_chunk($tweetIds, 100) as $batch) {
    $res = sorsa('POST', '/tweet-info-bulk', ['tweet_links' => $batch]);
    array_push($tweets, ...$res['tweets']);
}

$profiles = [];
foreach (array_chunk($usernames, 100) as $batch) {
    $res = sorsa('GET', '/info-batch', ['usernames' => $batch]);
    array_push($profiles, ...$res['users']);
}

Una solicitud cuesta lo mismo sin importar lo que devuelva, así que un lote de 100 tweets cuesta lo que cuesta un tweet: desde $0.014 por 1,000 tweets, más de 250 veces menos que los $5.00 de la API oficial de X. Con las 100 solicitudes gratis obtienes así 10,000 tweets.

Para tener en cuenta

GET /info-batch lee una lista como una clave repetida, usernames=a&usernames=b, la forma que define su referencia OpenAPI. El http_build_query() de PHP escribe en su lugar usernames%5B0%5D=a&usernames%5B1%5D=b, y lo mismo hacen la opción query con arreglos de Guzzle y el Http::get($url, $array) de Laravel, que arman la consulta de la misma manera. Usa la función query() de arriba, o GuzzleHttp\Psr7\Query::build(), que escribe claves repetidas.

#Ejecuta lotes en paralelo a 19 solicitudes por segundo

PHP ejecuta solicitudes en paralelo con curl_multi, y un solo proceso alcanza las 20 solicitudes por segundo por clave de Sorsa API en cuanto el trabajo se divide en solicitudes independientes. Los lotes se dividen sin problema, porque cada uno se sostiene solo. Una cadena de cursor no se puede dividir, ya que cada página necesita el cursor de la anterior, así que corre en paralelo cuentas o ventanas de fechas distintas. parallel() inicia como máximo 19 solicitudes por segundo, una menos que el límite, y devuelve a la fila cualquier 429 o 5xx.

/** POST many bodies side by side, starting at most $rate a second. */
function parallel(string $path, array $bodies, float $rate = 19): array
{
    $multi = curl_multi_init();
    $queue = array_keys($bodies);
    $tries = $results = [];
    $next = microtime(true);
    $running = 0;

    while ($queue || $running) {
        if ($queue && microtime(true) >= $next) {
            $key = array_shift($queue);
            $ch = curl_init(SORSA_API . $path);
            curl_setopt_array($ch, [
                CURLOPT_HTTPHEADER => [
                    'ApiKey: ' . (getenv('SORSA_API_KEY') ?: 'YOUR_API_KEY'),
                    'Content-Type: application/json',
                ],
                CURLOPT_POSTFIELDS => json_encode($bodies[$key]),
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_TIMEOUT => 30,
                CURLOPT_PRIVATE => (string) $key,
            ]);
            curl_multi_add_handle($multi, $ch);
            $next = max($next, microtime(true) - 1 / $rate) + 1 / $rate;
        }
        curl_multi_exec($multi, $running);
        while ($done = curl_multi_info_read($multi)) {
            $ch = $done['handle'];
            $key = curl_getinfo($ch, CURLINFO_PRIVATE);
            $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
            $tries[$key] = ($tries[$key] ?? 0) + 1;
            if (in_array($status, [0, ...RETRY], true) && $tries[$key] < 5) {
                $queue[] = $key; // back in line, it waits its turn
            } else {
                $results[$key] = json_decode(curl_multi_getcontent($ch), true);
            }
            curl_multi_remove_handle($multi, $ch);
        }
        curl_multi_select($multi, 0.01);
    }
    return $results;
}

$bodies = array_map(fn ($batch) => ['tweet_links' => $batch],
    array_chunk($tweetIds, 100));
$tweets = array_merge(...array_column(parallel('/tweet-info-bulk', $bodies),
    'tweets'));

Con 19 inicios por segundo, 100 lotes mueven 10,000 tweets en unos 5 segundos, 1,900 tweets por segundo. Mantén un solo bucle parallel() por clave: dos procesos que lo ejecutan en paralelo inician el doble del límite entre los dos. El Pool de Guzzle parece la herramienta para esto, pero su opción concurrency limita las solicitudes en vuelo, no los inicios por segundo, así que un pool de respuestas rápidas aún puede cruzar las 20 por segundo y apoyarse en los reintentos.

#Laravel: las mismas llamadas con el cliente Http

El cliente Http de Laravel envuelve a Guzzle, así que una app de Laravel no necesita ningún paquete adicional. Una macro define la URL base, la clave y una regla de reintentos que repite solo los 429, las respuestas 5xx y las conexiones cortadas; cada controlador, job o comando de Artisan llama entonces a Http::sorsa().

// config/services.php: 'sorsa' => ['key' => env('SORSA_API_KEY')],
// .env: SORSA_API_KEY=YOUR_API_KEY

// app/Providers/AppServiceProvider.php
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;

// inside the class
public function boot(): void
{
    Http::macro('sorsa', fn () => Http::baseUrl('https://api.sorsa.io/v3')
        ->withHeaders(['ApiKey' => config('services.sorsa.key')])
        ->timeout(30)
        ->retry(5, fn (int $attempt) => 1000 * 2 ** ($attempt - 1),
            fn (Throwable $e) => $e instanceof ConnectionException
                || ($e instanceof RequestException
                    && ($e->response->status() === 429
                        || $e->response->serverError()))));
}

use GuzzleHttp\Psr7\Query;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;

// One request per 5 minutes, however many people open the page
$tweets = Cache::remember('x-feed:php_release_notes', now()->addMinutes(5),
    fn () => Http::sorsa()
        ->post('user-tweets', ['username' => 'php_release_notes'])
        ->json('tweets'));

// Up to 100 profiles in one request, sent as a repeated key
$users = Http::sorsa()
    ->get('info-batch?' . Query::build(['usernames' => $usernames]))
    ->json('users');

retry() espera 1, 2, 4 y 8 segundos entre intentos y lanza una RequestException cuando se agotan los intentos o el estado no vale un reintento, como un 401 o un 403, así que una llamada fallida nunca llega a la caché. Ejecuta los trabajos largos, como miles de solicitudes por lotes, desde un job en cola o un comando de Artisan y no dentro de una solicitud de página.

Un feed en caché gasta solicitudes según el reloj, no según el visitante. El planificador convierte el número de feeds y el tiempo de caché en solicitudes por día y por mes, y en el plan de Sorsa API que las incluye.

#Cuánto cuesta un trabajo en PHP

Sorsa API cobra por solicitud, sin importar lo que devuelva el endpoint: los timelines y la búsqueda cuestan desde $0.07 por 1,000 tweets, los lotes desde $0.014, y las solicitudes fallidas nunca se cobran. La API oficial de X cobra en cambio por objeto: $5.00 por 1,000 posts, y a partir del 22 de noviembre de 2026 hasta $15.00 por 1,000 cuando el código expande el autor de cada post, como hacen la mayoría de las búsquedas con TwitterOAuth.

La tarifa por 1,000 solicitudes va de $4.90 en Starter a $1.40 en Hyperscale, y cada plan la aplica por igual a todos los endpoints. Consultar cuánto te queda no cuesta nada: GET /key-usage-info (se abre en una pestaña nueva) nunca descuenta de tus solicitudes.

$usage = sorsa('GET', '/key-usage-info');
echo $usage['remaining_requests'], ' left until ', $usage['valid_until'], "\n";

#Cómo pasar el código de TwitterOAuth a Sorsa API

La mayoría de las lecturas de TwitterOAuth se corresponden con un endpoint de Sorsa API, y el código deja atrás sus expansiones y listas de campos, porque cada tweet ya trae su autor y sus conteos. La tabla empareja rutas comunes de v2 con sus endpoints; para pasar un código base completo, la guía para migrar desde la API de Twitter/X mapea cada endpoint v2 y cada campo de respuesta.

• get('tweets/search/recent')

  Endpoint de Sorsa API

  POST /search-tweets

  Qué cambia

  Un solo endpoint para la búsqueda reciente y la de archivo, desde 2006

• get("users/$id/tweets")

  Endpoint de Sorsa API

  POST /user-tweets

  Qué cambia

  Basta con un nombre de usuario, y no hay tope de 3,200 posts

• get('tweets') con ids

  Endpoint de Sorsa API

  POST /tweet-info-bulk

  Qué cambia

  100 IDs o enlaces por solicitud

• get('users/by') con usernames

  Endpoint de Sorsa API

  GET /info-batch

  Qué cambia

  100 nombres de usuario por solicitud

• get("users/$id/followers")

  Endpoint de Sorsa API

  GET /followers

  Qué cambia

  200 seguidores por página

• post('tweets')

  Endpoint de Sorsa API

  ninguno

  Qué cambia

  Solo lectura: publica con la API oficial de X

Los nombres de los campos también cambian: text pasa a ser full_text, public_metrics->like_count pasa a ser likes_count, author_id con includes->users pasa a ser el arreglo user, y meta->next_token pasa a ser next_cursor. TwitterOAuth devuelve objetos, mientras que json_decode($body, true) da los arreglos que usa esta guía. El timeline de usuario también llega más allá de los 3,200 posts más recientes, donde se detiene el timeline oficial (se abre en una pestaña nueva).

#Haz hoy tu primera solicitud en PHP

Leer datos de X en PHP necesita la extensión cURL, una clave y cuatro funciones cortas: sorsa() para los reintentos, pages() para los cursores, array_chunk() con los endpoints por lotes para 100 elementos por solicitud, y parallel() para 19 solicitudes por segundo. Empieza con Sorsa API, la API de Twitter creada para leer datos públicos de X a gran escala: 20 tweets por solicitud de timeline o búsqueda desde $0.07 por 1,000, 100 por lote desde $0.014, y 100 solicitudes gratis que no piden tarjeta y nunca vencen. Las mismas llamadas en otros lenguajes están en las guías de la API de Twitter en Python y la API de Twitter en Node.js.

#Preguntas frecuentes