X/Twitter API 문서

X/Twitter API: 검색 — 검색어별 게시물

사용자 검색어로 X/Twitter의 검색 데이터를 찾고 결과를 검색, 카탈로그, 리서치 화면에 연결하세요.

객체의 정확한 ID를 모르고 먼저 관련 후보를 찾아야 할 때 "검색어별 게시물"을 사용하세요.

메서드 GET
엔터티 검색
버전 2
이 엔드포인트가 하는 일

이 API 메서드로 만들 수 있는 것

먼저 결과와 일반적인 워크플로를 확인한 다음 매개변수와 작동하는 요청 예제로 넘어가세요.

이 엔드포인트가 도움이 되는 일

응답에는 일치하는 검색, 공개 컨텍스트, 결과가 더 있을 경우 페이지네이션 데이터가 포함됩니다.

적합한 사용 시점

객체의 정확한 ID를 모르고 먼저 관련 후보를 찾아야 할 때 "검색어별 게시물"을 사용하세요.

주요 사용 사례

제품 내 검색

고객용 및 내부 화면에 X/Twitter 데이터 검색을 추가하세요.

카탈로그 구축

검색어로 후보를 찾고 관련 객체를 저장해 나중에 보강하세요.

시장 조사

주제, 크리에이터, 경쟁 분석을 위한 결과 집합을 수집하세요.

사용 가능한 버전

응답 버전

두 버전 모두 같은 작업을 해결하며 같은 매개변수를 받습니다. 전환기로 응답 구조를 비교하고 클라이언트가 기대하는 버전을 선택하세요.

응답 버전 V2

이 페이지에서 버전을 전환하면 같은 문서 URL에서 응답 구조를 비교할 수 있습니다.

동일하게 유지되는 것

인증, 필수 매개변수, 요청 형태는 V1과 V2에서 같습니다. 실제로는 엔드포인트 경로를 구성할 때와 응답을 읽을 때 버전을 선택합니다.

버전 간에 달라지는 것

주요 차이는 응답 봉투입니다. 새 연동에는 V2를 사용하고, 기존 클라이언트 계약과의 호환성이 필요한 경우에만 V1을 유지하세요.

사용 방법

메서드 호출 방법

두 버전 모두 같은 API 키 헤더와 같은 쿼리 매개변수를 사용합니다. 이 문서는 먼저 공통 매개변수를 보여 준 다음 각 버전의 경로와 코드 스니펫을 보여 줍니다.

입력 매개변수

공통 매개변수
매개변수 필수 유형 예시 설명
query 예 str technology 사용자가 입력한 검색어.
all_of_these_words 아니요 str | None AI robotics Optional words that must all appear in matching Twitter/X posts. Example: AI robotics.
any_of_these_words 아니요 str | None launch release Optional words where any one may appear in matching Twitter/X posts. Example: launch release.
cursor 아니요 str | None DAABCgABF4ABCD... 이전 응답에서 받은 다음 페이지 커서. 첫 페이지에서는 생략합니다.
exact_phrase 아니요 str | None machine learning Optional exact phrase that must appear in matching Twitter/X posts. Example: machine learning.
from_accounts 아니요 str | None technews xai Optional source accounts without or with @, separated by spaces or commas. Example: technews xai.
hashtags 아니요 str | None #TechNews #AI Optional hashtags to require, separated by spaces or commas. Example: #TechNews #AI.
language 아니요 str | None en Optional Twitter/X language code. Use 'any' to omit language filtering. Example: en.
link_filter 아니요 include | only | exclude | None only Optional link filter: include all posts, only posts with links, or exclude links. Example: only.
mentioning_accounts 아니요 str | None technews elonmusk Optional mentioned accounts without or with @, separated by spaces or commas. Example: technews elonmusk.
min_likes 아니요 int | None 100 Optional minimum like count. Example: 100.
min_replies 아니요 int | None 10 Optional minimum reply count. Example: 10.
min_retweets 아니요 int | None 25 Optional minimum repost/retweet count. Example: 25.
none_of_these_words 아니요 str | None rumor leak Optional words to exclude from matching Twitter/X posts. Example: rumor leak.
reply_filter 아니요 include | only | exclude | None exclude Optional reply filter: include all posts, only replies, or exclude replies. Example: exclude.
since_date 아니요 date | None 2026-01-01 Optional earliest post date in ISO YYYY-MM-DD format. Example: 2026-01-01.
tag 아니요 Top | Latest | People | Photos | Videos | None Latest Optional Twitter/X search product filter. Example: Latest.
to_accounts 아니요 str | None technews Optional reply target accounts without or with @, separated by spaces or commas. Example: technews.
until_date 아니요 date | None 2026-01-31 Optional latest post date in ISO YYYY-MM-DD format. Example: 2026-01-31.

