x/
community-posts

X 커뮤니티 링크의 공개 게시물을 가져오며, 게시물 텍스트, 작성자, 참여 수치를 함께 반환하고 커뮤니티마다 결과 수 제한을 따로 적용합니다.

X Community Posts API

커뮤니티 토론 읽기
게시물 텍스트와 작성자
커뮤니티별 수량 제한
결과당 0.7 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

X Community Posts

X 커뮤니티 게시물은 주제 기반 커뮤니티 안에서 공유되는 메시지로, 작성자, 게시 시각, 텍스트, 첨부된 미디어가 함께 담겨 있습니다. 이러한 게시물을 상호작용 수치와 함께 읽으면 토론 자료를 정리하고, 커뮤니티의 공개 대화를 이루는 개별 게시물을 비교할 수 있습니다.

X Community Posts API 주요 기능

  • 지정한 커뮤니티의 게시물 읽기한 사람의 프로필에 올라온 게시물 모음이 아니라, 커뮤니티 링크에서 시작해 해당 커뮤니티의 공개 토론을 수집합니다.
  • 커뮤니티마다 별도 상한 적용커뮤니티 링크를 여러 개 지정하면 results_limit이 각각에 적용되고 게시물은 작성 시각순으로 수집되므로, 입력값으로 토론 공간별 수집 규모를 정할 수 있습니다.
  • 메시지와 부가 정보를 함께 보존각 게시물 레코드에는 텍스트, 작성자 정보, 게시 시각, 미디어, 확인 가능한 상호작용 수치가 담겨 있어, 누가 언제 올렸는지 놓치지 않고 메시지를 검토할 수 있습니다.

X Community Posts API 매개변수

매개변수필수설명
urls필수숫자 커뮤니티 ID가 포함된 공개 X 커뮤니티 링크의 목록으로, 필수 값입니다(예: https://x.com/i/communities/1493446837214187523). Playground에서는 한 줄에 링크 하나씩 입력하고, 코드에서는 JSON urls 배열을 사용하세요. 프로필, 검색, 개별 게시물 링크는 사용할 수 없습니다.
results_limit선택커뮤니티별 최대 게시물 수로, 선택 값입니다. 기본값은 100이며 20부터 2000까지 20의 배수(예: 20, 40, 100)를 받습니다. 커뮤니티 링크가 두 개이고 상한이 20이면 커뮤니티마다 최대 20개의 게시물을 가져올 수 있습니다.

X Community Posts API 사용 방법

요청을 보내면 백그라운드 수집 작업이 시작되므로, 첫 응답에는 완성된 데이터가 아니라 작업 ID가 담깁니다. 이 ID로 진행 상황을 확인하고 결과를 가져옵니다.

  1. 읽고 싶은 커뮤니티의 링크를 복사하고 커뮤니티별 상한을 20이나 100처럼 정합니다. 개별 게시물 URL이 아니라 커뮤니티 링크를 사용하세요.
  2. 예제를 실행하기 전에 $SOCQ_API_KEY를 본인의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래 예제처럼 Authorization 헤더를 포함해 JSON 입력을 POST /v1/x/community-posts로 보내고, 응답의 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/community-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/i/communities/1493446837214187523"],"results_limit":20}'

X Community Posts API 추천 활용 사례

  • 토론 요약용 원본 자료 준비: 가져온 게시물 텍스트, 작성자 핸들, 링크, 시각을 읽기 목록으로 정리해 두면, 사람이나 별도의 요약 도구가 해당 게시물의 요약본을 작성하는 데 활용할 수 있습니다.
  • 저장된 스냅샷으로 게시물 상호작용 수치 비교: 게시물 ID와 반환된 수치를 수집 시각과 함께 저장하고, 이후 수집에서 같은 게시물을 찾아 맞춰 보면 확인 가능한 수치의 변화를 직접 계산할 수 있습니다.
  • 선택한 게시물 주변 대화 조사: 커뮤니티 결과에서 게시물을 골라 그 게시물 URL을 X Thread Context에 전달하면, 해당 메시지 앞뒤의 확인 가능한 이전 게시물과 답글을 읽을 수 있습니다.

X Community Posts API 활용 팁

  • 배치를 계획할 때는 커뮤니티 링크 수에 results_limit을 곱해 요청 레코드 수를 가늠하고, 상한을 모든 커뮤니티가 나눠 쓴다고 가정하지 말고 게시물당 요금을 기준으로 계산하세요.
  • 수집을 반복할 때는 이후 작업에서 같은 게시물이 다시 나타날 수 있으므로, 저장 테이블에 추가하기 전에 게시물 ID로 대조하세요.
  • 여러 커뮤니티의 결과를 보관할 때는 제출한 커뮤니티 링크를 작업 입력과 함께 저장하세요. 표준 게시물 레코드에는 이 입력 정보를 대신할 커뮤니티 ID가 보장되지 않습니다.

X Community Posts API 외에 X의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Twitter Tweet Scraper API — x.com 또는 twitter.com 게시물 URL에서 공개 게시물 텍스트, 작성자, 참여도, 미디어, 해시태그, 멘션, 대화 관계를 가져옵니다.
  • Twitter User Tweets Scraper API — 사용자 이름으로 최근 공개 게시물, 작성자, 미디어, 해시태그, 멘션, 참여도를 수집하며 답글은 제외합니다.
  • X Post Quotes API — 알고 있는 게시물 URL에 대한 공개 인용 게시물을 수집하며, 코멘트, 작성자, 참여도, 미디어, 타임스탬프, 원본 게시물 맥락을 포함합니다.
  • Twitter Mentions API — 지정한 계정을 멘션한 공개 게시물을 수집합니다.
  • X Thread Context API — 게시물과 함께 답글 체인의 이전 글, 공개 답글, 관계 ID를 가져옵니다.
  • X List Tweets API — 리스트 타임라인을 최신순으로 가져오며, 리포스트에는 원 작성자를 표시합니다.

다른 플랫폼 둘러보기

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

X Community Posts API — 자주 묻는 질문

X Community Posts API는 X 커뮤니티 링크 목록에서 공개 게시물을 읽어 오는 프로그래밍 인터페이스입니다. 게시물 텍스트, 작성자, 미디어, 타임스탬프, 상호작용 수치를 작성 시각순으로 반환하며 커뮤니티마다 결과 상한을 적용합니다.

커뮤니티는 해당 토론 공간 안에서 공유된 게시물을 묶고, 프로필 타임라인은 한 계정의 게시물을 묶습니다. 여기에는 커뮤니티 링크를 입력하고, 계정 사용자 이름에서 시작한다면 X User Posts를 사용하세요.

아니요. 커뮤니티 링크마다 최대 100개라는 뜻입니다. 예를 들어 커뮤니티 세 곳이면 합계 최대 300개를 요청할 수 있지만, 공개 여부와 중복 제거에 따라 최종 레코드 수는 줄어들 수 있습니다.

상한은 20 단위로만 지정할 수 있으므로 20, 40, 60, 100 같은 값을 사용하세요. 허용 범위는 20부터 2000까지이고 기본값은 100입니다.

아니요. 작업의 cursor는 해당 작업이 이미 저장한 결과의 다른 페이지를 읽게 해 줄 뿐입니다. 처음 정한 커뮤니티별 상한을 늘리거나 새 수집을 시작하지 않습니다.

아니요. 읽고 정리하거나 별도의 요약 프로세스에 넘길 수 있는 게시물 레코드를 반환합니다. 완성된 요약이나 분석은 응답에 포함되지 않습니다.

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