Grok X Search API: Capturar datos de publicaciones X (Twitter) como JSON estructurado

TL;DR:

• Grok responde citando publicaciones de X, y el actor Scrapeless scraper.grok devuelve esas publicaciones como un array estructurado separado. x_search_results se encuentra junto a web_search_results en la misma carga útil, por lo que una solicitud genera tanto las citas de la web abierta como las citas de X (Twitter) sin ningún análisis de HTML.
• Cada cita de X lleva once claves, siete de las cuales llegaron pobladas en cada captura. post_id, user_name, name, text, create_time, view_count, y profile_image_url estaban no vacías en las 167 entradas de publicaciones recopiladas para esta guía; citation_id, community_note, parent, y quote estaban vacías en todas ellas.
• El prompt es la superficie de control, no un parámetro de búsqueda. Una pregunta definicional simple devolvió cero llamadas a herramientas y dos paneles vacíos. Los prompts que apuntan a Grok en X devolvieron entre 3 y 35 publicaciones.
• tool_usages expone la consulta literal de X que Grok ejecutó. El array registra el nombre de la herramienta y sus argumentos, por lo que puedes volver a leer la cadena de búsqueda exacta — incluidos los operadores from:, since:, until:, y min_faves: — que produjo las publicaciones que recibiste.
• No se garantiza que el panel esté deduplicado. Las llamadas a herramientas superpuestas pueden repetir publicaciones, y la frecuencia varía por captura: en siete capturas, la proporción de duplicados osciló entre 0% (18 entradas, 18 valores post_id distintos) y 48% (25 entradas, 13 distintos). Deduplica antes de contar anything: dos de las siete capturas llegaron sin repeticiones, y nada en la respuesta te dice qué tipo recibiste.
• El modo de razonamiento no controló la profundidad de origen de X. Dos pares MODEL_MODE_FAST / MODEL_MODE_EXPERT en un prompt idéntico se invirtieron, así que trata el modo como un ajuste de razonamiento y no como un control de volumen.
• Gratis para empezar. Las nuevas cuentas de Scrapeless incluyen créditos de prueba gratuitos — regístrate en app.scrapeless.com.

Pide a Grok qué están publicando las personas sobre el lanzamiento de un telescopio y la respuesta llega con una lista de publicaciones de X debajo. Esas publicaciones son la evidencia que el modelo seleccionó, y el actor Scrapeless scraper.grok las devuelve como filas JSON con identificadores de autor, marcas de tiempo, recuentos de vistas y identificadores de publicación ya separados en campos.

Eso convierte a Grok en una ruta diferente hacia los datos de X que la habitual. El enfoque común extrae publicaciones directamente de la plataforma y apunta a la completitud. Esta guía cubre la dirección opuesta: capturando las publicaciones que un motor de respuesta eligió citar, que es una porción más pequeña y ya filtrada, más la consulta que el modelo utilizó para encontrarlas.

Esta guía cubre la forma de la solicitud, el esquema exacto de campos de una cita de X, cómo hacer que el panel se complete en lugar de llegar vacío, y el array tool_usages que muestra lo que Grok realmente buscó. Para el contrato general del actor — sobre envasado, modos, actores acompañantes — consulta la guía de API del scraper Grok.

Lo que la API de Búsqueda X de Grok Te Da

Una solicitud devuelve la respuesta de Grok más sus dos paneles de citas como arrays discretos. El panel X es la parte de la que trata esta guía.

• Filas a nivel de publicación, no un feed renderizado. Cada entrada es un objeto con un post_id estable, el identificador y nombre para mostrar del autor, el texto de la publicación, una marca de tiempo en formato RFC 3339, y un recuento de vistas como un entero.
• La consulta propia del modelo, registrada. tool_usages preserva la búsqueda emitida por Grok, por lo que una captura es reproducible y auditable en lugar de una caja negra.
• Ambos paneles de una sola llamada. Un prompt que abarca la reacción social y la documentación oficial devuelve publicaciones de X y páginas de la web abierta en la misma carga útil, ya separadas.
• Porciones limitadas en el tiempo. Debido a que Grok compone operadores de fecha en sus búsquedas de X, los prompts que nombran una ventana producen publicaciones dentro de esa ventana.
• Capturas limitadas a la cuenta. Un prompt que nombra una cuenta se dirige a través de una búsqueda de usuario X y devuelve las publicaciones recientes de esa cuenta.

El panel es un conjunto de citas en lugar de un archivo completo. Refleja en qué se basó una respuesta, que se adapta mejor al seguimiento de citas y muestreo de sentimientos que a la recolección exhaustiva.

