Réunissez avec SocQ les posts ciblés, le contexte qui les précède et les relations de réponse. Organisez les discussions Twitter/X selon qui répond à qui, puis utilisez les identifiants de conversation et de parent direct pour la lecture, la relecture, les résumés et le filtrage des threads d’auteur.
SocQ X Thread Context API interroge le post public ciblé, les posts antérieurs de la chaîne de réponses et les réponses renvoyées par la source. Ce guide couvre la collecte, le regroupement par conversation, les exports parent-enfant et le filtrage des threads d’auteur.
Réponse rapide : envoyez l’URL d’un post public à
POST /v1/x/thread-contextet lisez les pages de résultats de la tâche terminée. Regroupez parconversation_idet reliez les parents directs avecin_reply_to_id. Lorsque le contenu d’un parent est absent, conservez sa référence et signalez le vide.
Choisir entre la consultation d’un post, les réponses et le contexte de thread
| Ce dont vous avez besoin | Endpoint SocQ | Entrée de départ |
|---|---|---|
| Le post sélectionné lui-même | X Posts | URL de posts publics |
| Les réponses à un post sélectionné | X Post Replies | URL de posts publics |
| Le post ciblé, les posts antérieurs de la chaîne de réponses et les réponses disponibles | X Thread Context | URL de posts publics |
| Les posts partagés dans une communauté | X Community Posts | URL de communautés publiques |
Utilisez Thread Context pour lire la discussion qui précède le post sélectionné. Les « posts antérieurs » désignent les posts atteints en remontant les relations de parent direct.
Par exemple, si B répond à A et C répond à B, la chaîne de parents de C est C → B → A. Les identifiants de conversation déterminent le regroupement, les identifiants de post parent déterminent les liens, et les dates de publication fournissent l’ordre d’affichage chronologique.
Après la collecte, transmettez le texte et les données de relation à une interface de lecture ou à un workflow de résumé distinct.
Récupérer le contexte d’un thread à partir de l’URL d’un post public
Utilisez une URL publique /status/{numeric_id}, en remplaçant l’exemple par le post que vous souhaitez étudier :
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
}'
L’entrée accepte les liens de posts publics X et Twitter, y compris celui d’une réponse située au milieu d’une discussion. Placez l’URL complète /status/{numeric_id} dans urls.
Le champ data.task_id de la réponse identifie la tâche en arrière-plan. Conservez-le et envoyez :
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Patientez tant que la tâche est queued, running ou retrying. En cas de failed, examinez data.error_message. Une fois succeeded, lisez data.results.items et poursuivez avec next_cursor tant que has_more vaut true.
results_limit vaut 100 par défaut et accepte des entiers de 1 à 2 000 pour chaque URL d’entrée. Deux URL avec un plafond de 100 chacune demandent jusqu’à 100 enregistrements de façon indépendante. Dédupliquez par ID de post lorsque vous fusionnez des captures d’une même conversation.
Thread Context accepte tout entier compris dans cette plage de limites. Construisez les liens parent-enfant à partir des champs de relation après la récupération, et utilisez l’ordre du tableau pour parcourir les enregistrements.
Comprendre les identifiants de conversation et de post parent
Les deux champs de relation ont des rôles différents :
| Champ | Signification | Traitement |
|---|---|---|
conversation_id | La conversation qui contient le post | Regrouper les enregistrements ayant la même valeur |
in_reply_to_id | L’ID du post parent direct | Rechercher cet ID et relier les posts |
id | L’identifiant du post courant | Indexer et dédupliquer les posts |
Les données illustratives suivantes expliquent les relations :
| Post | Auteur | Conversation | Parent direct |
|---|---|---|---|
| A | Alice | A | Aucun indiqué |
| B | Alice | A | A |
| C | Bob | A | B |
| D | Alice | A | C |
Les quatre posts appartiennent à la conversation A, et le parent direct de D est C. Relier par ID de parent préserve le chemin de réponses D → C → B → A.
Consultez la référence des champs de Thread Context pour les définitions. Utilisez l’identifiant de conversation et l’identifiant de parent direct pour, respectivement, les étapes de regroupement et de liaison.
Les enregistrements standard contiennent aussi le texte, les auteurs, les dates de publication et de collecte, les médias et les compteurs d’engagement. Les champs omis par la source restent à null.
Collecter les pages de résultats stockées avec Python
Enregistrez cet utilitaire, qui n’utilise que la bibliothèque standard, sous le nom 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")
Enregistrez le script suivant sous le nom collect_thread.py dans le même répertoire :
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)
Définissez SOCQ_API_KEY, puis exécutez-le avec le post public choisi :
python3 collect_thread.py \
"https://x.com/BaganiTohid/status/2110635249889919362"
thread-context.json enregistre les liens d’entrée, l’ID de tâche et les enregistrements. L’utilitaire attend jusqu’à dix minutes côté client. Après un délai d’expiration, conservez l’ID de tâche affiché et continuez à interroger la tâche côté serveur.
La pagination lit les enregistrements sauvegardés par cette tâche. Lire toutes les pages vous donne l’ensemble complet des résultats enregistrés ; les enregistrements et les marqueurs de vide décrivent la couverture de la conversation.
Construire les relations de réponse par ID de parent direct
Indexez les posts par ID, puis ajoutez les liens parent-enfant. Lorsque le contenu d’un parent référencé est absent, conservez l’ID et définissez parent_in_dataset sur false.
Enregistrez ceci sous le nom 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)
Construisez l’export des relations :
python3 build_thread.py thread-context.json
Le fichier thread-graph.json obtenu contient :
- Des nœuds de posts uniques et identifiables, plus les enregistrements sans ID conservés séparément.
- Des arêtes parent-enfant, avec
parent_in_datasetindiquant si le parent est présent. - Des groupes pour les identifiants de conversation connus et une liste distincte pour les identifiants de conversation manquants.
- Les ID de parents référencés qui n’ont aucun post collecté correspondant.
- Les ID de posts dont le champ de parent direct est null.
in_reply_to_id=null signifie que l’enregistrement ne fournit aucune référence de parent direct ; le programme l’ajoute à unknown_parent_post_ids. Lorsqu’un ID de parent existe mais que son enregistrement est absent de l’index, conservez l’arête et signalez le parent manquant.
L’export préserve les groupes de conversation, les arêtes connues et les marqueurs d’enregistrements manquants. Une interface de lecture peut afficher séparément les branches connectées et les vides de contexte.
Distinguer le thread d’un auteur des réponses des lecteurs
Dans les données illustratives, Alice a écrit A, B et D. Le passage de A à B est un segment d’auto-réponse de l’auteur, tandis que D est la réponse d’Alice à Bob. Filtrez par ID d’auteur pour lire toutes les interventions de l’auteur, puis vérifiez les ID d’auteur du parent et de l’enfant pour repérer les segments d’auto-réponse.
Lorsque vous connaissez l’ID du compte de l’auteur du thread, transmettez cette chaîne comme second argument :
python3 build_thread.py thread-context.json THREAD_AUTHOR_ID
selected_author_self_reply_edges stocke les arêtes dont le parent et l’enfant appartiennent à l’auteur indiqué. Confirmez cet ID d’auteur avant de filtrer ; le lien d’entrée peut identifier un post de l’auteur ou la réponse d’un lecteur.
Sélectionnez un segment d’auto-réponses connecté autour du post de l’auteur que vous souhaitez lire. Si l’auteur a plusieurs auto-réponses à un même parent, l’export conserve ces branches afin que l’interface de lecture puisse choisir sa portée d’affichage.
Conservez ensemble les enregistrements complets et la vue filtrée par auteur, afin que les filtres de lecture ultérieurs puissent s’appuyer sur les données d’origine.
Exporter le contexte pour la lecture, la relecture ou le résumé
Affichez dans l’interface de lecture les URL sources, les auteurs, les dates de publication et les relations de parenté, avec des marqueurs pour les parents manquants. Enregistrez le JSON des relations à côté des exports texte ou Markdown pour reconstituer la structure plus tard.
Un workflow de résumé lit le texte des posts et les relations, traite séparément les interventions de l’auteur et les réponses des lecteurs, et conserve les marqueurs de vide de contexte. Thread Context fournit les enregistrements ; c’est votre modèle ou votre application qui génère le résumé.
Lorsque vous fusionnez des tâches issues d’une même conversation, dédupliquez par ID de post et conservez leurs liens d’entrée et leurs ID de tâche. Gardez les posts déjà observés avec leur date de capture d’origine lorsqu’ils sont absents d’une capture ultérieure.
Pour repérer des discussions avant de les examiner, utilisez le tutoriel de collecte de communautés ou le guide de recherche et de collecte X.
Utiliser un seul jeu de données de contexte pour la lecture, la relecture et les résumés
SocQ Thread Context place le texte des posts et les ID de relation dans les mêmes résultats standard. Utilisez le code pour regrouper les conversations, exporter les relations de réponse et construire une vue filtrée par auteur. Les interfaces de lecture et les workflows de résumé peuvent réutiliser ces enregistrements avec leurs sources et leurs marqueurs de vide de contexte.
Ouvrir Thread Context et explorer la discussion ciblée.
Sources et lectures complémentaires
- Documentation de SocQ Thread Context – entrées publiques, plafonds et champs de relation standard.
FAQ
Puis-je partir d’une réponse plutôt que du premier post ?
Oui. Placez l’URL de cette réponse publique dans urls. La tâche lit le post ciblé, les posts antérieurs publics et les réponses renvoyées par la source, dans la limite du plafond configuré.
Est-ce la même chose que d’obtenir les réponses à un post ?
Post Replies se concentre sur les réponses au post sélectionné. Thread Context lit le post ciblé, les posts antérieurs et les réponses afin d’organiser le contexte à travers les relations de réponse.
L’API renvoie-t-elle toutes les réponses d’une conversation ?
La tâche collecte des enregistrements publics jusqu’au results_limit de chaque entrée. Lire toutes les pages récupère les posts enregistrés dans cette capture ; évaluez aussi la couverture de la discussion à l’aide des parents manquants et des enregistrements de réponses.
Comment gérer les réponses à des réponses ?
Reliez les parents directs avec in_reply_to_id et regroupez les conversations avec conversation_id. Conservez l’ID d’un parent manquant et affichez un marqueur de vide.
Pourquoi un parent référencé est-il manquant ?
La référence du parent a été renvoyée, mais son contenu est absent de cette capture. Conservez la référence et interrogez ce post lorsque vous avez besoin de plus de contexte ; appuyez-vous sur les informations signalées par la source pour établir une raison précise de son absence.
Comment ne conserver que le thread de l’auteur d’origine ?
Confirmez l’ID de l’auteur et conservez les arêtes dont le parent et l’enfant appartiennent tous deux à cet auteur. Sélectionnez un segment connecté autour du post ciblé et choisissez la portée d’affichage lorsque les auto-réponses se ramifient.
Puis-je enregistrer le thread pour un résumé par IA ?
Oui. Enregistrez le texte collecté, les auteurs, les dates et les relations au format JSON, puis lancez une étape de résumé distincte. Conservez les marqueurs de contexte manquant et les URL sources avec le résumé.
X API
Tester le workflow avec une URL publique X
Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.
Découvrir les API X