XTwitter스크래핑API 튜토리얼

API로 X/Twitter 게시물 검색하고 수집하는 방법

비동기 엔드포인트와 정규화된 JSON으로 X의 공개 프로필, 게시물, 타임라인, 검색 결과, 답글, 인용을 수집하세요.

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

브라우저에서 보는 X는 여전히 하나의 타임라인처럼 보입니다. 하지만 공개 데이터의 사양은 훨씬 좁습니다. 사용자 이름은 게시물 URL이 아니고, 인용은 리포스트가 아니며, 답글은 인용이 아닙니다. 삭제되었거나 비공개인 게시물은 빈 레코드가 되지 않고 깔끔하게 실패해야 합니다.

이 튜토리얼에서는 SocQ X API로 실서비스 수준의 워크플로를 구성합니다. 공식 접근과 공개 접근의 차이, 엔드포인트 선택, 입력값 정리, 비동기 작업, 필드의 의미, 갱신 주기, 책임 있는 사용까지 다룹니다.

빠른 답변: 사용자 이름, x.com 또는 twitter.com 게시물 URL, 검색어를 POST /v1/x/{resource}로 보내고, 작업 ID를 저장한 뒤 /v1/tasks/{id}를 폴링하세요. 인용, 리포스트, 답글은 리소스 구분 값 없이 하나의 테이블에 합치지 마세요.

공식 X API와 공개 데이터 API 중 무엇을 쓸까

공식 X API는 유료이며 권한이 필요합니다. 게시물 작성, 다이렉트 메시지(DM) 전송, 광고 관리, 사용자 권한으로 하는 팔로우·좋아요, 스트림 및 그 밖의 계정 인증이 필요한 기능에는 공식 API가 맞는 선택입니다. 접근 조건과 요금은 바뀔 수 있으니, 쓰기 및 파트너 제품은 최신 개발자 문서를 기준으로 판단하세요.

SocQ는 지원되는 프로필, 알고 있는 게시물, 사용자 게시물 구간, 검색, 대화 관계, 트렌드를 읽는 공개 읽기 계층입니다. X 사용자로 인증하지 않으며, 공식 API의 게시나 광고 기능을 대체하지 않습니다. 요금과 업체 비교는 Twitter API 대안, Twitter 스크래퍼 API 비교, TwitterAPI.io 대안을 참고하세요. 엔드포인트를 고르기 전에 접근 방식부터 정하세요.

알맞은 X 엔드포인트 고르기

리소스엔드포인트허용되는 공개 입력값일반적인 용도
Profiles/v1/x/profiles사용자 이름(@ 유무 무관)공개 신원 정보와 표시되는 수치
Posts/v1/x/postsx.com 또는 twitter.com 게시물 URL알고 있는 게시물 1건
User posts/v1/x/user-posts사용자 이름계정의 최근 공개 게시물
Search/v1/x/search검색어최신순 또는 인기순 공개 게시물 탐색
Replies/v1/x/post-replies게시물 URL알고 있는 게시물의 답글
Quotes/v1/x/post-quotes게시물 URL알고 있는 게시물의 인용 게시물

그 밖에 다음 엔드포인트도 있습니다.

인용, 리포스트, 답글은 서로 다른 리소스입니다. 인용에는 자체 게시물 텍스트가 있습니다. 리포스트한 사용자 목록은 프로필의 집합입니다. 답글은 대화에 속한 게시물입니다. 이들을 같은 객체처럼 upsert하지 마세요.

사용자 이름, URL, 검색어 정규화하기

제출한 값은 그대로 보관하고, 복사본을 정리해서 사용하세요.

  1. 사용자 이름은 @가 있든 없든 받아들이고, 하나의 정식 사용자 이름으로 저장합니다.
  2. x.com과 twitter.com 호스트를 모두 허용합니다. 게시물 형태의 엔드포인트에는 숫자로 된 /status/{id} 경로가 있어야 합니다.
  3. 추적용 쿼리 매개변수는 제거합니다. 게시물 ID가 온전하다면 특정 모바일 호스트나 로캘 호스트를 요구하지 마세요.
  4. 사용자 이름은 대소문자를 구분하지 않고, 게시물은 게시물 ID 기준으로 중복을 제거합니다.
  5. 제출하기 전에 빈 검색어와 빈 사용자 이름을 거부합니다.
  6. 분석가가 게시물이 데이터셋에 들어온 이유를 설명할 수 있도록 검색식을 출처 행에 남깁니다.

user-posts와 search의 results_limit은 20부터 2000까지 20 단위로 지정할 수 있습니다. 검색의 sort_by는 latest 또는 top입니다. post-replies는 sort_by로 relevance, latest, likes도 받습니다.

수집 작업 제출하기

프로필 수집:

curl -X POST "https://api.socq.ai/v1/x/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["openai","@github"]}'

