API 문서

공개 X 데이터용 REST API예요. 프로필, 트윗, 검색, 팔로워, 리스트, 트렌드를 다뤄요. 모든 엔드포인트는 GET이고, JSON을 돌려주며, 아래에 적힌 고정 token 수만큼 들어요. 새 계정은 이메일을 확인하면 token 1,000개를 받아요.

AI 에이전트로 개발 중인가요? MCP 서버와 스킬로 Claude, Cursor, VS Code를 같은 엔드포인트에 연결해요.

빠른 시작

계정을 만들어요. 이메일도 확인해요.
API 키 페이지에서 API 키를 만들어요. 한 번만 보이니 안전한 곳에 저장해요.
이 키를 x-api-key 헤더에 넣어요:

요청

curl "https://api.xscraper.online/api/v1/twitter/users/profile_by_username/jack" \
  -H "x-api-key: $XSCRAPER_KEY"

인증

모든 요청에 x-api-key: <your key>가 필요해요. 키는 xs_로 시작해요. 계정당 키는 하나예요. 교체하면 새 키가 나오고 이전 키는 바로 멈춰요. 키는 서버에만 둬요. 브라우저나 모바일 코드에는 넣지 않아요.

token과 가격

호출마다 그 엔드포인트 가격만큼 token이 들어요. count를 받는 엔드포인트는 기본 가격에 결과 한 페이지 가격을 더해요. 그래서 더 많이 요청하면 더 비싸요. 요금은 호출이 성공할 때만 나가요. 오류 응답은 돌려주지만, 404 (없음)은 실제 결과라서 요금이 나가요. 모든 응답은 x-tokens-cost와 x-tokens-remaining을 알려요.

엔드포인트	경로	최소	최대
트윗
사용자 트윗/users/tweets/:username	/users/tweets/:username	3	7
최신 트윗/users/latest_tweet/:username	/users/latest_tweet/:username	1	1
사용자 트윗과 답글/users/replies/:username	/users/replies/:username	3	7
사용자 ID로 트윗/users/tweets_by_user_id/:userId	/users/tweets_by_user_id/:userId	3	7
사용자 ID로 트윗과 답글/users/replies_by_user_id/:userId	/users/replies_by_user_id/:userId	3	7
좋아요한 트윗/users/likes/:username	/users/likes/:username	4	8
ID로 트윗/tweets/:tweetId	/tweets/:tweetId	1	1
트윗 답글/tweets/:tweetId/replies	/tweets/:tweetId/replies	4	4
인용 트윗/tweets/:tweetId/quotes	/tweets/:tweetId/quotes	4	4
검색
사용자 검색/users/search_profiles	/users/search_profiles	4	6
트윗 검색/tweets/search	/tweets/search	6	14
고급 검색/tweets/advanced_search	/tweets/advanced_search	8	12
프로필
사용자 이름으로 프로필/users/profile_by_username/:username	/users/profile_by_username/:username	1	1
사용자 ID로 프로필/users/profile_by_userid/:userId	/users/profile_by_userid/:userId	3	3
사용자 이름을 사용자 ID로/users/user_id/:username	/users/user_id/:username	1	1
소셜
팔로워/users/followers/:userId	/users/followers/:userId	4	4
팔로잉/users/following/:userId	/users/following/:userId	4	4
리스트
리스트 트윗/lists/:listId/tweets	/lists/:listId/tweets	3	7
트렌드
트렌드/trends	/trends	2	2
계정
token 잔액/balance	/balance	0	0

응답

성공이든 오류든 모든 응답은 같은 형식이에요. 내용은 data에 있어요.

성공

{
  "success": true,
  "message": "Profile for @jack",
  "data": {
    "userId": "12",
    "username": "jack"
  },
  "errors": null
}

오류 (402)

{
  "success": false,
  "message": "Not enough tokens: this call costs 14 and your balance is 10.",
  "data": null,
  "errors": [
    {
      "field": "balance",
      "message": "insufficient_tokens"
    }
  ]
}

오류

상태	의미
400	매개변수가 없거나 잘못됐어요. 어느 것인지는 메시지에 있어요.
401	x-api-key가 없거나, 알 수 없거나, 폐기됐어요.
402	잔액이 이 호출의 가격보다 적어요. 차감은 없었어요.
403	이 엔드포인트는 관리자 키가 필요해요.
404	사용자나 리스트가 없거나 보이지 않아요 (없는 트윗은 data: null을 돌려줘요). 요금은 나가요. 조회는 실행됐어요.
429	계정에서 1분에 요청이 너무 많거나, 한 번에 너무 많아요. Retry-After의 초만큼 기다려요.
503	스크레이퍼 풀이 바빠요. Retry-After 헤더 이후에 다시 시도해요.
5xx	업스트림 실패예요. 다시 시도해도 돼요.

속도 제한

키마다 1분에 요청 100번을 보낼 수 있어요. 응답에는 X-RateLimit-Limit과 X-RateLimit-Remaining이 있고, 429에는 Retry-After도 있어요. 제한에 걸린 호출은 요금이 없어요.

모든 엔드포인트

같은 목록을 OpenAPI 3.1 명세로도 받을 수 있어요. 주소는 /openapi.json이고, AI 에이전트용 일반 텍스트 요약은 /llms.txt예요.