Formato de respuesta: esquemas de User y Tweet

Sorsa API devuelve todos los datos en JSON. Esta página describe la estructura de las respuestas, los objetos principales, los tipos de campos y la paginación.

Convenciones

Estas reglas se aplican en toda la API. Los IDs son cadenas. Los IDs de X/Twitter (id, conversation_id_str, in_reply_to_tweet_id y otros) se devuelven como cadenas, no como enteros. X utiliza IDs Snowflake de 64 bits que superan Number.MAX_SAFE_INTEGER de JavaScript. Las cadenas evitan la pérdida silenciosa de precisión en navegadores, Node.js y lenguajes que representan los números JSON en coma flotante. Las fechas principales son cadenas ISO 8601. Los campos created_at de User y Tweet utilizan valores como 2026-03-06T12:00:00Z. Consulta el esquema para otras fechas; no supongas que las verificaciones o relaciones utilizan el mismo formato. Los booleanos son estrictos. Indicadores como verified, is_reply, protected y can_dm son true o false, nunca 0/1 ni "true"/"false". Campos nulos y ausentes. Distingue un valor ausente de un cero medido o de false. Al recorrer arrays opcionales como bio_urls y pinned_tweet_ids, normaliza los valores nulos o ausentes a listas vacías: user.get("bio_urls") or [] en Python o user.bio_urls ?? [] en JavaScript. Los modelos compactos omiten campos del objeto User completo.

Estructuras contenedoras de respuesta

Los endpoints de un único objeto, como /info y /tweet-info, lo devuelven directamente en el nivel superior. Los endpoints de listas utilizan estas estructuras. UsersResponse: utilizada por /followers, /follows, /verified-followers, /retweeters, /search-users, /list-members y /list-followers. /community-members utiliza las mismas claves, pero devuelve objetos compactos CommunityUser.

{
  "users": [ ... ],
  "next_cursor": "abc123"
}

TweetsResponse: utilizada por /user-tweets, /comments, /quotes, /search-tweets, /mentions, /list-tweets, /community-tweets y /community-search-tweets.

{
  "tweets": [ ... ],
  "next_cursor": "abc123"
}

FollowersResponse: utilizada por /new-followers-7d, /new-following-7d y /top-following. /top-followers utiliza TopFollowersResponse, con perfiles compactos y un campo score.

{
  "users": [ ... ]
}

FollowersResponse no incluye next_cursor: devuelve todos los resultados en una sola respuesta.

El objeto User

Representa el perfil de una cuenta de X/Twitter. /info lo devuelve directamente; los endpoints de listas lo incluyen como elemento de un array y cada objeto Tweet lo contiene en el campo user.

{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "description": "Mars & Cars, Chips & Dips",
  "location": "Earth",
  "created_at": "2009-06-02T20:12:29Z",
  "followers_count": 236021252,
  "followings_count": 1292,
  "favourites_count": 214650,
  "tweets_count": 98479,
  "media_count": 4374,
  "profile_image_url": "https://pbs.twimg.com/profile_images/.../photo_normal.jpg",
  "profile_background_image_url": "https://pbs.twimg.com/profile_banners/44196397/...",
  "bio_urls": ["https://example.com"],
  "pinned_tweet_ids": ["2028500984977330453"],
  "verified": true,
  "can_dm": false,
  "protected": false,
  "possibly_sensitive": false
}

Campo	Tipo	Descripción
`id`	cadena	ID numérico permanente del usuario (Snowflake)
`username`	cadena	Nombre de usuario actual, sin @
`display_name`	cadena	Nombre público del perfil
`description`	cadena	Biografía de la cuenta
`location`	cadena	Ubicación indicada por el usuario (texto libre)
`created_at`	cadena	Fecha y hora de creación de la cuenta
`followers_count`	entero	Número de seguidores
`followings_count`	entero	Número de cuentas seguidas
`favourites_count`	entero	Total de Me gusta dados por esta cuenta
`tweets_count`	entero	Total de publicaciones
`media_count`	entero	Total de elementos multimedia publicados
`profile_image_url`	cadena	URL de la imagen de perfil
`profile_background_image_url`	cadena	URL de la imagen de portada
`bio_urls`	array de cadenas o null	URL de la biografía
`pinned_tweet_ids`	array de cadenas o null	IDs de las publicaciones fijadas
`verified`	booleano	Estado de verificación (marca azul, dorada o gris)
`can_dm`	booleano	Indica si los mensajes directos están abiertos
`protected`	booleano	Indica si la cuenta es privada
`possibly_sensitive`	booleano	Indica si la cuenta está marcada como sensible

El objeto Follower

Amplía el objeto User con un campo adicional. Lo devuelven /new-followers-7d, /new-following-7d y /top-following. /top-followers devuelve un modelo compacto diferente con score.

Campo adicional	Tipo	Descripción
`followerDate`	cadena	Fecha en que se registró la relación de seguimiento

El objeto Tweet

Contiene el texto completo, los metadatos, las métricas de interacción y las relaciones anidadas de una publicación. /tweet-info lo devuelve directamente; los endpoints de listas lo incluyen como elemento de un array.