버전별 요청 경로

V2

정확한 엔드포인트 경로, 예시 URL, 코드 스니펫을 복사할 때 버전을 선택하세요. 위의 매개변수 목록은 바뀌지 않습니다.

GET /api/v2/twitter.com/search/tweets-by-query

정규화된 형식

코드 예제

curl --request GET \
  --url "https://www.scrapestorm.net/api/v2/twitter.com/search/tweets-by-query" \
  --header "X-API-Key: 00000000-0000-4000-8000-000000000000" \
  --get --data-urlencode 'query=technology' \
  # Optional parameters:
  # --data-urlencode 'all_of_these_words=AI robotics'
  # --data-urlencode 'any_of_these_words=launch release'
  # --data-urlencode 'cursor=DAABCgABF4ABCD...'
  # --data-urlencode 'exact_phrase=machine learning'
  # --data-urlencode 'from_accounts=technews xai'
  # --data-urlencode 'hashtags=#TechNews #AI'
  # --data-urlencode 'language=en'
  # --data-urlencode 'link_filter=only'
  # --data-urlencode 'mentioning_accounts=technews elonmusk'
  # --data-urlencode 'min_likes=100'
  # --data-urlencode 'min_replies=10'
  # --data-urlencode 'min_retweets=25'
  # --data-urlencode 'none_of_these_words=rumor leak'
  # --data-urlencode 'reply_filter=exclude'
  # --data-urlencode 'since_date=2026-01-01'
  # --data-urlencode 'tag=Latest'
  # --data-urlencode 'to_accounts=technews'
  # --data-urlencode 'until_date=2026-01-31'
응답 예시

버전별 실제 응답

미리보기에는 주요 필드와 컬렉션의 첫 항목이 포함되어 있어 응답 형태를 빠르게 확인할 수 있습니다. 버전을 바꾸면 JSON 형식이 바뀝니다.

응답 예시

V2 응답 JSON

검증된 예시

이 간결한 JSON 예시는 V2의 최근 성공한 검증 실행에서 가져왔습니다.

