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로 진행 상황을 확인하고 결과를 가져옵니다.
- 읽고 싶은 커뮤니티의 링크를 복사하고 커뮤니티별 상한을 20이나 100처럼 정합니다. 개별 게시물 URL이 아니라 커뮤니티 링크를 사용하세요.
- 예제를 실행하기 전에 $SOCQ_API_KEY를 본인의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래 예제처럼 Authorization 헤더를 포함해 JSON 입력을 POST /v1/x/community-posts로 보내고, 응답의 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/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가 보장되지 않습니다.
관련 API
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 — 리스트 타임라인을 최신순으로 가져오며, 리포스트에는 원 작성자를 표시합니다.
- Twitter Profile Scraper API
- Twitter Search API
- X Followers List API
- X Following List API
- X Post Replies API
- X Post Retweeters API
- X Trends API
- Twitter User Search API
- X Community API
- X Account Location API
- X Verified Followers 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