XTwitter 커뮤니티 APIX 커뮤니티 정보 APITwitter 커뮤니티 상세 API커뮤니티 메타데이터

API로 Twitter/X 커뮤니티 정보 가져오는 방법

SocQ로 Twitter/X 커뮤니티 프로필 표를 만드세요. 이름, 규칙, 수치를 출처 링크와 수집 시각과 함께 내보내고, 연구용으로 게시물까지 연결합니다.

SocQ2026년 10월 16일 업데이트약 6분 소요

SocQ로 Twitter/X 커뮤니티의 이름, 설명, 규칙, 멤버 수와 운영진 수를 프로필 표로 정리해 보세요. 출처와 수집 시각을 함께 저장하고, 기록해 둔 커뮤니티 맥락에 게시물을 연결해 검토할 수 있습니다.

SocQ X Community API는 공개 커뮤니티 URL로 메타데이터를 조회합니다. 이 가이드에서는 요청 방법, 반환 필드, 출처 링크와 수집 시각이 포함된 JSON·CSV 내보내기를 다룹니다.

빠른 답변: x.com/i/communities/{numeric_id} 링크를 urls에 넣어 POST /v1/x/community로 제출하세요. 작업이 성공하면 data.results.items에서 이름, 설명, 규칙, 멤버 수와 운영진 수, 가입 및 초대 정책을 읽을 수 있습니다. 게시물은 Community Posts로 따로 조회하세요.

커뮤니티 URL로 프로필 표 만들기

urls에 커뮤니티 URL을 넣으면 이름, 설명, 규칙, 멤버 수와 운영진 수, 가입 및 초대 정책을 조회할 수 있습니다. 이 예시는 Build in Public 커뮤니티를 사용합니다.

https://x.com/i/communities/1493446837214187523

마지막 숫자 부분이 커뮤니티 ID입니다. urls에는 /i/communities/{numeric_id}를 포함한 전체 URL을 넣어야 합니다.

이름만 알고 있다면 먼저 커뮤니티 URL을 찾으세요. 레코드는 커뮤니티 숫자 ID로 매칭하고, 이름이 같아도 ID가 다른 커뮤니티는 서로 구분해서 보관하세요.

궁금한 점사용할 엔드포인트
이 커뮤니티에서 어떤 메타데이터를 얻을 수 있나요?X Community
커뮤니티에서 어떤 게시물을 수집할 수 있나요?X Community Posts
하나의 토론 안에서 게시물은 서로 어떻게 연결되나요?X Thread Context

이 엔드포인트는 주제별 커뮤니티의 메타데이터를 조회합니다. 커뮤니티 노트(Community Notes)는 게시물에 붙는 주석이며 별개의 데이터 유형입니다.

커뮤니티 정보 요청하기

SOCQ_API_KEY를 설정한 뒤 URL을 제출합니다.

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"]}'

여러 건을 한꺼번에 조회하려면 공개 커뮤니티 링크를 urls에 추가하세요. 반환되는 레코드 하나는 커뮤니티 하나를 나타내므로, 결과 수는 실제로 반환된 레코드를 기준으로 세세요.

data.task_id를 TASK_ID로 저장한 뒤 기존 작업을 조회합니다.

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

상태가 queued, running, retrying인 동안에는 확인 간격을 두고 기다리세요. succeeded가 되면 data.results.items와 저장된 나머지 결과 페이지를 읽습니다. 작업이 실패하면 data.error_message를 확인하세요. 작업 페이지네이션은 저장된 데이터를 읽을 뿐이며 커뮤니티 정보를 새로 고치지는 않습니다.

규칙, 수치, 가입 정책 읽기

다음 메타데이터 예시는 일부 필드와 규칙 배열에 들어 있는 규칙 하나를 보여 줍니다.

{
  "id": "1493446837214187523",
  "type": "community",
  "name": "Build in Public",
  "metrics": {"members_count": 268858, "moderators_count": 6},
  "join_policy": "Open",
  "invites_policy": "MemberInvitesAllowed",
  "rules": [
    {
      "id": "1493447542045958144",
      "name": "Share what you're working on",
      "description": "Don't be scared to share unfinished work"
    }
  ],
  "collected_at": "2026-10-15T08:12:58.252843Z"
}

text에는 설명이, rules에는 구조화된 규칙 목록이, metrics에는 수치가 들어 있습니다. 규칙의 이름과 설명은 따로 보관하고, 원본에 설명이 없으면 null로 두세요.

metrics.members_count는 멤버 총수를, metrics.moderators_count는 운영진 총수를 나타냅니다. 같은 커뮤니티의 수치를 시점별로 비교할 수 있도록 수집 시각을 함께 저장하세요.

join_policy와 invites_policy에는 원본의 가입 정책과 초대 정책 문자열이 저장됩니다. 이미 알고 있는 값에 라벨을 붙이더라도 원본 값은 유지하고, 처음 보는 값은 반환된 그대로 표시하세요. 실제 가입 가능 여부는 X의 현재 제품 화면에서 확인해야 합니다.

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")

내보내기 스크립트는 같은 디렉터리에 export_communities.py로 저장하세요.

import csv
import json
from socq_collect import collect

urls = ["https://x.com/i/communities/1493446837214187523"]
task_id, items = collect("x/community", {"urls": urls})
with open("communities.json", "w", encoding="utf-8") as f:
    json.dump({"task_id": task_id, "input": {"urls": urls}, "items": items},
              f, ensure_ascii=False, indent=2)

