Skip to main content
La X API devuelve objetos JSON estructurados que representan Publicaciones, usuarios, contenido multimedia y más. Esta referencia documenta todos los campos disponibles para cada tipo de objeto.
Utiliza los parámetros fields para solicitar campos específicos y expansions para incluir objetos relacionados.

Publicación (Tweet)

Las Publicaciones son la unidad principal de contenido en X. Cada objeto de Publicación incluye texto, metadatos y referencias a objetos relacionados como autores, medios y encuestas. Campos predeterminados: id, text, edit_history_tweet_ids Utiliza tweet.fields para solicitar campos adicionales y expansions para incluir objetos relacionados.

Todos los campos de Publicación

Obtención de un objeto Tweet Solicitud de ejemplo En la siguiente solicitud, estamos solicitando campos para el Tweet en el endpoint Tweets lookup. Asegúrate de reemplazar $BEARER_TOKEN con tu propio Bearer Token generado.
Ejemplo de respuesta

User

El objeto user contiene metadatos de la cuenta de usuario de Twitter que describen al usuario de referencia. El objeto user es el objeto principal que devuelve el endpoint users lookup. Al solicitar campos de usuario adicionales en este endpoint, basta con usar el parámetro de campos user.fields. El objeto user también se puede encontrar como un objeto hijo y expandido en el objeto Tweet. El objeto está disponible para expansión con ?expansions=author_id o ?expansions=in_reply_to_user_id para obtener el objeto resumido con solo los campos predeterminados. Usa la expansión junto con el parámetro de campos user.fields cuando solicites campos adicionales para completar el objeto.   Obtención de un objeto de usuario Solicitud de ejemplo En la siguiente solicitud, estamos solicitando campos para el usuario mediante el endpoint de users lookup. Asegúrate de reemplazar $BEARER_TOKEN con tu propio Bearer Token generado.
Ejemplo de respuesta

Space

Los Spaces permiten la expresión y la interacción a través de conversaciones de audio en vivo. El diccionario de datos de Space contiene metadatos relevantes sobre un Space; todos los detalles se actualizan en tiempo real. Los objetos User se pueden encontrar y expandir en el recurso user. Estos objetos están disponibles para expansión añadiendo al menos uno de host_ids, creator_id, speaker_ids, mentioned_user_ids al parámetro de consulta expansions. A diferencia de los Tweets, los Spaces son efímeros y dejan de estar disponibles después de que terminan o cuando son cancelados por su creador. Cuando tu aplicación procese datos de Spaces, eres responsable de devolver la información más actualizada y debes eliminar los datos que ya no estén disponibles en la plataforma. Los endpoints de búsqueda de Spaces pueden ayudarte a garantizar que respetas las expectativas y la intención de los usuarios. Recuperar un objeto Space Ejemplo de solicitud En la siguiente solicitud, pedimos campos para el Space en el endpoint de consulta de Spaces. Asegúrate de reemplazar $BEARER_TOKEN por tu propio Bearer Token generado.
** Respuesta de ejemplo **

Lista

El objeto de Lista contiene metadatos de Listas de X que describen la Lista de referencia. El objeto de Lista es el objeto principal devuelto en el endpoint de consulta de Listas. Al solicitar campos adicionales de Lista en este endpoint, simplemente usa el parámetro de campos list.fields. El objeto de Lista no se encuentra como hijo de otros objetos de datos. Sin embargo, los objetos de usuario se pueden encontrar y expandir en el recurso de usuario. Estos objetos están disponibles para su expansión añadiendo owner_id al parámetro de consulta expansions. Usa esta expansión con el parámetro de campos list.fields cuando solicites campos adicionales para completar el objeto de Lista principal y user.fields para completar el objeto expandido. Recuperar un objeto de usuario Ejemplo de solicitud En la siguiente solicitud, solicitamos campos para el usuario en el endpoint de consulta de Lista por ID. Reemplaza $BEARER_TOKEN por tu Bearer Token generado.
** Respuesta de ejemplo**

Media

Media se refiere a cualquier imagen, GIF o video adjunto a un Tweet. El objeto media no es un objeto principal en ningún endpoint, pero se puede encontrar y expandir dentro del objeto Tweet. El objeto está disponible para expansión con ?expansions=attachments.media_keys para obtener el objeto simplificado solo con los campos predeterminados. Usa la expansión junto con el parámetro de campos: media.fields cuando solicites campos adicionales para completar el objeto. Recuperar un objeto media Solicitud de ejemplo En la siguiente solicitud, solicitamos campos para el objeto media adjunto al Tweet en el endpoint Tweet lookup. Dado que media es un objeto hijo de un Tweet, se requiere la expansión attachment.media_keys. Asegúrate de reemplazar $BEARER_TOKEN con tu propio Bearer Token generado.

