Riunisci con SocQ i post di destinazione, il contesto precedente e le relazioni tra le risposte. Organizza le discussioni di Twitter/X in base a chi ha risposto a chi, poi usa gli ID della conversazione e del genitore diretto per la lettura, la revisione, i riepiloghi e il filtraggio dei thread degli autori.
La X Thread Context API di SocQ interroga il post pubblico di destinazione, i post precedenti della catena di risposte e le risposte restituite dalla fonte. Questa guida copre la raccolta, il raggruppamento delle conversazioni, le esportazioni genitore-figlio e il filtraggio dei thread degli autori.
Risposta rapida: invia l’URL di un post pubblico a
POST /v1/x/thread-contexte leggi le pagine di risultati dell’attività completata. Raggruppa perconversation_ide collega i genitori diretti tramitein_reply_to_id. Quando il testo di un genitore è assente, conserva il riferimento e segna la lacuna.
Scegliere tra ricerca di post, risposte e contesto del thread
| Cosa ti serve | Endpoint di SocQ | Input di partenza |
|---|---|---|
| Il post selezionato | X Posts | URL di post pubblici |
| Le risposte a un post selezionato | X Post Replies | URL di post pubblici |
| Il post di destinazione, i post precedenti della catena di risposte e le risposte disponibili | X Thread Context | URL di post pubblici |
| I post condivisi all’interno di una community | X Community Posts | URL di community pubbliche |
Usa Thread Context per leggere la discussione che precede il post selezionato. “Post precedenti” indica i post raggiunti risalendo le relazioni con il genitore diretto.
Per esempio, se B risponde ad A e C risponde a B, la catena dei genitori di C è C → B → A. Gli ID della conversazione determinano il raggruppamento, gli ID dei post genitori determinano i collegamenti e gli orari di pubblicazione forniscono l’ordine cronologico di visualizzazione.
Dopo la raccolta, passa il testo e i dati sulle relazioni a un’interfaccia di lettura o a un flusso di riepilogo separato.
Recuperare il contesto di un thread da un URL di post pubblico
Usa un URL pubblico /status/{numeric_id}, sostituendo l’esempio con il post che vuoi analizzare:
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’input accetta link pubblici ai post di X e Twitter, compresa una risposta presa dal mezzo di una discussione. Inserisci in urls l’URL completo /status/{numeric_id}.
data.task_id nella risposta identifica l’attività in background. Conservalo e richiedi:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Attendi finché l’attività è queued, running o retrying. In caso di failed, controlla data.error_message. Quando è succeeded, leggi data.results.items e continua con next_cursor finché has_more è true.
results_limit ha come valore predefinito 100 e accetta interi da 1 a 2.000 per ogni URL di input. Due URL con un tetto di 100 richiedono ciascuno fino a 100 record in modo indipendente. Quando unisci acquisizioni della stessa conversazione, deduplica per ID del post.
Thread Context accetta qualsiasi intero entro quell’intervallo. Dopo il recupero, costruisci i collegamenti genitore-figlio a partire dai campi delle relazioni e usa l’ordine dell’array per scorrere i record.
Capire gli ID della conversazione e dei post genitori
I due campi delle relazioni hanno scopi diversi:
| Campo | Significato | Elaborazione |
|---|---|---|
conversation_id | La conversazione che contiene il post | Raggruppa i record con lo stesso valore |
in_reply_to_id | L’ID del post genitore diretto | Cerca quell’ID e collega i post |
id | L’identificatore del post corrente | Indicizza e deduplica i post |
I dati seguenti, a titolo di esempio, spiegano le relazioni:
| Post | Autore | Conversazione | Genitore diretto |
|---|---|---|---|
| A | Alice | A | Nessuno indicato |
| B | Alice | A | A |
| C | Bob | A | B |
| D | Alice | A | C |
Tutti e quattro i post appartengono alla conversazione A e il genitore diretto di D è C. Collegare i post tramite l’ID del genitore conserva il percorso di risposta D → C → B → A.
Per le definizioni consulta il riferimento dei campi di Thread Context. Usa l’ID della conversazione e l’ID del genitore diretto rispettivamente per le fasi di raggruppamento e di collegamento.
I record standard contengono anche testo, autori, orari di pubblicazione e di raccolta, contenuti multimediali e conteggi di engagement. I campi omessi dalla fonte restano null.
Raccogliere le pagine di risultati salvate con Python
Salva questo helper, basato sulla libreria standard, come 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")
Salva lo script successivo come collect_thread.py nella stessa directory:
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)
Imposta SOCQ_API_KEY, poi eseguilo con il post pubblico selezionato:
python3 collect_thread.py \
"https://x.com/BaganiTohid/status/2110635249889919362"
thread-context.json salva i link di input, l’ID attività e i record. L’helper attende fino a dieci minuti sul client. Dopo un timeout, conserva l’ID attività stampato e continua a controllare l’attività sul server.
La paginazione legge i record salvati da quell’attività. Leggendo tutte le pagine ottieni l’intero insieme di risultati salvato; i record e i segnalatori di lacune descrivono la copertura della conversazione.
Costruire le relazioni tra risposte tramite l’ID del genitore diretto
Indicizza i post per ID, poi aggiungi i collegamenti genitore-figlio. Quando il testo di un genitore a cui si fa riferimento è assente, conserva l’ID e imposta parent_in_dataset su false.
Salva questo script come 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)
Genera l’esportazione delle relazioni:
python3 build_thread.py thread-context.json
Il file thread-graph.json risultante contiene:
- Nodi dei post unici e identificabili, più i record senza ID conservati a parte.
- Collegamenti genitore-figlio, con
parent_in_datasetche indica se il genitore è presente. - Gruppi per gli ID di conversazione noti e un elenco separato per quelli mancanti.
- ID dei genitori a cui si fa riferimento che non hanno un post raccolto corrispondente.
- ID dei post il cui campo del genitore diretto è null.
in_reply_to_id=null significa che il record non fornisce alcun riferimento al genitore diretto; il programma lo aggiunge a unknown_parent_post_ids. Quando esiste un ID del genitore ma il suo record è assente dall’indice, conserva il collegamento e segna il genitore mancante.
L’esportazione conserva i gruppi di conversazione, i collegamenti noti e i segnalatori dei record mancanti. Un’interfaccia di lettura può mostrare separatamente i rami collegati e le lacune di contesto.
Tenere separato il thread di un autore dalle risposte dei lettori
Nei dati di esempio, Alice ha scritto A, B e D. Da A a B c’è un segmento di risposta dell’autore a se stesso, mentre D è la risposta di Alice a Bob. Filtra per ID dell’autore per leggere tutti gli interventi dell’autore, poi controlla gli ID dell’autore sia del genitore sia del figlio per individuare i segmenti di auto-risposta.
Quando conosci l’ID dell’account dell’autore del thread, passa quella stringa come secondo argomento:
python3 build_thread.py thread-context.json THREAD_AUTHOR_ID
selected_author_self_reply_edges contiene i collegamenti in cui genitore e figlio appartengono all’autore indicato. Conferma quell’ID dell’autore prima di filtrare; il link di input può identificare il post dell’autore o la risposta di un lettore.
Seleziona un segmento di auto-risposta connesso attorno al post dell’autore che vuoi leggere. Se l’autore ha più auto-risposte allo stesso genitore, l’esportazione conserva quei rami, così l’interfaccia di lettura può scegliere l’ambito da mostrare.
Conserva insieme i record completi e la vista filtrata per autore, in modo che i filtri di lettura successivi possano usare i dati originali.
Esportare il contesto per lettura, revisione o riepilogo
Nell’interfaccia di lettura mostra URL di origine, autori, orari di pubblicazione e relazioni con i genitori, con segnalatori per i genitori mancanti. Salva il JSON delle relazioni accanto alle esportazioni in testo o Markdown per poter ricostruire la struttura in un secondo momento.
Un flusso di riepilogo legge il testo dei post e le relazioni, tratta separatamente gli interventi dell’autore e le risposte dei lettori e conserva i segnalatori delle lacune di contesto. Thread Context fornisce i record; il riepilogo viene generato dal tuo modello o dalla tua applicazione.
Quando unisci attività della stessa conversazione, deduplica per ID del post e conserva i link di input e gli ID attività. Mantieni i post già osservati con i loro orari di acquisizione originali quando sono assenti da una raccolta successiva.
Per individuare le discussioni prima di analizzarle, usa il tutorial sulla raccolta dei post delle community o la guida alla ricerca e alla raccolta su X.
Usare un unico dataset di contesto per lettura, revisione e riepiloghi
SocQ Thread Context riunisce il testo dei post e gli ID delle relazioni negli stessi risultati standard. Usa il codice per raggruppare le conversazioni, esportare le relazioni tra le risposte e costruire una vista filtrata per autore. Le interfacce di lettura e i flussi di riepilogo possono riutilizzare quei record con le loro fonti e i segnalatori delle lacune di contesto.
Apri Thread Context ed esplora la discussione che ti interessa.
Fonti e letture di approfondimento
- Documentazione di SocQ Thread Context – input pubblici, limiti e campi standard delle relazioni.
Domande frequenti (FAQ)
Posso partire da una risposta invece che dal primo post?
Sì. Inserisci in urls l’URL di quella risposta pubblica. L’attività legge il post di destinazione, i post precedenti pubblici e le risposte restituite dalla fonte fino al limite configurato.
È lo stesso che ottenere le risposte a un post?
Post Replies si concentra sulle risposte al post selezionato. Thread Context legge il post di destinazione, i post precedenti e le risposte per organizzare il contesto tramite le relazioni tra le risposte.
L’API restituisce tutte le risposte di una conversazione?
L’attività raccoglie i record pubblici fino al valore results_limit di ogni input. Leggendo tutte le pagine si recuperano i post salvati in quell’acquisizione; valuta la copertura della discussione guardando anche i genitori mancanti e i record delle risposte.
Come gestisco le risposte alle risposte?
Collega i genitori diretti con in_reply_to_id e raggruppa le conversazioni con conversation_id. Conserva l’ID di un genitore mancante e mostra un segnalatore di lacuna.
Perché un genitore a cui si fa riferimento risulta mancante?
Il riferimento al genitore è stato restituito, ma il suo testo è assente da questa acquisizione. Conserva il riferimento e interroga quel post quando ti serve più contesto; per stabilire un motivo specifico della sua assenza usa le informazioni indicate dalla fonte.
Come tengo solo il thread dell’autore originale?
Conferma l’ID dell’autore e conserva i collegamenti in cui genitore e figlio appartengono entrambi a quell’autore. Seleziona un segmento connesso attorno al post di destinazione e scegli l’ambito da mostrare quando le auto-risposte si ramificano.
Posso salvare il thread per un riepilogo con l’AI?
Sì. Salva in JSON testo, autori, orari e relazioni raccolti, poi esegui un passaggio di riepilogo separato. Conserva accanto al riepilogo i segnalatori del contesto mancante e gli URL di origine.
X API
Prova il flusso di lavoro con un URL pubblico di X
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di X