Guía de integración

Conceptos clave y prácticas recomendadas para integrar los endpoints de Timelines

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

shellscript

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"

​

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

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

​

Ejemplo

cURL

shellscript

# 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"

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

shellscript

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

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