Poll

Una encuesta incluida en un Tweet no es un objeto principal en ningún endpoint, pero se puede encontrar y expandir dentro del objeto Tweet. El objeto está disponible para usar con la expansión ?expansions=attachments.poll_ids y obtener así el objeto resumido solo con los campos predeterminados. Usa la expansión junto con el parámetro de campos: poll.fields cuando solicites campos adicionales para completar el objeto. Retrieving a poll object Sample Request En la siguiente solicitud, se solicitan campos para el objeto de la encuesta adjunto al Tweet en el endpoint Tweets lookup. Dado que la encuesta es un objeto hijo de un Tweet, se requiere la expansión attachments.poll_id. Asegúrate de reemplazar $BEARER_TOKEN con tu propio Bearer Token generado.
Ejemplo de respuesta

Lugar

El lugar etiquetado en un Tweet no es un objeto principal en ningún endpoint, pero se puede encontrar y expandir en el recurso del Tweet. El objeto está disponible para ser expandido con ?expansions=geo.place_id para obtener el objeto condensado solo con los campos predeterminados. Usa la expansión con el parámetro de campos: place.fields cuando solicites campos adicionales para completar el objeto. Recuperar un objeto de lugar Ejemplo de solicitud En la siguiente solicitud, solicitamos campos para el objeto de lugar adjunto al Tweet en el endpoint de búsqueda de Tweets. Dado que place es un objeto secundario de un Tweet, se requiere la expansión geo.place_id. Asegúrate de reemplazar $BEARER_TOKEN con tu propio Bearer Token generado.
Ejemplo de respuesta

Eventos de Mensajes Directos

Las conversaciones de Mensajes Directos (DM) están compuestas por eventos. La X API v2 actualmente admite tres tipos de eventos: MessageCreate, ParticipantsJoin y ParticipantsLeave. Los objetos de eventos de DM los devuelven los endpoints de Direct Message lookup, y se crea un evento MessageCreate cuando los Mensajes Directos se crean correctamente con los endpoints de Manage Direct Messages. Al solicitar eventos de DM, se incluyen de forma predeterminada tres atributos del objeto de evento, o campos: id, event_type y text. Para recibir campos de evento adicionales, usa el parámetro fields dm_event.fields para seleccionar otros. Otros campos de evento disponibles incluyen los siguientes: dm_conversation_id, created_at, sender_id, attachments, participant_ids y referenced_tweets. Varios de estos campos proporcionan los ID de otros objetos de X relacionados con el evento de Mensaje Directo:
  • sender_id - El ID de la cuenta que envió el mensaje o que invitó a un participante a una conversación de grupo
  • partricipants_ids - Un array de ID de cuenta. Para los eventos ParticipantsJoin y ParticipantsLeave, este array contendrá un único ID de la cuenta que creó el evento
  • attachments - Proporciona los ID de medios para contenido que ha sido subido a Twitter por el remitente
  • referenced_tweets - Si se encuentra una URL de un Tweet en el campo text, el ID de ese Tweet se incluye en la respuesta
Las expansions sender_id, participant_ids, referenced_tweets.id y attachments.media_keys están disponibles para expandir estos ID de objetos de Twitter. Recuperar un objeto de evento de Mensaje Directo Solicitud de ejemplo En este ejemplo, crearemos una solicitud que recupera eventos asociados con una conversación de uno a uno. Esta solicitud devolverá campos fundamentales del evento de Mensaje Directo, junto con campos adicionales para los Tweets referenciados y sus autores. Construyamos una consulta que solicite:
  • Atributos fundamentales del evento, como cuándo se creó y de qué conversación forma parte (dm_conversation).
  • El ID de la cuenta y la descripción de quien envió el Mensaje Directo.
  • El texto de cualquier Tweet referenciado y cuándo se publicó.
  • El ID de la cuenta y la descripción de cualquier autor de Tweet referenciado.
Para devolver esos atributos, la consulta de tu solicitud debe incluir lo siguiente: ?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description
Asegúrate de reemplazar $BEARER_TOKEN por tu propio Bearer Token generado. Respuesta de ejemplo

