Guía de integración

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

Autenticación

Los endpoints de consulta de Listas admiten varios métodos de autenticación:

Método	Mejor para	¿Acceso a Listas privadas?
OAuth 2.0 App-Only	Datos de Listas públicas	No
OAuth 2.0 Authorization Code with PKCE	Aplicaciones para usuarios finales	Sí (propietarias/seguidas)
OAuth 1.0a User Context	Integraciones heredadas	Sí (propietarias/seguidas)

Ejemplo de solicitud

cURL

curl "https://api.x.com/2/lists/84839422?\
list.fields=description,member_count,follower_count,private" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtener una Lista por ID
response = client.lists.get(
    list_id="84839422",
    list_fields=["description", "member_count", "follower_count", "private"]
)
print(response.data)

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

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

const response = await client.lists.get("84839422", {
  listFields: ["description", "member_count", "follower_count", "private"],
});
console.log(response.data);

Descripción general de los endpoints

Método	Endpoint	Descripción
GET	`/2/lists/:id`	Obtener una lista por id
GET	`/2/users/:id/owned_lists`	Obtener listas propiedad de un usuario

Campos y expansions

Respuesta predeterminada

{
  "data": {
    "id": "84839422",
    "name": "Tech News"
  }
}

Campos disponibles

list.fields

Campo	Descripción
`created_at`	Marca de tiempo de creación de la Lista
`description`	Descripción de la Lista
`follower_count`	Número de seguidores
`member_count`	Número de miembros
`owner_id`	ID de usuario del propietario
`private`	Indica si la Lista es privada

user.fields (requiere la expansión de owner_id)

Campo	Descripción
`username`	@handle del propietario
`name`	Nombre para mostrar del propietario
`verified`	Estado de verificación del propietario
`profile_image_url`	URL del avatar del propietario

Ejemplo con `expansions`

cURL

curl "https://api.x.com/2/lists/84839422?\
list.fields=description,member_count,follower_count,owner_id&\
expansions=owner_id&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtener una Lista con la expansión del propietario
response = client.lists.get(
    list_id="84839422",
    list_fields=["description", "member_count", "follower_count", "owner_id"],
    expansions=["owner_id"],
    user_fields=["username", "verified"]
)

print(response.data)
print(response.includes)  # Contiene el objeto de usuario del propietario

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

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

const response = await client.lists.get("84839422", {
  listFields: ["description", "member_count", "follower_count", "owner_id"],
  expansions: ["owner_id"],
  userFields: ["username", "verified"],
});

console.log(response.data);
console.log(response.includes); // Contiene el objeto de usuario del propietario

Respuesta con expansión

{
  "data": {
    "id": "84839422",
    "name": "Tech News",
    "description": "Top tech journalists",
    "member_count": 50,
    "follower_count": 1250,
    "owner_id": "2244994945"
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "XDevelopers",
        "verified": true
      }
    ]
  }
}

Guía de campos y expansions

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

Paginación

Al recuperar listas propias, los resultados se paginan:

cURL

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

# Solicitud posterior con token de paginación
curl "https://api.x.com/2/users/123/owned_lists?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_lists = []

for page in client.lists.get_user_owned_lists(user_id="123", max_results=100):
    if page.data:
        all_lists.extend(page.data)

print(f"Se encontraron {len(all_lists)} listas")

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

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

async function getAllOwnedLists(userId) {
  const allLists = [];

  // El SDK gestiona la paginación automáticamente
  const paginator = client.lists.getUserOwnedLists(userId, { maxResults: 100 });

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

  return allLists;
}

// Uso
const lists = await getAllOwnedLists("123");
console.log(`Se encontraron ${lists.length} listas`);

Guía de paginación

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

Listas privadas

Las listas privadas solo son visibles para su propietario
Debes autenticarte como propietario para obtener los detalles de una lista privada
El campo private indica si una lista es privada

Gestión de errores

Estado	Error	Solución
400	Solicitud no válida	Comprueba el formato del id de la lista
401	No autorizado	Comprueba la autenticación
403	Prohibido	La lista puede ser privada
404	No encontrado	La lista no existe
429	Demasiadas solicitudes	Espera y vuelve a intentarlo

Próximos pasos

Inicio rápido

Haz tu primera solicitud de consulta de una lista

Publicaciones de la Lista

Obtén publicaciones de una lista

Referencia de la API

Documentación completa del endpoint

Código de ejemplo

Ejemplos de código listos para usar

Descripción general

Publicaciones

Usuarios

Mensajes directos

Me gusta

Listas

Spaces

Comunidades

Notas de la comunidad

Tendencias

Noticias

Contenido multimedia

Actividad en X

Uso

Conexiones de streaming

Cumplimiento

Enterprise v2

Flujos de Me gusta

GNIP 2.0

Guía de integración

Autenticación

Ejemplo de solicitud

Descripción general de los endpoints

Campos y expansions

Respuesta predeterminada

Campos disponibles

Ejemplo con `expansions`

Respuesta con expansión

Guía de campos y expansions

Guía de paginación

Listas privadas

Gestión de errores

Próximos pasos

Inicio rápido

Publicaciones de la Lista

Referencia de la API

Código de ejemplo

Autenticación

Ejemplo de solicitud

Descripción general de los endpoints

Campos y expansions

Respuesta predeterminada

Campos disponibles

Ejemplo con expansions

Respuesta con expansión

Guía de campos y expansions

Paginación

Guía de paginación

Listas privadas

Gestión de errores

Próximos pasos

Inicio rápido

Publicaciones de la Lista

Referencia de la API

Código de ejemplo

Ejemplo con `expansions`