x/
thread-context

게시물 링크로 X 게시물 주변의 맥락을 읽어 옵니다. 대상 게시물, 그 게시물이 답글을 단 이전 게시물, 공개 답글을 관계 ID와 함께 반환합니다.

X Thread Context API

게시물과 그 맥락
어떤 게시물이 어디에 답글을 달았는지
대화 단위 그룹화
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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로 진행 상황을 확인하고 결과를 가져옵니다.

  1. 맥락을 파악하려는 공개 게시물 링크를 복사하고, 그 게시물에 대해 요청할 맥락 레코드 수를 정합니다. 링크가 여러 개라면 urls 목록에 하나씩 넣으세요.
  2. 예제를 실행하기 전에 $SOCQ_API_KEY를 본인의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래 예제처럼 Authorization 헤더를 포함해 JSON 입력을 POST /v1/x/thread-context로 보내고, 응답의 task_id를 저장합니다.
  3. 저장한 ID로 GET /v1/tasks/{task_id}를 호출해 진행 상황을 확인합니다. queued는 대기 중, running은 수집 진행 중, retrying은 재시도 중이라는 뜻입니다. succeeded가 되면 결과를 읽고, 작업이 failed이면 error_message에서 사유를 확인하세요.
  4. 작업이 성공하면 data.results.items를 읽습니다. 이 목록의 각 항목은 게시물 하나와 확인 가능한 대화 관계를 나타내며, 목록이 비어 있으면 레코드 없이 작업이 완료되었다는 뜻입니다.
  5. 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를 사용하세요.

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 — 커뮤니티에 공유된 공개 게시물을 텍스트, 작성자, 상호작용 수와 함께 가져옵니다.

다른 플랫폼 둘러보기

X 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

X Thread Context API — 자주 묻는 질문

X Thread Context API는 X 게시물 링크에서 공개 토론 맥락을 가져오는 프로그래밍 인터페이스입니다. 대상 게시물, 답글 체인의 이전 게시물, 확인 가능한 답글, 반환된 게시물이 어떻게 이어지는지 보여 주는 관계 ID를 반환합니다.

대상은 링크를 제출한 게시물입니다. 이전 게시물(ancestors라고도 합니다)은 대상의 답글 관계를 거슬러 올라가며 찾은 메시지이며, 그 이전에 올라온 모든 게시물을 뜻하지는 않습니다.

A가 게시물을 올리고 B가 A에 답글을 달면, B의 in_reply_to_id에는 A의 게시물 ID가 담깁니다. conversation_id는 게시물을 같은 대화로 묶고 in_reply_to_id는 직접적인 답글 연결을 나타내며, C가 B에 답글을 달면 C는 A가 아니라 B를 가리킵니다.

Thread Context는 선택한 게시물과 답글 체인의 공개 이전 게시물, 답글을 모두 포함합니다. X Post Replies는 지정한 게시물에 달린 답글에 집중하므로 더 좁은 답글 수집 작업에 적합합니다.

아니요. 상한과 공개 범위 때문에 빈 부분이 생길 수 있고, 관계 ID가 결과에 포함되지 않은 게시물을 가리킬 수도 있습니다. 누락된 메시지나 그 의미를 추측하지 말고, 확인 가능한 연결만 그대로 보존하세요.

아니요. 커서는 이 작업이 이미 저장한 레코드의 다른 페이지를 읽을 뿐이며, 새 수집을 시작하거나 처음 정한 결과 상한을 늘리지 않습니다.

반환된 게시물 레코드 하나당 0.5 크레딧이며 기본 요금은 없습니다. 링크 두 개에 상한 100이면 100 크레딧으로 예상되고, 작업이 게시물을 총 30개 반환하면 최종 요금은 15 크레딧입니다.