X/Twitter API docs

X/Twitter API: Search — Posts by query

Discover Search data on X/Twitter from a user query and connect the results to search, catalog, or research interfaces.

Use “Posts by query” when an exact object ID is not known and relevant candidates must be found first.

Method GET
Entity Search
Versions 2
What this endpoint does

What you can build with this API method

Review the result and common workflows first, then move to parameters and a working request example.

What this endpoint helps with

The response includes matching Search, public context, and pagination data when more results are available.

When to use it

Use “Posts by query” when an exact object ID is not known and relevant candidates must be found first.

Common use cases

In-product search

Add X/Twitter data search to customer-facing and internal interfaces.

Catalog building

Find candidates by query and save relevant objects for later enrichment.

Market research

Collect result sets for topic, creator, and competitive analysis.

Available versions

Response version

Both versions solve the same job and accept the same parameters. Use the switch to compare the response structure and choose the version your client expects.

Response version V2

Switch versions on this page to compare response structures while keeping the same documentation URL.

What stays the same

Authentication, required parameters, and the request shape stay the same across V1 and V2. In practice, you choose the version when you build the endpoint path and when you parse the response.

What changes between versions

The main difference is the response envelope. Use V2 for new integrations and keep V1 only when you need compatibility with an existing client contract.

How to use it

How to call the method

Use the same API key header and the same query parameters for both versions. This documentation shows the shared parameter set first, then version-specific endpoint paths and code snippets.

Input parameters

Shared parameters
Parameter Required Type Example Description
query Yes str value User-entered search query.
all_of_these_words No str | None value Optional words that must all appear in matching Twitter/X posts. Example: AI robotics.
any_of_these_words No str | None value Optional words where any one may appear in matching Twitter/X posts. Example: launch release.
cursor No str | None QVFB... Next-page cursor returned by the previous response. Omit it for the first page.
exact_phrase No str | None value Optional exact phrase that must appear in matching Twitter/X posts. Example: machine learning.
from_accounts No str | None value Optional source accounts without or with @, separated by spaces or commas. Example: technews xai.
hashtags No str | None value Optional hashtags to require, separated by spaces or commas. Example: #TechNews #AI.
language No str | None value Optional Twitter/X language code. Use 'any' to omit language filtering. Example: en.
link_filter No include | only | exclude | None value Optional link filter: include all posts, only posts with links, or exclude links. Example: only.
mentioning_accounts No str | None value Optional mentioned accounts without or with @, separated by spaces or commas. Example: technews elonmusk.
min_likes No int | None value Optional minimum like count. Example: 100.
min_replies No int | None value Optional minimum reply count. Example: 10.
min_retweets No int | None value Optional minimum repost/retweet count. Example: 25.
none_of_these_words No str | None value Optional words to exclude from matching Twitter/X posts. Example: rumor leak.
reply_filter No include | only | exclude | None value Optional reply filter: include all posts, only replies, or exclude replies. Example: exclude.
since_date No date | None value Optional earliest post date in ISO YYYY-MM-DD format. Example: 2026-01-01.
tag No Top | Latest | People | Photos | Videos | None value Optional Twitter/X search product filter. Example: Latest.
to_accounts No str | None value Optional reply target accounts without or with @, separated by spaces or commas. Example: technews.
until_date No date | None value Optional latest post date in ISO YYYY-MM-DD format. Example: 2026-01-31.

Version-specific request path

V2

Choose a version when you copy the exact endpoint path, example URL, and code snippet. The parameter list above stays the same.

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

Normalized format

Code examples

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=value' \
  # Optional parameters:
  # --data-urlencode 'all_of_these_words=value'
  # --data-urlencode 'any_of_these_words=value'
  # --data-urlencode 'cursor=QVFB...'
  # --data-urlencode 'exact_phrase=value'
  # --data-urlencode 'from_accounts=value'
  # --data-urlencode 'hashtags=value'
  # --data-urlencode 'language=value'
  # --data-urlencode 'link_filter=value'
  # --data-urlencode 'mentioning_accounts=value'
  # --data-urlencode 'min_likes=value'
  # --data-urlencode 'min_replies=value'
  # --data-urlencode 'min_retweets=value'
  # --data-urlencode 'none_of_these_words=value'
  # --data-urlencode 'reply_filter=value'
  # --data-urlencode 'since_date=value'
  # --data-urlencode 'tag=value'
  # --data-urlencode 'to_accounts=value'
  # --data-urlencode 'until_date=value'
Response example

Live response by version

The preview keeps key fields and the first collection items so you can scan the response shape quickly. Switching versions changes the JSON format.

Response example

V2 response JSON

Verified example

This compact JSON example comes from the latest successful verification run for 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
        }
      ]
    }
  }
}
What to do next

Continue the evaluation

Use this documentation as the first decision point, then move into pricing, platform coverage, and integration rules before you connect the endpoint for recurring use.

Open the X/Twitter platform page

Compare adjacent entities, API method groups, and related docs before implementation.

Open platform page

Compare API method pricing

Check where this API method sits inside the public price table before you scale usage.

View pricing

Review integration rules

Use the starter docs to confirm authentication, versioning, retries, and mock vs live behavior.

Open docs
FAQ

Questions teams ask before implementation

Use these answers to decide whether this API method fits your workflow, versioning choice, and rollout plan.

What data does this X/Twitter API method return?

The method performs “Posts by query” for Search. The compact response example below shows the exact field structure.

Should I choose V1 or V2?

Choose V2 for new integrations because it provides a normalized structure. Use V1 only for compatibility with clients that already consume the platform-native format.

What do I need for the first request?

Create an API key, send it in the request header, and provide the required parameters from the table. The code samples already contain the correct path and request structure.