Guía de integración

Esta guía abarca los conceptos clave que necesitas para integrar los endpoints de Timelines en tu aplicación.

Autenticación

Requisitos del endpoint

Endpoint	Solo App	Contexto de usuario
Cronología de publicaciones del usuario	✓	✓
Cronología de menciones del usuario	✓	✓
Cronología de inicio	—	✓ (obligatorio)

Métricas privadas

Para acceder a las métricas privadas, debes autenticarte en representación del autor de la Publicación:

Estos campos requieren autenticación en contexto de usuario:

tweet.fields.non_public_metrics
tweet.fields.promoted_metrics
tweet.fields.organic_metrics
media.fields.non_public_metrics
media.fields.promoted_metrics
media.fields.organic_metrics

Campos y expansions

De forma predeterminada, las respuestas incluyen únicamente id, text y edit_history_tweet_ids. Solicita datos adicionales:

Ejemplo de solicitud

cURL

curl "https://api.x.com/2/users/123/tweets?\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtener la cronología de Publicaciones de un usuario
for page in client.posts.get_user_posts(
    user_id="123",
    tweet_fields=["created_at", "public_metrics", "author_id"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"],
    max_results=100
):
    for post in page.data:
        print(f"{post.text} - {post.public_metrics}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Obtener la cronología de Publicaciones de un usuario con paginación
const paginator = client.posts.getUserPosts("123", {
  tweetFields: ["created_at", "public_metrics", "author_id"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`${post.text} - ${JSON.stringify(post.public_metrics)}`);
  });
}

Campos clave

Campo	Descripción
`created_at`	Marca de tiempo de creación de la publicación
`public_metrics`	Métricas de interacción
`conversation_id`	Identificador del hilo de conversación
`context_annotations`	Clasificaciones de temas
`entities`	Hashtags, menciones, URL

Guía de campos y expansions

Más información sobre cómo personalizar las respuestas

Paginación

Las timelines devuelven hasta 100 Publicaciones por solicitud. Utiliza la paginación para obtener conjuntos de resultados más grandes.

Cómo funciona

Realiza una solicitud inicial con max_results
Obtén next_token del objeto meta
Incluye pagination_token en la siguiente solicitud
Repite hasta que ya no se devuelva ningún next_token

Ejemplo

cURL

# Primera solicitud
curl "https://api.x.com/2/users/123/tweets?max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# Solicitud siguiente con token de paginación
curl "https://api.x.com/2/users/123/tweets?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# El SDK gestiona la paginación automáticamente
all_posts = []

for page in client.posts.get_user_posts(user_id="123", max_results=100):
    if page.data:
        all_posts.extend(page.data)

print(f"Se encontraron {len(all_posts)} publicaciones")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

async function getAllTimelinePosts(userId) {
  const allPosts = [];

  // El SDK gestiona la paginación automáticamente con iteración asíncrona
  const paginator = client.posts.getUserPosts(userId, { maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allPosts.push(...page.data);
    }
  }

  return allPosts;
}

// Uso
const posts = await getAllTimelinePosts("123");
console.log(`Se encontraron ${posts.length} publicaciones`);

Guía de paginación

Obtén más información sobre la paginación

Filtrar resultados

Filtrado por tiempo

Parámetro	Descripción
`start_time`	Marca de tiempo de la Publicación más antigua (ISO 8601)
`end_time`	Marca de tiempo de la Publicación más reciente (ISO 8601)
`since_id`	Devuelve Publicaciones posteriores a este identificador
`until_id`	Devuelve Publicaciones anteriores a este identificador

Parámetro exclude

Elimina tipos específicos de Publicaciones de los resultados:

cURL

curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Excluir retweets y respuestas
for page in client.posts.get_user_posts(
    user_id="123",
    exclude=["retweets", "replies"]
):
    for post in page.data:
        print(post.text)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Excluir retweets y respuestas
const paginator = client.posts.getUserPosts("123", {
  exclude: ["retweets", "replies"],
});

for await (const page of paginator) {
  page.data?.forEach((post) => console.log(post.text));
}

Valor	Efecto
`retweets`	Excluye retweets
`replies`	Excluye respuestas

Límites de volumen

Cada cronología tiene límites máximos de obtención:

Endpoint	Número máximo de Publicaciones
Cronología de Publicaciones de usuario	3.200 más recientes
Publicaciones de usuario (exclude=replies)	800 más recientes
Cronología de menciones de usuario	800 más recientes
Cronología de inicio	3.200 o 7 días

Si solicitas Publicaciones más allá de estos límites, se devuelve una respuesta exitosa sin datos.

Edición de Publicaciones

Las publicaciones se pueden editar hasta 5 veces en un periodo de 30 minutos. Los endpoints de línea de tiempo siempre devuelven la versión más reciente.

Consideraciones

Las Publicaciones con más de 30 minutos representan su versión final
Los casos de uso casi en tiempo real deben tener en cuenta posibles ediciones
Usa Post lookup para verificar el estado final cuando sea necesario

Fundamentos de edición de Publicaciones

Obtén más información sobre la edición de Publicaciones

Métricas de publicaciones

Métricas públicas

Disponibles para todas las Publicaciones con autenticación solo de App o con contexto de usuario:

{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12
  }
}

Métricas privadas

Requiere autenticación con contexto de usuario del autor de la Publicación:

Solo disponible para Publicaciones de los últimos 30 días
Solo se devuelve para Publicaciones creadas por el usuario autenticado
Devuelve un error para Publicaciones de otros usuarios

Casos límite

Métricas no públicas y paginación

Al solicitar métricas no públicas para Publicaciones de hace más de 30 días, puedes recibir un next_token con result_count: 0. Para evitarlo:

Mantén las solicitudes dentro de los últimos 30 días
Usa un max_results de al menos 10

Métricas promocionadas para Publicaciones no promocionadas

Solicitar métricas promocionadas para Publicaciones que no fueron promocionadas devuelve una respuesta vacía. Este es un problema conocido.

Texto de Retweet truncado

Para Retweets con texto de más de 140 caracteres, el campo de texto se trunca. Usa la expansión referenced_tweets.id para obtener el texto completo.

Próximos pasos

Inicio rápido de la cronología principal

Obtén la cronología principal de un usuario

Inicio rápido de menciones

Obtén las menciones de un usuario

Referencia de la API

Documentación completa del endpoint

Paginación

Gestiona grandes conjuntos de resultados