Punto Final, Actor y Parámetros

• Punto final sincrónico: POST https://api.scrapeless.com/api/v2/scraper/execute — bloquea y devuelve el resultado final.
• Punto final asincrónico: POST https://api.scrapeless.com/api/v2/scraper/request devuelve un task_id; GET https://api.scrapeless.com/api/v2/scraper/result/{task_id} devuelve el resultado una vez que esté listo.
• Actor: scraper.grok
• Encabezado de autenticación: x-api-token: $SCRAPELESS_API_KEY

Las capturas para esta guía terminaron en aproximadamente 16 a 60 segundos. El endpoint sincrónico se adapta a una verificación rápida desde la línea de comandos. Para cualquier cosa con guiones, prefiere el par asincrónico: responde a la llamada de envío con HTTP 201 y un task_id, luego devuelve el estado 202 Aceptado definido en la especificación de semántica HTTP mientras la tarea aún se está ejecutando y 200 con status: "success" una vez que el resultado esté listo. La sondeo para esa transición es lo que hace que un cliente sea determinista independientemente de cuánto tiempo dure un aviso dado.

Mantén la clave en el entorno en lugar de en el código:

export SCRAPELESS_API_KEY="your_api_token_here"

Tu Primer Captura

Esta solicitud nombra una cuenta, que es la forma más confiable de obtener un panel X poblado en el primer intento. El filtro jq imprime los dos tamaños de panel y las herramientas que invocó Grok.

curl -sS -X POST https://api.scrapeless.com/api/v2/scraper/execute \
  -H "Content-Type: application/json" \
  -H "x-api-token: ${SCRAPELESS_API_KEY}" \
  -d '{
    "actor": "scraper.grok",
    "input": {
      "prompt": "What has @NASA posted on X recently?",
      "country": "US",
      "mode": "MODEL_MODE_FAST"
    }
  }' | jq '{
    x_posts: (.task_result.x_search_results | length),
    web_pages: (.task_result.web_search_results | length),
    tools: [.task_result.tool_usages[].tool_name]
  }'

Una captura de esa solicitud devolvió {"x_posts": 20, "web_pages": 0, "tools": ["x_keyword_search", "x_keyword_search"]} — veinte publicaciones X, ninguna página de la web abierta, y dos búsquedas de palabras clave. Los conteos varían entre ejecuciones, así que trata la forma como el contrato y los números como una muestra. Si x_posts es 0 y tools está vacío, Grok respondió desde su propio conocimiento y no buscó nada — ve haciendo que se llene el panel X a continuación.

El Esquema de la Publicación X, Campo por Campo

Cada entrada en x_search_results es un objeto plano con las mismas once claves. Esta es una captura real de la solicitud @NASA anterior:

// captured from a live scraper.grok run; a single x_search_results entry
{
  "citation_id": "",
  "community_note": "",
  "create_time": "2026-08-06T11:00:59Z",
  "name": "NASA",
  "parent": null,
  "post_id": "2085320225776427457",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg",
  "quote": null,
  "text": "LIVE: Time for a spacewalk! Watch as @Astro_Jessica and @Astro_Anil step outside the @Space_Station to prepare the orbiting lab for a new solar array.",
  "user_name": "NASA",
  "view_count": 714862
}

A través de 167 entradas de publicaciones capturadas para esta guía, los campos se separan limpiamente en dos grupos:

Los cuatro campos nunca poblados merecen una advertencia. Están presentes en el esquema en cada entrada, así que el código que los lee no generará errores, pero nada en este conjunto de capturas los llenó. Construye sobre los siete que llegan poblados, y trata los otros cuatro como reservados en lugar de como una característica de hilo de respuesta o Notas de la Comunidad de las que puedes depender.

user_name y post_id juntos reconstruyen una URL de publicación canónica como https://x.com/<user_name>/status/<post_id>, que es útil para almacenar un enlace de regreso a la fuente.

Obtén tu clave API en el plan gratuito: app.scrapeless.com

Leyendo la Consulta que Grok Realmente Ejecutó

tool_usages es el campo que separa esta ruta de captura de una búsqueda X simple. Cada entrada nombra una herramienta y lleva sus argumentos como un string JSON, así que puedes leer exactamente lo que se buscó.

import json
import os
import time

import requests

BASE = "https://api.scrapeless.com/api/v2/scraper"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


