SocQ로 Twitter/X 커뮤니티의 토론을 수집하고, 게시물 텍스트·작성자·게시 시각·출처를 함께 보관하세요. 반복되는 질문을 주제 아이디어로 정리하고, 각 항목에 원본 게시물을 붙여 두면 나중에 검토하기 편합니다.
이 튜토리얼은 SocQ X Community Posts로 게시물을 수집하고, X Community로 커뮤니티 설명과 규칙을 조회합니다. 예제는 출처가 보존된 JSON과 커뮤니티별 CSV 내보내기 파일을 만듭니다.
빠른 답변:
x.com/i/communities/{id}링크를POST /v1/x/community-posts에 제출하고 작업 ID를 저장한 뒤, 작업이 성공하면 모든 결과 페이지를 읽습니다. 같은 링크로POST /v1/x/community를 호출하면 메타데이터를 조회할 수 있습니다. 입력한 커뮤니티를 각 게시물에 함께 붙여 두면 메타데이터와 토론을 연결할 수 있습니다.
공개 커뮤니티 URL을 입력값으로 사용하기
조사하려는 공개 커뮤니티로 바꿔서, 아래와 같은 형태의 URL을 사용하세요.
https://x.com/i/communities/1493446837214187523
숫자 부분이 커뮤니티 ID입니다. 두 커뮤니티 엔드포인트 모두 /i/communities/{numeric_id} 형식의 전체 URL을 받습니다.
커뮤니티 이름만 알고 있다면 먼저 공개 URL을 찾은 다음, 그 링크를 urls에 제출하세요.
제출한 URL, 숫자 커뮤니티 ID, 게시 시각(published_at), 수집 시각(collected_at)을 저장하세요. x.com과 지원되는 twitter.com 변형 URL은 커뮤니티 ID로 일치 여부를 판단하고, 이름이 같아도 ID가 다르면 서로 다른 커뮤니티로 구분해서 보관합니다.
Twitter/X 커뮤니티 피드에서 게시물 수집하기
SOCQ_API_KEY를 설정한 뒤, 커뮤니티당 게시물 40개로 제한한 작업을 제출합니다.
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": 40
}'
응답에 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에 들어 있습니다.
Community Posts는 작성 시각 순서로 레코드를 반환합니다. 좋아요나 댓글 수 기준으로 정렬한 보고서가 필요하면 수집한 레코드를 로컬에서 정렬하고, 그 결과에는 표본 기준 순위라고 표시하세요.
커뮤니티별 제한 이해하기
results_limit의 기본값은 100이며, 20부터 2000까지 20의 배수(20, 40, 60, 100 등)를 지정할 수 있습니다.
이 제한은 입력한 커뮤니티마다 적용됩니다. results_limit=40인 URL 두 개를 제출하면 각각 최대 40개의 게시물을 요청하며, 실제 개수는 저장된 중복 제거 결과로 정해집니다.
작업 조회의 limit은 페이지당 읽을 저장 레코드 수를 정하고, next_cursor는 다음 페이지를 가리킵니다. 제출할 때의 results_limit은 수집 상한을 정합니다.
어떤 커뮤니티 데이터를 받는지 확인하기
| 리소스 | 표준 필드 | 조사 질문 |
|---|---|---|
| Community | name, text, rules, join_policy, invites_policy | 어떤 설명, 규칙, 참여 정책이 기록되어 있는가? |
| Community 수치 | metrics.members_count, metrics.moderators_count | 소스가 보고하는 멤버와 운영자는 몇 명인가? |
| Community Posts | id, text, author, published_at, media | 수집한 기간에 어떤 토론이 있었는가? |
| 게시물 지표 | 사용 가능한 좋아요, 댓글, 공유, 조회 수 | 수집 시점에 표본 게시물끼리 어떻게 비교되는가? |
메타데이터 요청은 따로 보냅니다.
curl -X POST "https://api.socq.ai/v1/x/community" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/i/communities/1493446837214187523"]}'
메타데이터는 별도의 작업 ID로 조회하세요. 멤버·운영자 합계는 커뮤니티의 규모를 나타내고, 게시물의 조회 수는 해당 게시물이 조회된 횟수를 기록한 값입니다. 활성 작성자 수나 고유 도달 수는 따로 측정해야 합니다.
null은 소스가 해당 측정값을 생략했다는 뜻이고, 0은 반환된 값이 0이라는 뜻입니다. 내보내는 파일에서도 두 값을 구분해서 보존하세요.
Python으로 커뮤니티 게시물을 JSON·CSV로 내보내기
아래 워크플로는 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")
이 도우미는 작업 ID를 출력하고, 최대 10분까지 기다리며, 저장된 결과 페이지를 모두 읽습니다. 클라이언트에서 타임아웃이 나면 ID를 보관해 두고 같은 작업을 계속 조회하세요.
다음으로 같은 폴더에 export_communities.py를 저장합니다.
import csv
import json
import sys
from urllib.parse import urlparse
from socq_collect import collect
urls = list(dict.fromkeys(sys.argv[1:]))
if not urls:
raise SystemExit("Usage: python3 export_communities.py COMMUNITY_URL [COMMUNITY_URL...]")
def cell(value):
text = "" if value is None else str(value)
return "'" + text if text.lstrip().startswith(("=", "+", "-", "@")) else text
fields = ["community_id", "community_url", "post_id", "post_url", "text",
"author_id", "author_username", "published_at", "collected_at",
"likes_count", "comments_count", "shares_count", "views_count"]
bundles, seen = [], set()
with open("community-posts.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=fields)
writer.writeheader()
for url in urls:
metadata_task, communities = collect("x/community", {"urls": [url]})
posts_task, posts = collect("x/community-posts", {
"urls": [url], "results_limit": 40,
})
bundles.append({
"input_url": url, "metadata_task_id": metadata_task,
"posts_task_id": posts_task, "communities": communities, "posts": posts,
})
# Save completed collections before processing another community.
with open("community-results.json", "w", encoding="utf-8") as saved:
json.dump(bundles, saved, ensure_ascii=False, indent=2)
community_id = urlparse(url).path.rstrip("/").split("/")[-1]
for post in posts:
post_id = post.get("id")
key = (community_id, post_id)
if post_id and key in seen:
continue
if post_id:
seen.add(key)
author = post.get("author") or {}
metrics = post.get("metrics") or {}
row = {
"community_id": community_id, "community_url": url,
"post_id": post_id, "post_url": post.get("url"), "text": post.get("text"),
"author_id": author.get("id"), "author_username": author.get("username"),
"published_at": post.get("published_at"),
"collected_at": post.get("collected_at"),
**{name: metrics.get(name) for name in
("likes_count", "comments_count", "shares_count", "views_count")},
}
writer.writerow({key: cell(value) for key, value in row.items()})
공개 커뮤니티 URL을 하나 이상 넣어 실행하세요.
python3 export_communities.py \
"https://x.com/i/communities/1493446837214187523"
결과물은 두 가지입니다.
community-results.json: 입력 URL, 두 작업 ID, 커뮤니티 메타데이터, 게시물 레코드를 그대로 보존합니다.community-posts.csv: 커뮤니티별로 반환된 게시물마다 한 행씩, 출처·작성자·타임스탬프·사용 가능한 지표를 담습니다.
이 예제는 커뮤니티마다 메타데이터 작업과 게시물 작업을 따로 만들어, 입력한 커뮤니티를 해당 게시물에 붙입니다. 덕분에 각 레코드가 어디에서 수집되었는지 분명하게 남습니다. 한꺼번에 가져오려면 배치를 쓰고, 게시물별 출처가 필요하면 여기서 쓴 단일 커뮤니티 작업 방식을 사용하세요.
중복 제거는 community_id + post_id를 기준으로 합니다. 한 커뮤니티 안에서 반복된 행은 합치고, 서로 다른 커뮤니티에서 관찰된 같은 게시물은 따로 보관합니다. 게시물 ID가 없는 레코드는 하나씩 그대로 유지됩니다.
프로그램은 커뮤니티 하나가 끝날 때마다 파일을 갱신합니다. 이후 요청이 실패해도 앞서 완료된 커뮤니티는 파일에 남아 있습니다. 결과를 보고서에 쓰기 전에 완료된 입력과 기록된 오류를 확인하세요.
스프레드시트 내보내기의 원본은 JSON으로 유지하기
CSV는 검토하기 편하지만 데이터를 평면화합니다. 중첩된 규칙, 미디어, 작성자 필드는 JSON에 그대로 남아 있습니다. 열 구성이 바뀌면 저장해 둔 JSON에서 다른 스프레드시트를 다시 만드세요.
예제는 Python 표준 라이브러리의 CSV 작성기로 따옴표, 쉼표, 여러 줄 텍스트를 처리합니다. 바이트 순서 표시(BOM)가 있는 UTF-8은 일반적인 스프레드시트 가져오기에 도움이 됩니다. 수식처럼 보이는 공개 텍스트는 CSV에서 이스케이프되며, JSON에는 원본 내용이 보존됩니다. 긴 숫자 ID는 스프레드시트에서 정밀도가 손실되지 않도록 텍스트로 가져오세요.
커뮤니티 토론을 주제 조사에 활용하기
예를 들어 수집한 토론에서 어떤 온보딩 질문이 반복되는지 살펴볼 수 있습니다. 질문별로 묶고, 각 분류에 근거가 되는 게시물 ID를 남겨 두세요.
먼저 커뮤니티의 설명과 규칙을 읽습니다. 그런 다음 게시물 텍스트, 게시 시각, 출처 링크를 함께 검토하세요. 반복되는 질문, 제품 불만, 자료 요청을 묶고, 라벨 옆에 근거 게시물 ID를 같이 적어 둡니다.
커뮤니티 상세 워크플로로 설명과 규칙을 저장한 뒤, 애플리케이션에서 주제 분류나 요약을 실행하세요.
로컬에서 좋아요나 댓글 수로 정렬했다면 수집 시각과 레코드 수를 붙여 "이번 수집 내 순위"라고 표시하세요. 이후 수집에서 보이지 않는 게시물은 "이번 수집에서 관찰되지 않음"으로 표시하고, 삭제 여부를 확인하려면 그 게시물을 따로 조회하세요.
개별 토론 안쪽 살펴보기
토론 하나를 자세히 보려면 반환된 게시물 URL을 X Thread Context에 제출해 대상 게시물, 앞선 답글 체인의 게시물, 답글 관계를 읽으세요.
다음 단계는 Twitter 스레드 컨텍스트 튜토리얼을 참고하세요. 특정 게시물의 답글만 필요하면 X Post Replies를, 커뮤니티가 아니라 계정에서 시작한다면 X User Posts를 사용하세요.
콘텐츠 판단의 근거로 원본 게시물 남기기
SocQ의 커뮤니티 메타데이터 엔드포인트와 게시물 엔드포인트는 커뮤니티 식별, 토론 수집, 주제 검토를 하나로 연결합니다. 코드는 각 게시물의 커뮤니티 출처를 유지한 채 JSON과 CSV로 내보내므로, 콘텐츠 팀은 질문을 검토하고 사례를 정리하고 요약용 입력을 준비할 수 있습니다.
Community Posts를 열고 대상 커뮤니티를 수집해 보세요.
출처 및 추가 자료
- SocQ Community Posts 문서 — 허용되는 링크, 커뮤니티별 제한, 표준 게시물 필드.
- SocQ Community 문서 — 메타데이터, 규칙, 수치.
자주 묻는 질문(FAQ)
여러 X 커뮤니티의 게시물을 수집할 수 있나요?
네. urls에 커뮤니티 URL을 여러 개 제출하세요. 결과 상한은 URL마다 적용됩니다. Python 내보내기 예제는 작업을 따로 나눠, 모든 게시물에 입력 커뮤니티 출처가 분명하게 남도록 합니다.
커뮤니티에 올라온 모든 게시물을 반환하나요?
작업은 지정한 커뮤니티에서 results_limit 범위 안의 게시물을 읽습니다. 반환된 레코드가 해당 수집의 범위입니다. 과거 데이터를 분석하려면 수집을 따로 저장하고, 각각의 범위를 함께 보고하세요.
게시물뿐 아니라 커뮤니티 멤버도 내보낼 수 있나요?
Community는 메타데이터와 멤버·운영자 수를 반환하고, Community Posts는 게시물을 반환합니다. 개별 멤버 목록은 별개의 데이터이며 이 엔드포인트에서는 반환되지 않습니다.
커뮤니티 피드는 사용자 타임라인과 어떻게 다른가요?
커뮤니티 피드는 하나의 토론 공간에 모인 게시물이고, 사용자 타임라인은 한 계정의 게시물입니다. Community Posts에는 커뮤니티 링크를, User Posts에는 사용자 이름을 사용하세요.
인기순이나 좋아요순 정렬을 선택할 수 있나요?
엔드포인트는 작성 시각 순서로 반환합니다. 해당 수집의 지표 순위가 필요하면 애플리케이션에서 좋아요나 댓글 수로 표본을 정렬하세요.
페이지네이션으로 새 게시물을 수집할 수 있나요?
커서는 원래 작업이 저장한 다음 페이지를 읽습니다. 새로운 관찰이 필요하면 새 작업을 제출하고, 겹치는 레코드는 게시물 ID로 처리하세요.
커뮤니티 이전 공지 이후의 게시물은 어떻게 수집하나요?
X는 Communities에서 XChat으로의 이전 공지를 게시했습니다. 대상 커뮤니티 URL을 Community Posts에 제출하고, 성공한 뒤 반환된 게시물을 읽으세요. 빈 결과와 실패는 따로 기록하고, 수집 시각을 보관해 두면 저장된 과거 데이터와 새 조회 결과를 구분할 수 있습니다.