Comunidad

Las Comunidades son espacios dedicados para que los usuarios de X se conecten, compartan y se acerquen más a las conversaciones que más les interesan. Las Publicaciones en Comunidades pueden verse por cualquier persona en X, pero solo otros miembros dentro de la propia Comunidad pueden interactuar y participar en la conversación. El objeto Community contiene metadatos relevantes sobre una Comunidad. Recuperar objetos Community Ejemplo de solicitud En la siguiente solicitud, solicitamos campos específicos mientras buscamos una lista de Comunidades en función de una palabra clave proporcionada. Asegúrate de reemplazar $BEARER_TOKEN con tu propio Bearer Token generado.
Ejemplo de respuesta

Cómo usar campos y expansions

De forma predeterminada, los objetos de datos de X API v2 incluyen una pequeña cantidad de campos predeterminados cuando se hace una solicitud sin utilizar los parámetros fields o expansions. Esta guía te mostrará cómo usar los parámetros de consulta fields y expansions en tu solicitud para recibir objetos y campos adicionales en tu respuesta. En esta guía, solicitaremos varios campos del siguiente Tweet de la captura de pantalla.   Esta imagen incluye una captura de pantalla de un Tweet publicado por @X. Puedes ver el texto del Tweet, el nombre de usuario, la fecha y hora de publicación, la fuente y las métricas públicas. También incluye un video. Como puedes ver en la captura de pantalla, hay varios elementos de información visibles relacionados con el Tweet, incluido el autor del Tweet, las métricas del Tweet, la marca de tiempo de creación, el video y el número de reproducciones del video. También hay varios datos que no son visibles en la captura de pantalla, pero que siguen estando disponibles para solicitarlos.  Al hacer una solicitud a la API, la respuesta predeterminada es sencilla y contiene solo los campos de Tweet predeterminados (id y text). También solo recibirás el objeto principal que devuelve el endpoint que estás utilizando, y no ninguno de los objetos de datos asociados que puedan estar relacionados con el objeto principal. Esta simplicidad, junto con los parámetros fields y expansions, te permite solicitar solo aquellos campos que necesitas, según tu caso de uso.   

Solicitud de campos y objetos adicionales.

En primer lugar, solicitaremos un objeto Tweet usando un ID de Tweet y el endpoint GET /tweets. Solicitud:
Respuesta:
La siguiente guía paso a paso mostrará cómo recuperar los datos adicionales que se pueden ver en la captura de pantalla.
  1. Identifica los campos adicionales que quieras solicitar mediante nuestro modelo de objetos, o revisando la lista de campos en las páginas de referencia de la API de los endpoints. En este caso, solicitaremos los siguientes campos adicionales: attachments, author_id, created_at, public_metrics.
  2. Crea el parámetro de consulta tweet.fields con los campos anteriores como valor, usando una lista separada por comas: ?tweet.fields=attachments,author_id,created_at,public_metrics
  3. Agrega el parámetro de consulta a la solicitud GET /tweets que hiciste anteriormente.
Solicitud: curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics' \ --header 'Authorization: Bearer $BEARER_TOKEN' Respuesta:
  1. A continuación, solicitaremos campos relacionados con el video incluido en el Tweet. Para hacerlo, usaremos el parámetro expansions con attachments.media_keys como valor y lo agregaremos a la solicitud.
?expansions=attachments.media_keys Solicitud:
Respuesta, con el objeto de medios representado en el objeto includes:
  1. Y finalmente, vamos a solicitar el número de visualizaciones y la duración del video. Estos no son campos predeterminados, por lo que tenemos que solicitarlos específicamente. Usa el parámetro media.fields con los valores separados por comas, public_metrics y duration_ms en tu solicitud.
?media.fields=public_metrics,duration_ms Solicitud:   curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys&media.fields=duration_ms,public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN' Respuesta que ahora incluye todos los datos que aparecen en la captura de pantalla del Tweet:
En total, incluimos los siguientes parámetros en este ejemplo:
  • ids=1260294888811347969
  • tweet.fields=attachments,author_id,created_at,public_metrics
  • expansions=attachments.media_keys
  • media.fields=public_metrics,duration_ms  
Al combinarlos, la cadena de consulta completa se ve así:

Ejemplos de cargas de datos de X API v2

Tweet

Respuesta a un Tweet

Tweet extendido

Tweet con contenido multimedia

Retweet de Tweet citado