fields = ["community_id", "url", "name", "description", "members_count",
          "moderators_count", "join_policy", "invites_policy", "rules_json", "collected_at"]
def csv_cell(value):
    if value is None:
        return ""
    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
        return "'" + value
    return value

with open("communities.csv", "w", encoding="utf-8-sig", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=fields)
    writer.writeheader()
    for item in items:
        metrics = item.get("metrics") or {}
        row = {"community_id": item.get("id"), "url": item.get("url"),
               "name": item.get("name"), "description": item.get("text"),
               "members_count": metrics.get("members_count"),
               "moderators_count": metrics.get("moderators_count"),
               "join_policy": item.get("join_policy"),
               "invites_policy": item.get("invites_policy"),
               "rules_json": json.dumps(item.get("rules"), ensure_ascii=False),
               "collected_at": item.get("collected_at")}
        writer.writerow({k: csv_cell(v) for k, v in row.items()})
python3 export_communities.py

JSON에는 정규화된 원본 레코드와 제출한 링크가 그대로 남습니다. CSV는 반환된 커뮤니티마다 검토용 행을 하나씩 만들며, 규칙은 JSON으로 직렬화해서 쉼표나 줄바꿈 때문에 구조가 깨지지 않게 합니다. rules_json=null은 빈 목록과 구분됩니다. 수식처럼 보이는 공개 텍스트는 CSV에서만 이스케이프되며, 식별자는 텍스트로 가져와야 합니다.

입력에 대해 메타데이터가 반환되지 않으면 빈 결과와 조회 시각을 따로 기록하세요. 이전에 저장한 메타데이터는 이력 비교를 위해 원래의 수집 시각과 함께 보관합니다.

커뮤니티 메타데이터를 수집한 게시물과 연결하기

토론 내용이 필요하면 확인을 마친 같은 커뮤니티 URL을 X Community Posts에 사용하세요. 이는 별도의 작업으로 시작되며 결과 상한도 따로 적용됩니다. 커뮤니티 게시물 튜토리얼에서 게시물을 내보내면서 입력 커뮤니티라는 출처를 유지하는 방법을 볼 수 있습니다.

메타데이터와 함께 커뮤니티 ID, 출처 URL, 작업 ID, 수집 시각을 저장하세요. 수집한 게시물마다 입력한 커뮤니티를 붙여 두면 프로필 표와 게시물 표를 커뮤니티 ID로 조인할 수 있습니다.

설명, 규칙, 수집한 게시물을 각각의 수집 시각과 함께 놓고 검토하세요. 게시물의 답글 관계가 궁금하다면 스레드 컨텍스트 튜토리얼로 이어서 진행하세요.

커뮤니티 메타데이터를 재사용 가능한 연구 자료로 만들기

SocQ는 커뮤니티 메타데이터를 표준 필드로 정리합니다. 코드로 프로필 표와 구조화된 규칙을 저장한 뒤, 수집한 게시물을 커뮤니티 ID로 조인하세요. 설명, 규칙, 토론이 명확한 출처를 공유하므로 연구 파일, 표본 검토, 날짜별 업데이트에 활용하기 좋습니다.

X Community를 열고 출처 URL 조회하기.

자주 묻는 질문(FAQ)

Twitter Community API는 무엇을 반환하나요?

커뮤니티 이름, 설명, 규칙, 멤버 수와 운영진 수, 가입 정책, 초대 정책을 반환합니다. 필드 정의와 과금은 X Community API 페이지를 참고하세요.

커뮤니티 이전 공지 이후에는 메타데이터를 어떻게 조회하나요?

X는 Communities에서 XChat으로의 이전 공지를 게시했습니다. 메타데이터 조회에는 대상 커뮤니티 URL을 사용하세요. 작업이 성공하면 반환된 레코드를 읽고, 결과가 비어 있으면 조회 시각을 저장하고, 실패하면 오류 상세를 확인합니다. 가입과 참여 기능은 X의 현재 화면에서 확인하세요.

이름으로 커뮤니티를 검색할 수 있나요?

조회는 커뮤니티 URL을 입력으로 받습니다. 이름에 해당하는 링크를 확인한 뒤 urls에 넣어 제출하세요.

멤버 수에 멤버나 운영진 목록도 포함되나요?

응답에는 멤버 수와 운영진 수의 합계만 들어 있습니다. 개별 계정 목록은 별도의 데이터이며 이 메타데이터 응답에 포함되지 않습니다.

Open 정책이면 지금 바로 가입할 수 있나요?

Open은 메타데이터에 반환된 가입 정책 값입니다. 현재 가입 가능 여부는 X 화면에서 확인하세요. 이 엔드포인트는 메타데이터를 읽는 기능입니다.

커뮤니티 게시물이나 커뮤니티 노트도 포함되나요?

커뮤니티 게시물은 X Community Posts로 조회하세요. 커뮤니티 노트는 게시물에 붙는 별도의 주석입니다. 이 엔드포인트는 커뮤니티 메타데이터를 반환합니다.

이 수치로 커뮤니티 활동 순위를 매길 수 있나요?

멤버 수와 운영진 수는 규모를 나타냅니다. 활동을 분석하려면 게시물을 수집하고, 애플리케이션에서 published_at으로 기간을 고른 뒤, 그 표본 안에서 게시물, 작성자, 상호작용의 수를 세세요.

X API

공개 X URL로 워크플로를 테스트하세요

공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.

X API 살펴보기