Reúna con SocQ las publicaciones objetivo, el contexto previo y las relaciones de respuesta. Organice las conversaciones de Twitter/X según quién respondió a quién y luego use los ID de conversación y de publicación padre directa para la lectura, la revisión, los resúmenes y el filtrado de hilos de autor.
La API X Thread Context de SocQ consulta la publicación pública objetivo, las publicaciones anteriores de la cadena de respuestas y las respuestas devueltas por la fuente. Esta guía cubre la recolección, la agrupación de conversaciones, las exportaciones de relaciones padre-hijo y el filtrado de hilos de autor.
Respuesta rápida: Envíe la URL de una publicación pública a
POST /v1/x/thread-contexty lea las páginas de resultados de la tarea completada. Agrupe porconversation_idy conecte los padres directos conin_reply_to_id. Cuando falte el contenido de un padre, conserve su referencia y marque el vacío.
Elija entre consulta de publicación, respuestas o contexto del hilo
| Lo que necesita | Endpoint de SocQ | Entrada inicial |
|---|---|---|
| La publicación seleccionada | X Posts | URL de publicaciones públicas |
| Las respuestas a una publicación seleccionada | X Post Replies | URL de publicaciones públicas |
| La publicación objetivo, las publicaciones anteriores de la cadena de respuestas y las respuestas disponibles | X Thread Context | URL de publicaciones públicas |
| Las publicaciones compartidas dentro de una comunidad | X Community Posts | URL de comunidades públicas |
Use Thread Context para leer la conversación previa a la publicación seleccionada. Las “publicaciones anteriores” son las que se alcanzan siguiendo hacia atrás las relaciones de padre directo.
Por ejemplo, si B responde a A y C responde a B, la cadena de padres de C es C → B → A. Los ID de conversación determinan la agrupación, los ID de las publicaciones padre determinan las conexiones y las fechas de publicación definen el orden cronológico de visualización.
Después de la recolección, pase el texto y los datos de relaciones a una interfaz de lectura o a un flujo de trabajo de resumen independiente.
Obtenga el contexto del hilo a partir de la URL de una publicación pública
Use una URL pública con el formato /status/{numeric_id} y reemplace el ejemplo por la publicación que desea investigar:
curl -X POST "https://api.socq.ai/v1/x/thread-context" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://x.com/BaganiTohid/status/2110635249889919362"],
"results_limit": 100
}'
La entrada acepta enlaces de publicaciones públicas de X y Twitter, incluida una respuesta ubicada a la mitad de una conversación. Coloque en urls la URL completa /status/{numeric_id}.
El campo data.task_id de la respuesta identifica la tarea en segundo plano. Consérvelo y consulte:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Espere mientras la tarea esté en queued, running o retrying. Si pasa a failed, revise data.error_message. Cuando llegue a succeeded, lea data.results.items y continúe con next_cursor mientras has_more sea verdadero.
results_limit tiene un valor predeterminado de 100 y acepta enteros de 1 a 2000 por cada URL de entrada. Dos URL con un tope de 100 cada una solicitan hasta 100 registros de forma independiente. Elimine los duplicados por ID de publicación al combinar capturas de una misma conversación.
Thread Context acepta cualquier entero dentro de ese rango de límites. Arme las conexiones padre-hijo a partir de los campos de relación después de la recuperación y use el orden del arreglo para recorrer los registros.
Entienda los ID de conversación y los ID de publicación padre
Los dos campos de relación cumplen funciones distintas:
| Campo | Significado | Procesamiento |
|---|---|---|
conversation_id | La conversación que contiene la publicación | Agrupar los registros con el mismo valor |
in_reply_to_id | El ID de la publicación padre directa | Buscar ese ID y conectar las publicaciones |
id | El identificador de la publicación actual | Indexar y eliminar duplicados de las publicaciones |
Los siguientes datos ilustrativos explican las relaciones:
| Publicación | Autor | Conversación | Padre directo |
|---|---|---|---|
| A | Alice | A | Ninguno indicado |
| B | Alice | A | A |
| C | Bob | A | B |
| D | Alice | A | C |
Las cuatro publicaciones pertenecen a la conversación A, y el padre directo de D es C. Conectar por ID de padre conserva la ruta de respuestas D → C → B → A.
Consulte la referencia de campos de Thread Context para ver las definiciones. Use el ID de conversación y el ID de padre directo para los pasos de agrupación y de vinculación, respectivamente.
Los registros estándar también contienen texto, autores, fechas de publicación y de recolección, contenido multimedia y conteos de interacción. Los campos que la fuente omite permanecen en null.
Recolecte las páginas de resultados almacenadas con Python
Guarde este asistente, que usa solo la biblioteca estándar, como socq_collect.py:
import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}
def api(method, path, payload=None):
body = json.dumps(payload).encode("utf-8") if payload is not None else None
request = Request(
BASE + path, data=body, method=method,
headers={
"Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=60) as response:
result = json.load(response)
if result.get("code") != 200:
raise RuntimeError(result)
return result["data"]
def collect(endpoint, payload):
task_id = api("POST", "/" + endpoint, payload)["task_id"]
print("Task:", task_id, flush=True)
path = "/tasks/" + task_id
deadline = time.monotonic() + 600
data = api("GET", path + "?limit=100")
while data["status"] in PENDING:
if time.monotonic() >= deadline:
raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
time.sleep(2)
data = api("GET", path + "?limit=100")
if data["status"] != "succeeded":
raise RuntimeError(data.get("error_message") or data["status"])
items, seen_cursors = [], set()
while True:
if time.monotonic() >= deadline:
raise TimeoutError("Resume pagination for " + task_id)
page = data["results"]
items.extend(page["items"])
if not page["has_more"]:
return task_id, items
cursor = page.get("next_cursor")
if not cursor or cursor in seen_cursors:
raise RuntimeError("Missing or repeated result cursor")
seen_cursors.add(cursor)
data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
if data["status"] != "succeeded":
raise RuntimeError("Task is not ready for result pagination")
Guarde el siguiente script como collect_thread.py en el mismo directorio:
import json
import sys
from socq_collect import collect
if len(sys.argv) != 2:
raise SystemExit("Usage: python3 collect_thread.py PUBLIC_POST_URL")
payload = {"urls": [sys.argv[1]], "results_limit": 100}
task_id, posts = collect("x/thread-context", payload)
with open("thread-context.json", "w", encoding="utf-8") as output:
json.dump({"task_id": task_id, "input": payload, "items": posts},
output, ensure_ascii=False, indent=2)
Defina SOCQ_API_KEY y ejecútelo con la publicación pública seleccionada:
python3 collect_thread.py \
"https://x.com/BaganiTohid/status/2110635249889919362"
thread-context.json guarda los enlaces de entrada, el ID de la tarea y los registros. El asistente espera hasta diez minutos en el cliente. Después de un tiempo de espera agotado, conserve el ID de tarea impreso y siga consultando la tarea en el servidor.
La paginación lee los registros guardados por esa tarea. Al leer todas las páginas se obtiene el conjunto completo de resultados guardados; los registros y los marcadores de vacíos describen la cobertura de la conversación.
Arme las relaciones de respuesta por ID de padre directo
Indexe las publicaciones por ID y luego agregue los vínculos padre-hijo. Cuando falte el contenido de un padre referenciado, conserve el ID y establezca parent_in_dataset en false.
Guarde esto como build_thread.py:
import json
import sys
if len(sys.argv) not in (2, 3):
raise SystemExit("Usage: python3 build_thread.py INPUT_JSON [THREAD_AUTHOR_ID]")
with open(sys.argv[1], encoding="utf-8") as source:
records = json.load(source)["items"]
author_id = sys.argv[2] if len(sys.argv) == 3 else None
nodes, missing_id_records = {}, []
for post in records:
if post.get("id"):
nodes[str(post["id"])] = post
else:
missing_id_records.append(post)
edges, groups, unknown_conversation_ids, unknown_parent_ids = [], {}, [], []
for post_id, post in nodes.items():
conversation_id = post.get("conversation_id")
if conversation_id:
groups.setdefault(str(conversation_id), []).append(post_id)
else:
unknown_conversation_ids.append(post_id)
parent_id = post.get("in_reply_to_id")
if parent_id is None:
unknown_parent_ids.append(post_id)
else:
parent_id = str(parent_id)
edges.append({
"parent_id": parent_id, "child_id": post_id,
"parent_in_dataset": parent_id in nodes,
})
self_reply_edges = []
if author_id:
for edge in edges:
parent = nodes.get(edge["parent_id"])
child = nodes[edge["child_id"]]
if parent and edge["parent_id"] != edge["child_id"]:
parent_author = (parent.get("author") or {}).get("id")
child_author = (child.get("author") or {}).get("id")
if parent_author == author_id and child_author == author_id:
self_reply_edges.append(edge)
graph = {
"nodes": list(nodes.values()), "edges": edges, "conversation_groups": groups,
"missing_parent_ids": sorted({
edge["parent_id"] for edge in edges if not edge["parent_in_dataset"]
}),
"unknown_conversation_post_ids": unknown_conversation_ids,
"unknown_parent_post_ids": unknown_parent_ids,
"records_without_id": missing_id_records,
"selected_author_id": author_id, "selected_author_self_reply_edges": self_reply_edges,
}
with open("thread-graph.json", "w", encoding="utf-8") as output:
json.dump(graph, output, ensure_ascii=False, indent=2)
Genere la exportación de relaciones:
python3 build_thread.py thread-context.json
El archivo thread-graph.json resultante contiene:
- Nodos de publicaciones únicas e identificables, además de los registros sin ID, que se conservan por separado.
- Aristas padre-hijo, con
parent_in_datasetpara indicar si el padre está presente. - Grupos para los ID de conversación conocidos y una lista aparte para los ID de conversación faltantes.
- ID de padres referenciados que no tienen una publicación recolectada correspondiente.
- ID de publicaciones cuyo campo de padre directo es null.
in_reply_to_id=null significa que el registro no aporta una referencia de padre directo; el programa lo agrega a unknown_parent_post_ids. Cuando existe un ID de padre pero su registro no está en el índice, conserve la arista y marque el padre faltante.
La exportación conserva los grupos de conversación, las aristas conocidas y los marcadores de registros faltantes. Una interfaz de lectura puede mostrar por separado las ramas conectadas y los vacíos de contexto.
Separe el hilo de un autor de las respuestas de los lectores
En los datos ilustrativos, Alice escribió A, B y D. De A a B hay un segmento de autorrespuesta del autor, mientras que D es la respuesta de Alice a Bob. Filtre por ID de autor para leer todas las declaraciones del autor y luego verifique los ID de autor tanto del padre como del hijo para identificar los segmentos de autorrespuesta.
Cuando conozca el ID de la cuenta del autor del hilo, pase esa cadena como segundo argumento:
python3 build_thread.py thread-context.json THREAD_AUTHOR_ID
selected_author_self_reply_edges almacena las aristas cuyo padre e hijo pertenecen al autor especificado. Confirme ese ID de autor antes de filtrar; el enlace de entrada puede identificar la publicación del autor o la respuesta de un lector.
Seleccione un segmento conectado de autorrespuestas alrededor de la publicación del autor que desea leer. Si el autor tiene varias autorrespuestas a un mismo padre, la exportación conserva esas ramas para que la interfaz de lectura elija su alcance de visualización.
Conserve juntos los registros completos y la vista filtrada por autor, de modo que los filtros de lectura posteriores puedan usar los datos originales.
Exporte el contexto para lectura, revisión o resumen
Muestre en la interfaz de lectura las URL de origen, los autores, las fechas de publicación y las relaciones de padre, con marcadores para los padres faltantes. Guarde el JSON de relaciones junto a las exportaciones de texto o Markdown para reconstruir la estructura más adelante.
Un flujo de trabajo de resumen lee el texto de las publicaciones y las relaciones, trata por separado las declaraciones del autor y las respuestas de los lectores, y conserva los marcadores de vacíos de contexto. Thread Context aporta los registros; su modelo o su aplicación genera el resumen.
Al combinar tareas de una misma conversación, elimine los duplicados por ID de publicación y conserve sus enlaces de entrada y sus ID de tarea. Mantenga las publicaciones observadas anteriormente con sus fechas de captura originales cuando no aparezcan en una captura posterior.
Para descubrir conversaciones antes de examinarlas, use el tutorial de recolección de comunidades o la guía de búsqueda y recolección en X.
Use un solo conjunto de datos de contexto para lectura, revisión y resúmenes
SocQ Thread Context coloca el texto de las publicaciones y los ID de relación en los mismos resultados estándar. Use el código para agrupar conversaciones, exportar las relaciones de respuesta y construir una vista filtrada por autor. Las interfaces de lectura y los flujos de resumen pueden reutilizar esos registros junto con sus fuentes y sus marcadores de vacíos de contexto.
Abra Thread Context y explore la conversación que le interesa.
Fuentes y lecturas adicionales
- Documentación de SocQ Thread Context – entradas públicas, límites y campos estándar de relación.
Preguntas frecuentes (FAQ)
¿Puedo comenzar desde una respuesta en lugar de la primera publicación?
Sí. Coloque la URL pública de esa respuesta en urls. La tarea lee la publicación objetivo, las publicaciones públicas anteriores y las respuestas devueltas por la fuente hasta el límite configurado.
¿Es lo mismo que obtener las respuestas a una publicación?
Post Replies se centra en las respuestas a la publicación seleccionada. Thread Context lee la publicación objetivo, las publicaciones anteriores y las respuestas para organizar el contexto mediante las relaciones de respuesta.
¿La API devuelve todas las respuestas de una conversación?
La tarea recolecta registros públicos hasta el results_limit de cada entrada. Al leer todas las páginas se recuperan las publicaciones guardadas en esa captura; evalúe también la cobertura de la conversación con los registros de padres faltantes y de respuestas.
¿Cómo manejo las respuestas a respuestas?
Conecte los padres directos con in_reply_to_id y agrupe las conversaciones con conversation_id. Conserve el ID de un padre faltante y muestre un marcador de vacío.
¿Por qué falta un padre referenciado?
La referencia al padre se devolvió, pero su contenido no está en esta captura. Conserve la referencia y consulte esa publicación cuando necesite más contexto; use información reportada por la fuente para establecer un motivo específico de su ausencia.
¿Cómo conservo solo el hilo del autor original?
Confirme el ID del autor y conserve las aristas cuyo padre e hijo pertenezcan a ese autor. Seleccione un segmento conectado alrededor de la publicación objetivo y elija el alcance de visualización cuando las autorrespuestas se ramifiquen.
¿Puedo guardar el hilo para un resumen con IA?
Sí. Guarde el texto, los autores, las fechas y las relaciones recolectados como JSON y luego ejecute un paso de resumen independiente. Conserve junto al resumen los marcadores de contexto faltante y las URL de origen.
X API
Probar el flujo de trabajo con una URL pública de X
Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.
Ver las API de X