x-tweet-search-by-query
Searches X (Twitter) for tweets by free-form advanced query and returns a normalized tweet list with text, author profile, engagement counts, media, hashtags, mentions, and cursor for pagination
Install / Use
npx skills add browser-act/skills --skill x-tweet-search-by-queryInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of x-tweet-search-by-query
x-tweet-search-by-query scores 93/100 on our quality scale, 622nd of 4,700 Development & Engineering skills we index (top 14%).
Its SKILL.md is 12 KB long, well organised into 14 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
With 6,001 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so x-tweet-search-by-query is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-06. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
x-tweet-search-by-query compared with similar skills
All 4 of these similar skills score higher than x-tweet-search-by-query; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| x-tweet-search-by-query (this skill)by browser-act | 93 | 6.0k | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install x-tweet-search-by-query?
- Run
npx skills add browser-act/skills --skill x-tweet-search-by-query. The install tabs above show the steps for each supported agent. - Which AI agents does x-tweet-search-by-query work with?
- It is written for Cursor and Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is x-tweet-search-by-query safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is x-tweet-search-by-query still maintained?
- The repository was last updated about 3 months ago, so x-tweet-search-by-query is actively maintained.
Skill content
View source on GitHubname: x-tweet-search-by-query description: "Searches X (Twitter) for tweets by free-form advanced query and returns a normalized tweet list with text, author profile, engagement counts, media, hashtags, mentions, and cursor for pagination. Use when user mentions X search, Twitter search, scrape tweets by keyword, search X by hashtag, search Twitter by hashtag, find tweets about a topic, search tweets by date range, since until search Twitter, advanced Twitter search, tweets with media, tweets with images, tweets with video, top tweets, latest tweets, X latest tab, X top tab, min_faves, min_retweets, min_replies, filter verified Twitter, filter blue verified, from user Twitter, to user Twitter, mentioning user Twitter, geocode Twitter search, near location Twitter, lang code search Twitter, exclude retweets, exclude replies, collect tweets at scale, bulk tweets export, monitor brand mentions on X, monitor brand mentions on Twitter, competitor mention monitoring, KOL tweet harvesting, twitter keyword scraper, tweet keyword scraper, search X by keyword, search twitter, search x.com, x.com search, twitter advanced search, x advanced search, tweet collection by query, scrape twitter search results. Also applies to time-bounded research, sentiment analysis input gathering, hashtag campaign tracking, geo-targeted tweet collection, and any paginated bulk tweet collection driven by a search query."
X — Tweet Search by Query
Advanced search query → normalized list of tweets matching the query (with author, engagement, media, cursor).
Language
All process output to user (progress updates, process notifications) follows the user's language.
Objective
Collect tweets that match an X advanced-search query expression, returning structured per-tweet data and pagination cursors for unbounded bulk collection.
Prerequisites
- Active X session in the browser (left sidebar shows logged-in avatar / @handle).
- Network capture is enabled in the browser-act session.
Pre-execution Checks
1. Tool Readiness
If browser-act has been confirmed available in the current session → skip this step.
Invoke browser-act via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.
2. Login Verification
If login status for X has been confirmed in the current session → skip this step.
Otherwise: open https://x.com and observe the left sidebar:
- User avatar or @handle visible at the bottom → logged in, continue
- "Sign in" / "Log in" prompt visible → not logged in, inform the user that an X login is required and assist the login flow
User refuses or cannot log in → terminate execution.
Capability Components
This Skill's operational boundary = what the user can manually do in their browser. It only reads tweet data rendered by the user's own X session, never bypassing authentication. Each search request is signed by X's own page JS; the Skill triggers it via URL navigation and reads structured GraphQL responses from network traffic. Python scripts under
scripts/only build URLs and parse responses — they do not call X directly. Run them through the bash tool.
Network Capture: search tweets via advanced query
All search parameters are encoded into X's native advanced search syntax via the URL builder, then injected through the page URL. The browser's own JS signs the GraphQL request; the response is read from network traffic and parsed locally.
Step 1 — build the search URL with all desired filters:
URL=$(python scripts/build-search-url.py '{raw_query}' --sort {sort} [--language {iso}] [--min-retweets {n}] [--min-faves {n}] [--min-replies {n}] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--author {handle}] [--in-reply-to {handle}] [--mentioning {handle}] [--only-verified] [--only-blue-verified] [--only-image] [--only-video] [--only-quote] [--exclude-retweets] [--exclude-replies] [--geocode LAT,LON,RADIUSmi] [--near 'PLACE'] [--within 15mi])
Parameters:
raw_query(positional): free-form X advanced search expression; all standard operators are supported and may already include any clause below. Operators added via flags are skipped if the same operator is already present inraw_query.--sort:Latest(default) orTop. Maps to URLf=liveandf=top, which select GraphQLproduct=Latestvsproduct=Top.--language: ISO 639-1 code, appended aslang:CODE.--min-retweets/--min-faves/--min-replies: integer thresholds, appended asmin_retweets:N/min_faves:N/min_replies:N.--since/--until:YYYY-MM-DD, appended assince:/until:.--author: only tweets from this handle, appended asfrom:HANDLE.--in-reply-to: only tweets replying to this handle, appended asto:HANDLE.--mentioning: only tweets mentioning this handle, appended as@HANDLE.--only-verified/--only-blue-verified: appended asfilter:verified/filter:blue_verified.--only-image/--only-video/--only-quote: appended asfilter:images/filter:native_video/filter:quote.--exclude-retweets/--exclude-replies: appended as-filter:retweets/-filter:replies.--geocode:LAT,LON,RADIUSmiorLAT,LON,RADIUSkm, appended asgeocode:LAT,LON,RADIUS.--near/--within: appended asnear:"PLACE"andwithin:VALUE.
Step 2 — navigate and capture the first page:
network requests --clearnavigate "$URL"wait stable --timeout 25000(a timeout is normal on X; proceed even if it fires — the GraphQL response usually completes before the page reaches network-idle)network requests --type xhr,fetch --filter SearchTimeline→ take the latest entry'srequest_idnetwork request <request_id>→ save full output to a file (e.g.tmp/x-search-page-1.txt)python scripts/parse-tweets.py --json-file tmp/x-search-page-1.txt --source search→ emits JSON{tweets, count, cursor_top, cursor_bottom}
Endpoint characteristic: URL contains /i/api/graphql/<hash>/SearchTimeline. The query hash rotates over time, so always filter by name SearchTimeline, never by hash.
Step 3 — paginate via scroll until the desired tweet count is reached or cursor_bottom no longer advances:
network requests --clearscroll down --amount 5000wait stable --timeout 10000network requests --type xhr,fetch --filter SearchTimeline→ take the newest entry'srequest_id(its variables now carry the cursor returned by the previous page)network request <request_id>→ save totmp/x-search-page-N.txtpython scripts/parse-tweets.py --json-file tmp/x-search-page-N.txt --source search
Repeat Step 3 until any of these termination conditions is met:
- The accumulated unique tweet count reaches the user's target
max_items. countreturns0for the current page.cursor_bottomis identical to the previous page (the timeline has been fully consumed).
Error handling: if network requests --filter SearchTimeline returns no entry after a scroll, the request may have been throttled or the timeline may have ended — wait 3 s and retry the scroll once. If still no new request appears after the second attempt and cursor_bottom did not change, stop the loop. If the response file's body is missing (only headers present), the URL is likely stale — re-navigate to the same URL and retry.
Output example:
{
"tweets": [
{
"type": "tweet",
"id": "2068333045510291908",
"url": "https://x.com/NASA/status/2068333045510291908",
"twitter_url": "https://twitter.com/NASA/status/2068333045510291908",
"text": "The official FIFA World Cup ball went to space! ...",
"created_at": "Thu Jun 20 18:30:11 +0000 2026",
"lang": "en",
"source": "Twitter Web App",
"retweet_count": 4586,
"reply_count": 1812,
"like_count": 24499,
"quote_count": 240,
"bookmark_count": 1730,
"view_count": 2098235,
"is_reply": false,
"is_retweet": false,
"is_quote": false,
"quote_id": null,
"quote_url": null,
"in_reply_to_id": null,
"in_reply_to_user": null,
"in_reply_to_user_id": null,
"conversation_id": "2068333045510291908",
"hashtags": ["FIFAWorldCup"],
"mentions": [],
"urls": [],
"media": [
{
"type": "photo",
"url": "https://pbs.twimg.com/media/abcd.jpg",
"expanded_url": "https://x.com/NASA/status/2068333045510291908/photo/1",
"alt_text": null
}
],
"card": null,
"place": null,
"author": {
"id": "11348282",
"user_name": "NASA",
"name": "NASA",
"url": "https://x.com/NASA",
"is_verified": false,
"is_blue_verified": true,
"verified_type": "Government",
"profile_picture": "https://pbs.twimg.com/profile_images/.../photo.jpg",
"description": "Explore the universe ...",
"location": "Pale Blue Dot",
"followers": 92137231,
"following": 305,
"created_at": "Wed Dec 19 20:20:32 +0000 2007"
}
}
],
"count": 20,
"cursor_top": "DAADDAABCgABHLoyRYoXoV4...",
"cursor_bottom": "DAADDAABCgABHLoyRYoXoV4..."
}
Pagination
Network Capture Pagination: triggered by scroll down. X's page JS inserts the previous response's cursor_bottom into the next SearchTimeline request's variables.cursor automatically. The Skill reads each new GraphQL response from network and merges tweets. Termination: count == 0, or cursor_bottom does not advance across two consecutive pages, or the user's max_items is reached.
Success Criteria
count >= 1 on the first page AND every tweet has non-null id, text, created_at, author.user_name, like_count, retweet_count, reply_count AND each subsequent page's cursor_bottom differs from the previous page's until termination.
Known Limitations
- The X advanced search index only surfaces public tweets; protected accounts are excluded regardless of filters.
view_countisnullfor very new or low-traffic tweets where X has not yet emittedviews.count; onlyviews.state == "EnabledWithCount"entries carry a number.- X applies aggressive rate limits on search; sustained polling at high concurrency triggers throttling. Stay under ~150 SearchTimeline calls per 15-minute window per session (the
x-rate-limit-remainingresponse header reveals the live budget). SearchTimelinequery hashes rotate; always discover requests by name (--filter SearchTimeline), never by hash.- The page may never reach
network-idle, sowait stablewill frequently time out; this is expected — proceed to read network traffic anyway. - Account-permission gates (NSFW filter on/off, blocked-user lists, locked region) carry over into search results and cannot be bypassed.
Execution Efficiency
- Batch orchestration: write a bash script that iterates queries serially in one session. Within a single search, paginate one page at a time. To parallelize across queries, open multiple stealth browser sessions, each logged in and rate-limited independently.
- Test before batch execution: run one query end-to-end (page 1 + page 2) before kicking off the full batch.
- Reduce redundant pre-operations: keep the same browser session for many sequential searches —
navigatereuses the existing X SPA without reload. - Error resumption: persist
cursor_bottomand the accumulated unique tweet IDs to disk after every page so a crash mid-batch can resume from the last good cursor. - De-duplicate by
id: when running with--sort "Latest + Top", the two passes may return overlapping tweets; merge byidto drop duplicates.
Experience Notes
Path: {working-directory}/browser-act-skill-forge-memories/x-tweet-scraper-x-tweet-search-by-query.memory.md (working directory is determined by the Agent running the Skill, typically the project root or current
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