두 호스트 중 어느 쪽 URL로든 알고 있는 게시물 수집:

curl -X POST "https://api.socq.ai/v1/x/posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"]}'

사용자 게시물 구간 수집:

curl -X POST "https://api.socq.ai/v1/x/user-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["openai","github"],"results_limit":40}'

공개 게시물 검색:

curl -X POST "https://api.socq.ai/v1/x/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI lang:en","results_limit":100,"sort_by":"latest"}'

답글과 인용은 별도의 작업으로 수집:

curl -X POST "https://api.socq.ai/v1/x/post-replies" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20,"sort_by":"latest"}'
curl -X POST "https://api.socq.ai/v1/x/post-quotes" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20}'

반환된 작업 ID는 리소스 이름, 정규화한 입력값과 함께 저장하세요.

중복 없이 작업 폴링하기

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

queued와 running은 정상 상태로 취급하고, 지수 백오프를 사용하세요. 작업이 성공하면 data.results.items를 읽고, has_more가 true인 동안 next_cursor를 따라가세요.

안정적인 워커라면 다음 항목을 저장해야 합니다.

  • 배치 ID와 SocQ 작업 ID.
  • 리소스, 정규화한 사용자 이름·URL·검색어.
  • 제출 시각과 완료 시각.
  • 최종 상태와 오류 분류.
  • 마지막으로 처리한 결과 커서.

워커가 재시작되었다고 해서 같은 검색을 다시 제출할 이유는 없습니다.

반환 필드 이해하기

레코드는 id, platform, resource, type, url, created_at, collected_at, extra를 공통으로 가집니다.

프로필에는 username, name, description, avatar_url, cover_url, is_verified, is_private, 표시되는 수치가 포함됩니다. 보호된 계정은 공개 데이터의 대상이 아닙니다.

게시물에는 text, language, author, 표시되는 수치, media가 있고, 공개된 경우 hashtags와 mentions도 포함됩니다. 엔티티 키로는 id를, 출처로는 게시물 URL을 사용하는 것이 좋습니다.

답글과 인용은 게시물과 같은 구조를 쓰고, 리포스트한 사용자는 프로필과 같은 구조를 씁니다. 트렌드는 위치 기준의 탐색 행이며 게시물이 아닙니다.

삭제되었거나 비공개인 게시물은 입력 단계나 작업 단계에서 실패해야 합니다. 빈 게시물을 넣거나, 참여도를 0으로 지어내거나, collected_at을 created_at으로 대신 쓰지 마세요.

검색 결과는 순위가 매겨진 탐색 결과입니다. latest와 top은 제한된 구간을 서로 다른 순서로 정렬한 것이며, 과거 전체를 담은 아카이브가 아닙니다.

프로필·게시물·검색용 Python 워커

import time
import requests

BASE = "https://api.socq.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {SOCQ_API_KEY}",
    "Content-Type": "application/json",
}