def capture(prompt, country="US", mode="MODEL_MODE_FAST"):
    """Submit a Grok capture, then poll until the task_result is ready."""
    submit = requests.post(
        f"{BASE}/request",
        headers=HEADERS,
        json={
            "actor": "scraper.grok",
            "input": {"prompt": prompt, "country": country, "mode": mode},
        },
        timeout=60,
    )
    submit.raise_for_status()
    task_id = submit.json()["task_id"]

    for _ in range(120):
        poll = requests.get(f"{BASE}/result/{task_id}", headers=HEADERS, timeout=60)
        poll.raise_for_status()
        body = poll.json()
        if body.get("status") == "success":
            return body["task_result"]
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in the allotted window")


result = capture("Search X for posts from:NASA about Artemis since:2026-07-01 and summarize them.")

for call in result.get("tool_usages") or []:
    print(call["tool_name"])
    for key, value in json.loads(call["tool_args"]).items():
        print(f"    {key}: {value}")

print(f"x_search_results: {len(result.get('x_search_results') or [])}")

Ese aviso incorpora dos operadores de búsqueda X, y sobreviven en la llamada de herramienta tal cual:

x_keyword_search
    query: from:NASA Artemis since:2026-07-01
    limit: 10
    mode: Latest
x_search_results: 3

Los operadores que escribes en el aviso se convierten en los operadores en la consulta. A través de las capturas, Grok compuso from:, since:, until:, lang:, y min_faves: en sus búsquedas, junto con un mode de Top o Latest. Algunos de esos coinciden con la referencia publicada de operadores de búsqueda de la plataforma, que enumera from: y lang: junto con filtros de compromiso; las fechas límite since: y until: provienen de la interfaz de búsqueda en lugar de esa referencia. Aparecieron tres herramientas X distintas:

| herramienta | argumentos observados | lo que hace |
| x_keyword_search | query, limit, mode | búsqueda de palabras clave impulsada por el operador; mode selecciona Top o Latest |
| x_semantic_search | query, limit, from_date, to_date, min_score_threshold | búsqueda basada en el significado a través de una ventana de fechas |
| x_user_search | query, count | búsqueda de cuenta, utilizada cuando un aviso nombra un identificador |

Dos herramientas no-X comparten el array: web_search con query y num_results, y open_page con url y start_line, que llena web_search_results en su lugar.

Registrar tool_usages junto a cada captura convierte un resultado almacenado en algo que puedes explicar más tarde: las publicaciones que mantuviste y la consulta que las encontró.

Haciendo que el Panel X se Rellene

Un x_search_results vacío no es una condición de error. Significa que Grok respondió sin buscar en X. La distinción es visible en la misma carga útil: cuando el panel está vacío porque no se buscó nada, tool_usages también está vacío.

Un aviso definicional simple — "¿Qué es un navegador sin cabeza?" — devolvió cero llamadas a herramientas, cero publicaciones en X y cero páginas web. Cada aviso que apuntó a X devolvió publicaciones. Medido a través de las capturas para esta guía:

Tres patrones de aviso poblaron el panel de manera confiable:

1. Nombrar la plataforma. "en X" en el aviso es la señal única más fuerte.
2. Nombrar una cuenta. Un identificador se dirige a través de x_user_search y devuelve las publicaciones de esa cuenta.
3. Preguntar por reacción, sentimiento o discusión. Estos extraen publicaciones donde una pregunta fáctica se resolvería en la web abierta.

La última fila hace algo que las otras no hacen. Un aviso que pide tanto la reacción social como la fuente oficial llena ambos paneles, por lo que una llamada devuelve lo que la gente está publicando junto con lo que dice la fuente principal.

Manejo de Salida Estructurada en Python

El panel necesita una transformación antes de que sea utilizable: desduplicación. Las llamadas a herramientas superpuestas pueden devolver la misma publicación más de una vez, por lo que la longitud del array es un límite superior en el número de publicaciones distintas en lugar de un conteo de ellas. Algunas capturas vuelven sin repeticiones en absoluto; otras repiten casi la mitad de sus entradas. Dado que no puedes saber cuál obtuviste sin verificar, desduplica incondicionalmente.

import json
import os
import time

import requests

BASE = "https://api.scrapeless.com/api/v2/scraper"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