{
  "id": "1234567890123456789",
  "full_text": "This is the complete tweet text including mentions and links",
  "created_at": "2026-03-06T12:00:00Z",
  "lang": "en",
  "bookmark_count": 42,
  "likes_count": 1500,
  "quote_count": 23,
  "reply_count": 89,
  "retweet_count": 312,
  "view_count": 250000,
  "conversation_id_str": "1234567890123456789",
  "in_reply_to_tweet_id": null,
  "in_reply_to_username": null,
  "is_reply": false,
  "is_quote_status": false,
  "is_replies_limited": false,
  "entities": [ ... ],
  "user": { ... },
  "quoted_status": null,
  "retweeted_status": null
}

Campos de contenido

Campo	Tipo	Descripción
`id`	cadena	ID único de la publicación (Snowflake)
`full_text`	cadena	Texto completo de la publicación
`created_at`	cadena	Fecha y hora de publicación
`lang`	cadena	Código de idioma detectado, como “en”, “ja” o “es”

Métricas de interacción

Campo	Tipo	Descripción
`likes_count`	entero	Total de Me gusta
`retweet_count`	entero	Total de retuits
`reply_count`	entero	Total de respuestas
`quote_count`	entero	Total de citas
`view_count`	entero	Total de impresiones
`bookmark_count`	entero	Total de veces guardada

Contexto del hilo y de las respuestas

Campo	Tipo	Descripción
`conversation_id_str`	cadena	ID de la publicación inicial del hilo
`in_reply_to_tweet_id`	cadena o null	ID de la publicación a la que responde
`in_reply_to_username`	cadena o null	Nombre del usuario al que responde
`is_reply`	booleano	Indica si es una respuesta
`is_quote_status`	booleano	Indica si cita otra publicación
`is_replies_limited`	booleano	Indica si el autor restringió las respuestas

Objetos anidados

Campo	Tipo	Descripción
`user`	objeto User	Perfil completo del autor
`entities`	array de TweetEntity	Archivos multimedia y enlaces adjuntos
`quoted_status`	objeto Tweet o null	Publicación citada (objeto completo y recursivo)
`retweeted_status`	objeto Tweet o null	Publicación original retuiteada (objeto completo y recursivo)

quoted_status y retweeted_status contienen objetos Tweet completos, con sus propios campos user, entities y métricas. Así obtienes los datos relacionados en una sola llamada, sin solicitudes adicionales.

El objeto TweetEntity

Cada elemento de entities representa un archivo multimedia adjunto o un enlace insertado en la publicación.

{
  "type": "photo",
  "link": "https://pbs.twimg.com/media/..._large.jpg",
  "preview": "https://pbs.twimg.com/media/..._small.jpg"
}

Campo	Tipo	Descripción
`type`	cadena	Tipo de elemento, como `photo`, `video` o `animated_gif`
`link`	cadena	URL directa al archivo en resolución completa
`preview`	cadena	Texto de vista previa o URL de miniatura

Paginación por cursor

Los endpoints de listas paginadas utilizan cursores. Las consultas por lotes y las listas de análisis de criptomonedas descritas antes no los utilizan. La paginación por cursor es más fiable que la basada en desplazamientos cuando se añade contenido continuamente. Procedimiento:

Envía la solicitud inicial sin cursor.
Recibirás los datos y un campo next_cursor.
Incluye ese valor en la siguiente solicitud para obtener la próxima página.
Si next_cursor es null o no aparece, has llegado al final.

Los endpoints GET reciben el cursor como parámetro de consulta:

curl --request GET \
  --url 'https://api.sorsa.io/v3/followers?username=elonmusk&next_cursor=abc123' \
  --header 'ApiKey: YOUR_API_KEY'

Los endpoints POST lo reciben en el cuerpo JSON:

curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin", "next_cursor": "abc123"}'

Ejemplo en Python: recorrer todos los seguidores

import time
import requests

API_KEY = "YOUR_API_KEY"
all_users = []
cursor = None

while True:
    params = {"username": "elonmusk"}
    if cursor:
        params["next_cursor"] = cursor

    response = requests.get(
        "https://api.sorsa.io/v3/followers",
        params=params,
        headers={"ApiKey": API_KEY},
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()

    all_users.extend(data["users"])
    cursor = data.get("next_cursor")

    if not cursor:
        break

    time.sleep(0.05)  # respect rate limit

print(f"Fetched {len(all_users)} followers")

Consulta estrategias y consejos de rendimiento en Paginación.

Próximos pasos

Paginación: patrones avanzados y buenas prácticas.
Códigos de error: estructura de las respuestas de error.
Referencia de la API: esquemas completos y ejemplos de solicitudes y respuestas.

Primeros pasos

Conceptos básicos

Guías prácticas

Soporte y recursos

Formato de respuesta

Formato de respuesta: esquemas de User y Tweet

Convenciones

Estructuras contenedoras de respuesta

El objeto User

El objeto Follower

El objeto Tweet

El objeto TweetEntity

Paginación por cursor

Próximos pasos

​Formato de respuesta: esquemas de User y Tweet

​Convenciones

​Estructuras contenedoras de respuesta

​El objeto User

​El objeto Follower

​El objeto Tweet

​El objeto TweetEntity

​Paginación por cursor

​Próximos pasos

Formato de respuesta: esquemas de User y Tweet

Convenciones

Estructuras contenedoras de respuesta

El objeto User

El objeto Follower

El objeto Tweet

El objeto TweetEntity

Paginación por cursor

Próximos pasos