def collect(resource, payload):
    created = requests.post(
        f"{BASE}/x/{resource}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    created.raise_for_status()
    task_id = created.json()["data"]["task_id"]

    delay = 2
    while True:
        response = requests.get(
            f"{BASE}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()["data"]

        if task["status"] == "succeeded":
            return task["results"]["items"]
        if task["status"] in {"failed", "cancelled"}:
            raise RuntimeError(task)

        time.sleep(delay)
        delay = min(delay * 1.5, 15)

profiles = collect("profiles", {"usernames": ["openai"]})
hits = collect("search", {
    "query": "AI lang:en",
    "results_limit": 40,
    "sort_by": "latest",
})

실서비스에 적용하기 전에 커서 페이지네이션, 타임아웃과 재시도 가능한 5xx 응답에 대한 제한된 재시도, 멱등한 upsert를 추가하세요.

게시물과 지표 스냅샷을 분리해서 모델링하기

게시물의 신원 정보와 지표는 변하는 속도가 서로 다릅니다.

x_entity
  resource
  platform_id
  canonical_url_or_username
  text_or_description
  author_id
  created_at
  first_seen_at
  last_seen_at

x_snapshot
  resource
  platform_id
  collected_at
  likes_count
  replies_count
  reposts_count
  quotes_count
  source_task_id

resource + id로 upsert하세요. 인용, 답글, 원본 게시물을 같은 게시물 테이블에 저장하려면 resource가 필수 열로 유지되어야 합니다. 리포스트한 사용자는 프로필 테이블이나 관계(edge) 테이블에 보관하세요.

리포스트한 사용자의 스냅샷으로 인용 증가량을 계산하지 마세요. 두 지표는 서로 바꿔 쓸 수 없습니다.

저장하기 전에 검증하기

  • platform은 x여야 합니다.
  • resource는 호출한 엔드포인트와 일치해야 합니다.
  • 리소스가 게시물 형태라면 게시물 URL에 숫자 /status/ ID가 있어야 합니다.
  • 리소스가 user-posts이고 필드가 있다면 작성자 사용자 이름이 제출한 계정과 일치해야 합니다.
  • 수치는 음수가 아닌 숫자이거나 null이어야 합니다.
  • 타임스탬프는 파싱되어야 합니다.
  • 실패한 비공개·삭제 입력이 성공한 빈 게시물이 되어서는 안 됩니다.

유효하지 않은 행은 원본 작업 페이로드와 함께 격리 영역에 보관하세요.

엔티티별 갱신 주기 정하기

엔티티권장 시작 주기이유
프로필주 1회 또는 월 1회소개와 신원 필드는 천천히 바뀜
알고 있는 게시물활성 기간에는 1시간~1일공개 지표가 빠르게 변함
사용자 게시물 구간모니터링 시 1시간~1일타임라인은 구간이 제한되고 순위가 매겨짐
검색검색어에 맞는 일정latest와 top은 아카이브가 아님
답글 / 인용게시물이 활발한 동안 1시간마다대화 관계는 몰아서 들어옴
팔로워 / 팔로잉주 1회목록이 크고 200 단위로 지정됨
트렌드1시간마다 또는 하루 몇 차례WOEID 세트가 교체됨

비즈니스 질문에 더 최신인 스냅샷이 필요하지 않다면 수집 빈도를 줄이세요.

자주 발생하는 문제

게시물 URL이 아무것도 반환하지 않음

URL이 공개 상태이고, 아직 열람할 수 있으며, /status/{id}를 포함하는지 확인하세요. 삭제되었거나 보호된 게시물은 깔끔하게 실패해야 합니다. 입력 단위의 오류는 그대로 보존하세요.

검색 결과가 불완전해 보임

results_limit은 요청의 상한입니다. 순위, 인덱싱, latest와 top 전환 모두 결과 페이지를 바꿉니다. 검색어와 정렬 방식을 레코드와 함께 저장하세요.

인용이 리포스트로 저장됨

둘은 서로 다른 엔드포인트이자 서로 다른 객체입니다. 기본 키에 resource를 포함하세요.

팔로워 작업이 제한 값을 거부함

팔로워와 팔로잉은 200부터 2000까지 200 단위로 지정할 수 있습니다. User-posts와 search는 20 단위입니다.

지표가 브라우저와 다름

공개 수치는 스냅샷입니다. 지연되거나, 반올림되거나, 숨겨질 수 있습니다. 파서를 의심하기 전에 collected_at부터 비교하세요.

같은 사용자가 두 번 나타남

사용자 이름을 정규화하고 안정적인 공개 ID를 우선하세요. 계정 이름이 바뀔 때를 대비해 별칭 테이블을 두세요.

X 데이터의 책임 있는 사용

정당한 목적에 필요한 공개 필드만 수집하세요. 보호된 계정, 차단, 로그인 장벽 등 접근 제어를 우회하지 마세요. 민감한 개인 프로파일링이나, 안전장치 없이 개인에게 중대한 영향을 줄 수 있는 자동화된 결정은 피하세요.

X 데이터는 개인정보일 수 있습니다. 필요한 경우 적법한 근거를 마련하고, 보관 및 삭제 규칙을 정하고, API 키와 내보낸 파일을 보호하고, X의 최신 약관을 자격 있는 법률 전문가와 함께 검토하세요. 공개 데이터 API를 쓴다고 해서 게시물이나 미디어를 재게시할 권리가 생기는 것은 아닙니다.

자주 묻는 질문(FAQ)

X나 Twitter 스크래핑은 합법인가요?

모든 경우에 통하는 답은 없습니다. 관할권, 데이터, 방법, 목적, 계약, 안전장치에 따라 달라집니다. 이 튜토리얼은 법률 자문이 아닙니다.

공식 X API를 대체할 수 있나요?

아니요. 게시, DM, 광고, 스트림 등 권한이 필요한 작업에는 여전히 공식 접근이 필요합니다. SocQ는 지원되는 공개 읽기를 다룹니다.

비공개 게시물이나 삭제된 게시물도 수집할 수 있나요?

아니요. 이런 입력은 깔끔하게 실패해야 합니다. 보호 조치를 우회하지 마세요.

인용과 리포스트는 같은가요?

아니요. 인용은 게시물이고, 리포스트한 사용자는 프로필입니다. 답글은 세 번째 리소스입니다.

검색은 전체 내역을 반환하나요?

아니요. 하나의 검색어에 대해 제한되고 정렬된 구간을 반환합니다.

중복 제거에는 어떤 키를 써야 하나요?

resource + id를 우선 사용하세요. 공개 ID가 없으면 정규화한 게시물 URL이나 사용자 이름을 대신 쓰세요.

X API

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

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

X API 살펴보기