SocQ로 대상 게시물, 앞선 맥락, 답글 관계를 한데 모아 보세요. Twitter/X 토론을 누가 누구에게 답했는지를 기준으로 정리하고, 대화 ID와 직접 상위 게시물 ID를 이용해 읽기, 검토, 요약, 작성자 스레드 필터링에 활용할 수 있습니다.
SocQ X Thread Context API는 대상 공개 게시물, 앞선 답글 체인의 게시물, 원본에서 반환된 답글을 조회합니다. 이 가이드에서는 수집, 대화 단위 그룹화, 부모-자식 관계 내보내기, 작성자 스레드 필터링을 다룹니다.
빠른 답변: 공개 게시물 URL을
POST /v1/x/thread-context로 제출하고, 완료된 작업의 결과 페이지를 읽으세요.conversation_id로 묶고in_reply_to_id로 직접 상위 게시물을 연결합니다. 상위 게시물의 본문이 없으면 참조는 그대로 두고 빈 부분임을 표시하세요.
게시물 조회, 답글, 스레드 컨텍스트 중 고르기
| 필요한 것 | SocQ 엔드포인트 | 시작 입력 |
|---|---|---|
| 선택한 게시물 자체 | X Posts | 공개 게시물 URL |
| 선택한 게시물에 달린 답글 | X Post Replies | 공개 게시물 URL |
| 대상 게시물, 앞선 답글 체인의 게시물, 조회 가능한 답글 | X Thread Context | 공개 게시물 URL |
| 커뮤니티 안에서 공유된 게시물 | X Community Posts | 공개 커뮤니티 URL |
선택한 게시물에 앞선 토론을 읽으려면 Thread Context를 사용하세요. "앞선 게시물"은 직접 상위 게시물 관계를 거꾸로 따라가면 나오는 게시물을 뜻합니다.
예를 들어 B가 A에 답하고 C가 B에 답했다면, C의 상위 체인은 C → B → A입니다. 그룹화는 대화 ID로, 연결은 상위 게시물 ID로 정하며, 게시 시각은 시간순 표시 순서를 알려 줍니다.
수집이 끝나면 텍스트와 관계 데이터를 읽기 화면이나 별도의 요약 워크플로에 넘기세요.
공개 게시물 URL로 스레드 컨텍스트 가져오기
공개 /status/{numeric_id} URL을 사용하세요. 예시 URL은 조사하려는 게시물로 바꾸면 됩니다.
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
}'
입력에는 토론 중간에 있는 답글을 포함해 공개 X 및 Twitter 게시물 링크를 넣을 수 있습니다. urls에는 /status/{numeric_id}를 포함한 전체 URL을 넣으세요.
응답의 data.task_id가 백그라운드 작업을 식별합니다. 이 값을 보관해 두고 다음과 같이 요청하세요.
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
작업이 queued, running, retrying인 동안에는 기다리세요. failed이면 data.error_message를 확인합니다. succeeded가 되면 data.results.items를 읽고, has_more가 true인 동안 next_cursor로 계속 가져옵니다.
results_limit의 기본값은 100이며, 입력 URL마다 1부터 2000까지의 정수를 받습니다. 상한이 각각 100인 URL 두 개는 서로 독립적으로 최대 100개씩 레코드를 요청합니다. 같은 대화를 여러 번 수집해 합칠 때는 게시물 ID로 중복을 제거하세요.
Thread Context는 이 범위 안의 어떤 정수든 받습니다. 부모-자식 연결은 수집 후 관계 필드로 만들고, 레코드는 배열 순서대로 순회하세요.
대화 ID와 상위 게시물 ID 이해하기
두 관계 필드는 쓰임새가 서로 다릅니다.
| 필드 | 의미 | 처리 방법 |
|---|---|---|
conversation_id | 게시물이 속한 대화 | 같은 값의 레코드를 묶기 |
in_reply_to_id | 직접 상위 게시물의 ID | 해당 ID를 찾아 게시물을 연결하기 |
id | 현재 게시물의 식별자 | 게시물 인덱싱과 중복 제거 |
다음 예시 데이터로 관계를 설명합니다.
| 게시물 | 작성자 | 대화 | 직접 상위 게시물 |
|---|---|---|---|
| A | Alice | A | 표시 없음 |
| B | Alice | A | A |
| C | Bob | A | B |
| D | Alice | A | C |
네 게시물 모두 대화 A에 속하고, D의 직접 상위 게시물은 C입니다. 상위 게시물 ID로 연결하면 D → C → B → A의 답글 경로가 그대로 유지됩니다.
정의는 Thread Context 필드 레퍼런스를 참고하세요. 그룹화에는 대화 ID를, 연결에는 직접 상위 게시물 ID를 각각 사용하세요.
표준 레코드에는 텍스트, 작성자, 게시 및 수집 시각, 미디어, 참여 수치도 들어 있습니다. 원본에서 생략된 필드는 null로 남습니다.
Python으로 저장된 결과 페이지 수집하기
표준 라이브러리만 쓰는 이 도우미를 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")
다음 스크립트는 같은 디렉터리에 collect_thread.py로 저장하세요.
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)
SOCQ_API_KEY를 설정한 뒤, 선택한 공개 게시물로 실행합니다.
python3 collect_thread.py \
"https://x.com/BaganiTohid/status/2110635249889919362"
thread-context.json에는 입력 링크, 작업 ID, 레코드가 저장됩니다. 이 도우미는 클라이언트에서 최대 10분간 기다립니다. 타임아웃이 발생하면 출력된 작업 ID를 보관해 두고 서버 작업을 계속 확인하세요.
페이지네이션은 해당 작업이 저장해 둔 레코드를 읽습니다. 모든 페이지를 읽으면 저장된 결과 전체를 얻게 되며, 레코드와 빈 부분 표시가 대화의 포괄 범위를 보여 줍니다.
직접 상위 게시물 ID로 답글 관계 만들기
게시물을 ID로 인덱싱한 다음 부모-자식 링크를 추가하세요. 참조된 상위 게시물의 본문이 없으면 ID를 그대로 두고 parent_in_dataset을 false로 설정합니다.
다음 스크립트를 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)
관계 내보내기를 생성합니다.
python3 build_thread.py thread-context.json
생성된 thread-graph.json에는 다음이 들어 있습니다.
- ID로 식별되는 고유 게시물 노드, 그리고 ID가 없어 따로 보관한 레코드.
- 상위 게시물이 있는지를
parent_in_dataset으로 나타낸 부모-자식 엣지. - 대화 ID를 아는 게시물의 그룹과, 대화 ID가 없는 게시물의 별도 목록.
- 대응하는 수집 게시물이 없는, 참조된 상위 게시물 ID.
- 직접 상위 게시물 필드가 null인 게시물 ID.
in_reply_to_id=null은 레코드가 직접 상위 게시물 참조를 제공하지 않는다는 뜻이며, 프로그램은 이를 unknown_parent_post_ids에 추가합니다. 상위 게시물 ID는 있는데 인덱스에 해당 레코드가 없다면 엣지를 유지하고 누락된 상위 게시물임을 표시하세요.
이 내보내기는 대화 그룹, 확인된 엣지, 누락 레코드 표시를 모두 보존합니다. 읽기 화면에서는 연결된 가지와 맥락의 빈 부분을 따로 보여 줄 수 있습니다.
작성자의 스레드와 독자 답글 구분하기
예시 데이터에서 Alice는 A, B, D를 썼습니다. A에서 B로 이어지는 부분은 작성자 본인이 이어 쓴 구간이고, D는 Bob에게 한 Alice의 답글입니다. 작성자 ID로 필터링하면 그 작성자의 모든 발언을 읽을 수 있고, 상위·하위 게시물의 작성자 ID를 모두 확인하면 이어 쓴 구간을 가려낼 수 있습니다.
스레드 작성자의 계정 ID를 알고 있다면 그 문자열을 두 번째 인자로 넘기세요.
python3 build_thread.py thread-context.json THREAD_AUTHOR_ID
selected_author_self_reply_edges에는 상위 게시물과 하위 게시물이 모두 지정한 작성자의 것인 엣지가 저장됩니다. 필터링하기 전에 작성자 ID를 꼭 확인하세요. 입력 링크는 작성자의 게시물일 수도 있고 독자의 답글일 수도 있습니다.
읽으려는 작성자 게시물을 중심으로, 서로 이어진 본인 답글 구간을 선택하세요. 작성자가 하나의 상위 게시물에 본인 답글을 여러 개 달았다면, 내보내기는 그 가지들을 그대로 유지하므로 읽기 화면에서 표시 범위를 고를 수 있습니다.
전체 레코드와 작성자 기준으로 필터링한 뷰를 함께 보관하면, 나중에 읽기 필터를 바꿔도 원본 데이터를 그대로 쓸 수 있습니다.
읽기, 검토, 요약을 위한 맥락 내보내기
읽기 화면에는 출처 URL, 작성자, 게시 시각, 상위 게시물 관계를 표시하고, 상위 게시물이 없는 곳에는 표시를 넣으세요. 관계 JSON은 텍스트나 Markdown 내보내기와 나란히 저장해 두면 나중에 구조를 다시 구성할 수 있습니다.
요약 워크플로는 게시물 텍스트와 관계를 읽고, 작성자의 발언과 독자의 반응을 따로 처리하며, 맥락의 빈 부분 표시를 유지합니다. Thread Context가 레코드를 제공하고, 요약은 사용자의 모델이나 애플리케이션이 생성합니다.
같은 대화에서 가져온 작업을 합칠 때는 게시물 ID로 중복을 제거하고 입력 링크와 작업 ID를 함께 보관하세요. 이후 수집에서 빠졌더라도, 이전에 확인한 게시물은 원래의 수집 시각과 함께 유지합니다.
살펴볼 토론을 먼저 찾으려면 커뮤니티 수집 튜토리얼이나 X 검색 및 수집 가이드를 이용하세요.
하나의 맥락 데이터셋으로 읽기, 검토, 요약하기
SocQ Thread Context는 게시물 텍스트와 관계 ID를 같은 표준 결과에 담아 줍니다. 코드를 활용해 대화를 묶고, 답글 관계를 내보내고, 작성자 기준으로 필터링한 뷰를 만들어 보세요. 읽기 화면과 요약 워크플로는 이 레코드를 출처 및 맥락의 빈 부분 표시와 함께 재사용할 수 있습니다.
Thread Context를 열고 대상 토론 살펴보기.
출처 및 참고 자료
- SocQ Thread Context 문서 — 공개 입력, 상한, 표준 관계 필드.
자주 묻는 질문(FAQ)
첫 게시물이 아니라 답글에서 시작해도 되나요?
네. 해당 공개 답글 URL을 urls에 넣으세요. 작업은 설정된 상한까지 대상 게시물, 공개된 앞선 게시물, 원본에서 반환된 답글을 읽습니다.
게시물의 답글을 가져오는 것과 같은 기능인가요?
Post Replies는 선택한 게시물에 달린 답글에 초점을 둡니다. Thread Context는 대상 게시물, 앞선 게시물, 답글을 읽어 답글 관계로 맥락을 정리합니다.
대화의 모든 답글을 반환하나요?
작업은 입력마다 results_limit까지 공개 레코드를 수집합니다. 모든 페이지를 읽으면 그 수집에서 저장된 게시물을 가져오게 됩니다. 토론의 포괄 범위는 누락된 상위 게시물과 답글 레코드도 함께 보고 판단하세요.
답글에 달린 답글은 어떻게 처리하나요?
in_reply_to_id로 직접 상위 게시물을 연결하고 conversation_id로 대화를 묶으세요. 누락된 상위 게시물의 ID는 보존하고 빈 부분 표시를 보여 주세요.
참조된 상위 게시물이 없는 이유는 무엇인가요?
상위 게시물 참조는 반환되었지만 이번 수집에는 그 본문이 없는 경우입니다. 참조는 그대로 두고, 맥락이 더 필요할 때 해당 게시물을 조회하세요. 없는 구체적인 이유는 원본이 알려 주는 정보로만 판단하세요.
원작성자의 스레드만 남기려면 어떻게 하나요?
작성자 ID를 확인하고, 상위 게시물과 하위 게시물이 모두 그 작성자의 것인 엣지만 유지하세요. 대상 게시물을 중심으로 서로 이어진 구간을 선택하고, 본인 답글이 갈라지면 표시 범위를 정하세요.
AI 요약을 위해 스레드를 저장할 수 있나요?
네. 수집한 텍스트, 작성자, 시각, 관계를 JSON으로 저장한 다음 요약 단계를 별도로 실행하세요. 요약과 함께 누락된 맥락 표시와 출처 URL도 보존하세요.