def capture(prompt, country="US", mode="MODEL_MODE_FAST"):
    """Submit a Grok capture, then poll until the task_result is ready."""
    submit = requests.post(
        f"{BASE}/request",
        headers=HEADERS,
        json={
            "actor": "scraper.grok",
            "input": {"prompt": prompt, "country": country, "mode": mode},
        },
        timeout=60,
    )
    submit.raise_for_status()
    task_id = submit.json()["task_id"]
    print(f"submitted task_id={task_id}")

    for _ in range(120):
        poll = requests.get(f"{BASE}/result/{task_id}", headers=HEADERS, timeout=60)
        poll.raise_for_status()
        body = poll.json()
        if body.get("status") == "success":
            return body["task_result"]
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in the allotted window")


def x_rows(task_result):
    """Flatten x_search_results into unique rows keyed by post_id."""
    seen, rows = set(), []
    for post in task_result.get("x_search_results") or []:
        post_id = post.get("post_id")
        if not post_id or post_id in seen:
            continue
        seen.add(post_id)
        handle = post.get("user_name") or ""
        rows.append(
            {
                "post_id": post_id,
                "handle": handle,
                "display_name": post.get("name") or "",
                "posted_at": post.get("create_time") or "",
                "views": post.get("view_count") or 0,
                "text": " ".join((post.get("text") or "").split()),
                "url": f"https://x.com/{handle}/status/{post_id}",
            }
        )
    return rows


result = capture("What are people saying on X about the James Webb Space Telescope this week?")
rows = x_rows(result)

raw_count = len(result.get("x_search_results") or [])
print(f"raw={raw_count} unique={len(rows)}")

for row in sorted(rows, key=lambda r: r["views"], reverse=True)[:3]:
    print(f"@{row['handle']} · {row['posted_at']} · {row['views']:,} views")
    print(f"  {row['text'][:100]}")
    print(f"  {row['url']}")

print(json.dumps(rows[:1], ensure_ascii=False, indent=2))

x_rows devuelve exactamente la forma que un conjunto de columnas de tabla o almacén desea: una fila por publicación distinta, una URL resoluble y un conteo de vistas entero en el que puedes ordenar. La lista son diccionarios en formato JSON-serializable, por lo que se integra directamente en un DataFrame o en una sentencia de inserción.

Ordenar por views antes de muestrear es generalmente el movimiento correcto, porque el panel mezcla cuentas muy grandes con cuentas muy pequeñas: el rango observado en un conjunto de capturas iba de 0 a casi 7 millones de vistas en el mismo aviso.

Problemas Comunes de Forma de Datos

• La longitud del array no es el conteo de publicaciones. Desduplica en post_id antes de contar o graficar. Medido a través de siete capturas: 15 entradas / 13 únicas, 35 / 29, 34 / 31, 25 / 13, 15 / 14, y dos capturas que no repitieron nada (10 / 10 y 18 / 18). La participación de duplicados no es lo suficientemente estable como para predecir — incluye el paso de desduplicación de todos modos, porque un número de participación basado en longitud bruta exagera cada cuenta que ambas llamadas a herramientas revelaron.
• Cuatro campos están estructuralmente presentes pero siempre estuvieron vacíos. citation_id, community_note, parent, y quote aparecieron en cada entrada y estaban vacíos en los 167. No diseñes una función de hilo de respuesta o notas comunitarias alrededor de ellos sin confirmar que se llenan para tus avisos.
• view_count es un entero, post_id es una cadena. Los identificadores de publicaciones observados aquí superan 2×10^18, más allá del rango que un doble de precisión representa de manera exacta — que es por qué la guía de la especificación JSON sobre la interoperabilidad numérica advierte contra confiar en la precisión numérica a través de implementaciones. Mantén post_id como texto de principio a fin; convertirlo a un flotante es cómo los ID de publicaciones cambian de valor en silencio.
• El modo no es un dial de volumen. Dos pares de FAST / EXPERT en un mismo aviso idéntico devolvieron 15 frente a 20 publicaciones, luego 25 frente a 15 — el orden se invirtió. El tamaño del panel varió más entre dos ejecuciones de la misma configuración que entre configuraciones. Mantén el modo constante a lo largo de una serie rastreada para la consistencia metodológica, no porque garantice una obtención de información más profunda.
• El mismo aviso devuelve un panel diferente en cada ejecución. Grok recompone su consulta por ejecución, por lo que la redacción varía y también lo hace el conjunto de resultados. Lee una serie en lugar de una única captura y almacena tool_usages para que puedas ver qué ejecuciones hicieron preguntas diferentes.
• Los paneles se llenan independientemente. Un aviso puede llenar el panel X y dejar web_search_results vacío, o llenar ambos. Verifica la longitud de cada arreglo por separado en lugar de asumir que uno implica al otro.

Conclusión