{
  "success": true,
  "status": "ok",
  "pagination": {
    "cursor": "QVFB...",
    "has_more": true
  },
  "search_context": {
    "query": "Python code",
    "tag": "Top"
  },
  "data": {
    "tweets": {
      "count": 20,
      "items": [
        {
          "url": "https://x.com/freeCodeCamp/status/2078389573567050090",
          "tweet_id": "2078389573567050090",
          "text": "Learning to code can feel overwhelming when you don't know where to start.\n\nSo here's a course for you: Sunny teaches you Python from the ground up.\n\nYou'll install Python, writ…",
          "hashtags": [],
          "emails": [],
          "created_at": "2026-07-18T08:01:03Z",
          "language": "en",
          "source": "Buffer",
          "author": {
            "url": "https://x.com/freeCodeCamp",
            "user_id": "1668100142",
            "username": "freeCodeCamp",
            "display_name": "freeCodeCamp.org",
            "description": "We're a community of millions of people who are building new skills and getting new jobs together. A 501(c)(3) public charity. Tweets by @abbeyrenn.",
            "emails": [],
            "external_links": [],
            "location": "Just here on Earth... for now",
            "created_at": "2013-08-13T15:27:51Z",
            "is_verified": false,
            "is_blue_verified": true,
            "is_protected": false,
            "possibly_sensitive": false,
            "default_profile": false,
            "default_profile_image": false,
            "followers_count": 1204998,
            "following_count": 159,
            "tweet_count": 36772,
            "media_count": 5153,
            "listed_count": 6833,
            "like_count": 72305,
            "professional_type": null,
            "professional_category_name": null,
            "affiliated_account": null,
            "_more_fields": "5 more fields"
          },
          "is_from_automated_account": null,
          "media": {
            "images": [
              "…"
            ],
            "videos": [],
            "gifs": []
          },
          "external_links": [],
          "user_mentions": [],
          "is_reply": false,
          "reply": null,
          "is_quote": false,
          "quote_tweet_id": null,
          "is_retweet": false,
          "retweeted_tweet_id": null,
          "reply_count": 4,
          "retweet_count": 108,
          "quote_count": 3,
          "like_count": 599,
          "bookmark_count": 455,
          "_more_fields": "2 more fields"
        },
        {
          "url": "https://x.com/PythonPr/status/2078910492068786514",
          "tweet_id": "2078910492068786514",
          "text": "Pyramids in Python Code Examples for Beginners ⭐ https://t.co/QngwbiMVkb",
          "hashtags": [],
          "emails": [],
          "created_at": "2026-07-19T18:31:00Z",
          "language": "en",
          "source": "Twitter Web App",
          "author": {
            "url": "https://x.com/PythonPr",
            "user_id": "855384627975831553",
            "username": "PythonPr",
            "display_name": "Python Programming",
            "description": "#python #programming",
            "emails": [],
            "external_links": [],
            "location": "United States",
            "created_at": "2017-04-21T11:36:02Z",
            "is_verified": false,
            "is_blue_verified": true,
            "is_protected": false,
            "possibly_sensitive": false,
            "default_profile": true,
            "default_profile_image": false,
            "followers_count": 208924,
            "following_count": 1162,
            "tweet_count": 9883,
            "media_count": 4108,
            "listed_count": 1243,
            "like_count": 20597,
            "professional_type": null,
            "professional_category_name": null,
            "affiliated_account": null,
            "_more_fields": "5 more fields"
          },
          "is_from_automated_account": null,
          "media": {
            "images": [
              "…"
            ],
            "videos": [],
            "gifs": []
          },
          "external_links": [],
          "user_mentions": [],
          "is_reply": false,
          "reply": null,
          "is_quote": false,
          "quote_tweet_id": null,
          "is_retweet": false,
          "retweeted_tweet_id": null,
          "reply_count": 3,
          "retweet_count": 8,
          "quote_count": 0,
          "like_count": 62,
          "bookmark_count": 39,
          "_more_fields": "2 more fields"
        },
        {
          "_more_items": 18
        }
      ]
    }
  }
}
다음 단계

평가 계속하기

이 문서를 첫 판단 기준으로 삼고, 반복 사용을 위해 엔드포인트를 연결하기 전에 요금, 플랫폼 지원 범위, 연동 규칙을 확인하세요.

X/Twitter 플랫폼 페이지 열기

구현 전에 관련 엔터티, API 메서드 그룹, 관련 문서를 비교하세요.

플랫폼 페이지 열기

API 메서드 요금 비교

사용량을 늘리기 전에 공개 요금표에서 이 메서드의 위치를 확인하세요.

요금 보기

연동 규칙 확인

시작 문서에서 인증, 버전, 재시도, 테스트와 운영의 차이를 확인하세요.

문서 열기
자주 묻는 질문

팀이 구현 전에 묻는 질문

이 답변을 참고하여 이 API 메서드가 워크플로, 버전 선택, 도입 계획에 맞는지 판단하세요.

이 X/Twitter API 메서드는 어떤 데이터를 반환하나요?

이 메서드는 검색에 대해 "검색어별 게시물"을 실행합니다. 아래의 간결한 응답 예시에서 필드의 정확한 구조를 확인할 수 있습니다.

V1과 V2 중 무엇을 선택해야 하나요?

새 연동에는 정규화된 구조를 제공하는 V2를 선택하세요. V1은 이미 플랫폼 고유 형식을 처리하는 클라이언트와의 호환성을 위해서만 사용하세요.

첫 요청에는 무엇이 필요한가요?

API 키를 만들어 요청 헤더에 넣고 표의 필수 매개변수를 입력하세요. 코드 예제에는 이미 올바른 경로와 요청 구조가 포함되어 있습니다.