X Thread Context
X 스레드는 비슷한 시기에 올라온 게시물을 단순히 묶은 것이 아니라, 게시물을 그것이 답글을 단 메시지와 그 답글 체인의 이전 메시지, 이어지는 답글로 연결한 구조입니다. 이러한 관계를 게시물 텍스트와 작성자 정보와 함께 보관하면, 토론이 어떻게 전개되었는지 따라가고 개별 메시지의 맥락을 이해하는 데 도움이 됩니다.
X Thread Context API 주요 기능
- 선택한 게시물과 주변 토론 함께 읽기게시물 링크로 대상 메시지와 함께 그 답글 체인을 거슬러 올라가며 찾은 이전 공개 메시지, 이어지는 답글을 수집해, 선택한 메시지 하나만으로는 알 수 없는 맥락을 확인할 수 있습니다.
- 함께 속한 게시물과 답글 관계 파악텍스트, 작성자, 상호작용 수치와 함께, conversation_id는 게시물이 속한 대화를, in_reply_to_id는 게시물이 직접 답글을 단 대상 게시물을 나타내어 개별 레코드 사이의 연결을 알려 줍니다.
X Thread Context API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | /status/ 뒤에 숫자 게시물 ID가 붙은 공개 X 게시물 링크의 목록으로, 필수 값입니다(예: https://x.com/BaganiTohid/status/2110635249889919362). Playground에서는 한 줄에 링크 하나씩 입력하거나 JSON urls 배열을 사용하세요. 프로필이나 커뮤니티 링크는 사용할 수 없습니다. |
results_limit | 선택 | 입력 게시물마다 가져올 최대 맥락 레코드 수로, 선택 값입니다. 1부터 2000까지이며 기본값은 100입니다. 게시물 링크 두 개에 상한 20이면 각각 최대 20개의 관련 레코드를 요청하며, 합계 20개를 나눠 쓰지 않습니다. |
X Thread Context API 사용 방법
요청을 보내면 백그라운드 수집 작업이 시작되므로, 첫 응답에는 완성된 데이터가 아니라 작업 ID가 담깁니다. 이 ID로 진행 상황을 확인하고 결과를 가져옵니다.
- 맥락을 파악하려는 공개 게시물 링크를 복사하고, 그 게시물에 대해 요청할 맥락 레코드 수를 정합니다. 링크가 여러 개라면 urls 목록에 하나씩 넣으세요.
- 예제를 실행하기 전에 $SOCQ_API_KEY를 본인의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래 예제처럼 Authorization 헤더를 포함해 JSON 입력을 POST /v1/x/thread-context로 보내고, 응답의 task_id를 저장합니다.
- 저장한 ID로 GET /v1/tasks/{task_id}를 호출해 진행 상황을 확인합니다. queued는 대기 중, running은 수집 진행 중, retrying은 재시도 중이라는 뜻입니다. succeeded가 되면 결과를 읽고, 작업이 failed이면 error_message에서 사유를 확인하세요.
- 작업이 성공하면 data.results.items를 읽습니다. 이 목록의 각 항목은 게시물 하나와 확인 가능한 대화 관계를 나타내며, 목록이 비어 있으면 레코드 없이 작업이 완료되었다는 뜻입니다.
- data.results.has_more가 true이면 next_cursor 값이 저장된 결과의 다음 페이지를 가리키는 표식입니다. 이 값을 그대로 GET /v1/tasks/{task_id}?cursor=...의 cursor 매개변수에 넣고, has_more가 false가 될 때까지 반복합니다.
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":20}'X Thread Context API 추천 활용 사례
- 메시지를 읽는 데 필요한 맥락과 함께 검토: 대상 게시물을 반환된 이전 메시지와 답글(텍스트와 작성자 포함)과 나란히 배치해, 선택한 메시지가 무엇에 대한 반응이었는지 확인하려는 사람을 위한 읽기용 화면을 준비합니다.
- 반환된 답글 관계 지도 만들기: conversation_id로 게시물을 묶고 각 in_reply_to_id를 다른 레코드의 id와 대조해 존재하는 답글 연결을 그리며, 참조된 게시물이 반환되지 않았다면 빈 부분을 그대로 드러냅니다.
- 대화 요약용 원본 자료 준비: 응답에서 완성된 요약을 기대하는 대신, 게시물 텍스트, 작성자 이름, 시각, 답글 관계를 순서가 있는 읽기 세트로 저장해 사람이나 별도 소프트웨어의 요약 단계에 활용합니다.
X Thread Context API 활용 팁
- 토론을 읽기 좋게 배열할 때는 관계 ID로 게시물을 먼저 연결하고, 게시 시각은 보조 맥락으로만 사용하세요. 시간순 목록만으로는 각 게시물이 어떤 메시지에 대한 답인지 알 수 없습니다.
- in_reply_to_id가 저장된 레코드에 없는 ID를 가리키면, 답글을 다른 게시물에 붙이거나 빠진 텍스트를 지어내지 말고 그 참조를 누락된 연결로 남겨 두세요.
- 제출한 여러 링크가 같은 대화에 속할 때는 저장된 결과를 게시물 ID로 병합해, 공통된 이전 게시물이 읽기 세트에 여러 번 나타나지 않게 하세요.
- 선택한 게시물의 답글만 필요하면 X Post Replies를, 게시물 자체만 필요하면 주변 맥락을 수집하는 대신 X Posts를 사용하세요.
관련 API
X Thread Context API 외에 X의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Twitter Tweet Scraper API — x.com 또는 twitter.com 게시물 URL에서 공개 게시물 텍스트, 작성자, 참여도, 미디어, 해시태그, 멘션, 대화 관계를 가져옵니다.
- Twitter User Tweets Scraper API — 사용자 이름으로 최근 공개 게시물, 작성자, 미디어, 해시태그, 멘션, 참여도를 수집하며 답글은 제외합니다.
- X Post Quotes API — 알고 있는 게시물 URL에 대한 공개 인용 게시물을 수집하며, 코멘트, 작성자, 참여도, 미디어, 타임스탬프, 원본 게시물 맥락을 포함합니다.
- X Post Replies API — X 게시물 URL에서 공개 답글을 수집하며, 정렬 방식을 선택할 수 있고 답글 텍스트, 작성자, 공개된 참여도, 미디어, 상위 게시물 맥락을 포함합니다.
- Twitter Mentions API — 지정한 계정을 멘션한 공개 게시물을 수집합니다.
- X Community Posts API — 커뮤니티에 공유된 공개 게시물을 텍스트, 작성자, 상호작용 수와 함께 가져옵니다.
- Twitter Profile Scraper API
- Twitter Search API
- X Followers List API
- X Following List API
- X Post Retweeters API
- X Trends API
- Twitter User Search API
- X Community API
- X Account Location API
- X Verified Followers API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Communities Search API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API