XThread di TwitterRisposte annidateID conversazioneTutorial API

Twitter Thread API: contesto e risposte annidate

Ottieni il contesto dei thread di Twitter/X con SocQ. Raggruppa le conversazioni, collega le risposte e filtra i thread degli autori con codice Python, poi esporta il JSON per la revisione.

SocQAggiornato il 16 ottobre 202610 min di lettura

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-context e leggi le pagine di risultati dell’attività completata. Raggruppa per conversation_id e collega i genitori diretti tramite in_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 serveEndpoint di SocQInput di partenza
Il post selezionatoX PostsURL di post pubblici
Le risposte a un post selezionatoX Post RepliesURL di post pubblici
Il post di destinazione, i post precedenti della catena di risposte e le risposte disponibiliX Thread ContextURL di post pubblici
I post condivisi all’interno di una communityX Community PostsURL 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:

CampoSignificatoElaborazione
conversation_idLa conversazione che contiene il postRaggruppa i record con lo stesso valore
in_reply_to_idL’ID del post genitore direttoCerca quell’ID e collega i post
idL’identificatore del post correnteIndicizza e deduplica i post

I dati seguenti, a titolo di esempio, spiegano le relazioni:

PostAutoreConversazioneGenitore diretto
AAliceANessuno indicato
BAliceAA
CBobAB
DAliceAC

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_dataset che 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.

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

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