El panel X en una captura de Grok es un pequeño conjunto de datos bien tipado que se encuentra dentro de una carga útil de respuesta. Un POST a scraper.grok con un aviso que nombra X devuelve IDs de publicaciones, handles, nombres para mostrar, texto de publicaciones, marcas de tiempo UTC y conteos de vistas como JSON plano — siete campos que llegaron poblados en cada entrada capturada para esta guía. Elimina duplicados en post_id, mantén el identificador como una cadena, y registra tool_usages para que cada fila almacenada lleve la consulta que la encontró. El resultado cubre una pequeña porción de la plataforma en lugar de un archivo de ella: las publicaciones que un motor de respuestas juzgó dignas de citar, con la búsqueda que las hizo visibles adjunta.

Comienza a Capturar Citaciones de X Desde Respuestas de Grok

Únete a nuestra comunidad para reclamar un plan gratuito y comparar notas con desarrolladores que construyen pipelines de motores de respuestas: Discord · Telegram.

Regístrate en app.scrapeless.com para créditos de prueba gratuitos, luego apunta scraper.grok a las cuentas, temas, y ventanas que tu programa de monitoreo rastrea. La página de API de Raspado Universal cubre la familia de actores más amplia, y los niveles de uso actuales están en la página de precios.

FAQ

P: ¿Por qué x_search_results está vacío en mi solicitud?

Porque Grok respondió sin buscar X. Verifica tool_usages en la misma carga útil: si también está vacío, no se realizó ninguna búsqueda. Los avisos que nombran la plataforma ("en X"), nombran una cuenta, o preguntan sobre reacciones y discusiones llenaron el panel en cada captura para esta guía, mientras que una simple pregunta definicional devolvió cero herramientas y cero publicaciones.

P: ¿Qué campos contiene realmente cada publicación de X?

Once claves, presentes en cada entrada. Siete estaban pobladas en las 167 entradas capturadas aquí: post_id, user_name, name, text, create_time, view_count, y profile_image_url. Las cuatro restantes — citation_id, community_note, parent, y quote — estaban vacías en cada una.

P: ¿Puedo controlar qué publicaciones de X busca Grok?

Sí, a través del aviso. Los operadores de búsqueda escritos en el aviso se propagan en la consulta que Grok emite: un aviso que contenga from:NASA y since:2026-07-01 produjo la llamada a la herramienta query: from:NASA Artemis since:2026-07-01. Lee tool_usages después de cada ejecución para confirmar qué se buscó.

P: ¿Cómo reconstruyo un enlace a la publicación original?

Combina dos campos siempre poblados: https://x.com/<user_name>/status/<post_id>. Mantén post_id como una cadena — es lo suficientemente larga como para perder precisión si un analizador JSON lo lee como un número de punto flotante.

P: ¿Devuelve MODEL_MODE_EXPERT más publicaciones de X que MODEL_MODE_FAST?

No de manera confiable. Dos ejecuciones emparejadas en un aviso idéntico devolvieron 15 publicaciones bajo FAST y 20 bajo EXPERT, luego 25 bajo FAST y 15 bajo EXPERT. La variación de ejecución a ejecución fue mayor que la diferencia entre modos. Elige un modo y manténlo constante para que una serie rastreada siga siendo comparable.

P: ¿En qué se diferencia esto de recopilar publicaciones directamente de la plataforma?

Alcance y selección. Esta ruta devuelve las publicaciones que una respuesta citó — una muestra filtrada editorialmente, típicamente de 3 a 35 publicaciones, con la consulta del modelo adjunta. La recopilación directa apunta a la completitud en su lugar. Usa esto cuando la pregunta sea qué surfacing y acreditó un motor de respuestas; usa una ruta de colección dedicada cuando necesites una cobertura exhaustiva de un hashtag o cuenta.

P: ¿Qué debo tener en cuenta sobre los datos de la publicación en sí?
El texto de las publicaciones y los nombres de los autores son contenido público creado por personas reales, así que trata una captura almacenada como un conjunto de datos sobre individuos. Mantén la colección limitada y con propósito, retén solo los campos que tu análisis necesita, y verifica si el Reglamento General de Protección de Datos de la UE o un régimen comparable se aplica a tu uso, especialmente antes de volver a publicar el texto de las publicaciones o las imágenes de perfil. Los términos de la plataforma rigen la reutilización independientemente de la ley de protección de datos; revisa ambos y consulta a un abogado para tu caso específico.

P: ¿Necesito un proxy?

No. La salida residencial vinculada por país está integrada en el actor, y la entrada requerida country es toda la configuración.