功能描述

Search X (Twitter) in real time. Find posts by keyword, user, or hashtag. Get a user's timeline, replies, retweeters, or fetch specific posts by ID or URL. S...

使用说明 (SKILL.md)

X (Twitter) Search By Desearch

Name: X (Twitter) Search by Desearch
Author: okradze

Real-time X/Twitter search and monitoring. Search posts, track users, get timelines, replies, and retweeters with powerful filtering.

Setup

Get an API key from https://console.desearch.ai
Set environment variable: export DESEARCH_API_KEY='your-key-here'

Common Fields

All tweet-returning endpoints share these shapes. Fields marked * are always present.

Tweet

Field	Type	Description
`id`*	string	Post ID
`text`*	string	Post content
`created_at`*	string	ISO 8601 timestamp
`url`	string\|null	Direct link: `https://x.com/{username}/status/{id}`
`like_count`*	int	Likes
`retweet_count`*	int	Retweets
`reply_count`*	int	Replies
`quote_count`*	int	Quotes
`bookmark_count`*	int	Bookmarks
`view_count`	int\|null	Views
`lang`	string\|null	Language code (e.g. `en`)
`is_retweet`	bool\|null	Is a retweet
`is_quote_tweet`	bool\|null	Is a quote tweet
`conversation_id`	string\|null	Thread ID
`in_reply_to_screen_name`	string\|null	Username of post being replied to
`in_reply_to_status_id`	string\|null	ID of post being replied to
`media`	array\|null	`[{media_url, type}]` — type: `photo`, `video`, `animated_gif`
`entities`	object\|null	`{hashtags, symbols, urls, user_mentions}`
`quote`	Tweet\|null	Nested quoted tweet
`retweet`	Tweet\|null	Original tweet (timeline endpoint only)
`user`	User\|null	Post author — see User below

User

Field	Type	Description
`id`*	string	User ID
`username`*	string	@handle (without `@`)
`name`	string\|null	Display name
`url`	string\|null	Profile URL
`description`	string\|null	Bio
`followers_count`	int\|null	Followers
`followings_count`	int\|null	Following
`statuses_count`	int\|null	Total tweets posted
`verified`	bool\|null	Legacy verified badge
`is_blue_verified`	bool\|null	Twitter Blue subscriber
`location`	string\|null	Self-reported location
`created_at`	string\|null	Account creation date
`profile_image_url`	string\|null	Avatar URL

Endpoints

`x` — Search Posts

Search X posts by keyword, hashtag, or user with engagement filters.

scripts/desearch.py x "Bittensor TAO" --sort Latest --count 10
scripts/desearch.py x "AI news" --user elonmusk --start-date 2025-01-01
scripts/desearch.py x "crypto" --min-likes 100 --verified --lang en

Options:

Option	Description
`--sort`	`Top` (default) or `Latest`
`--user`, `-u`	Filter to posts by username
`--start-date`	Start date UTC (YYYY-MM-DD)
`--end-date`	End date UTC (YYYY-MM-DD)
`--lang`	Language code (e.g. `en`, `es`)
`--verified`	Only verified users
`--blue-verified`	Only Twitter Blue users
`--is-quote`	Only quote tweets
`--is-video`	Only posts with video
`--is-image`	Only posts with images
`--min-retweets`	Minimum retweet count
`--min-replies`	Minimum reply count
`--min-likes`	Minimum like count
`--count`, `-n`	Results count (default: 20, max: 100)

Response: Tweet[]

`x_post` — Retrieve Post by ID

Fetch a single post by its numeric ID.

scripts/desearch.py x_post 1892527552029499853

Response: Tweet

`x_urls` — Fetch Posts by URLs

Retrieve one or more posts by their X URLs.

scripts/desearch.py x_urls "https://x.com/user/status/123" "https://x.com/user/status/456"

Response: Tweet[]

`x_user` — Search Posts by User

Search within a specific user's posts for a keyword.

scripts/desearch.py x_user elonmusk --query "AI" --count 10

Options:

Option	Description
`--query`, `-q`	Keyword to filter the user's posts
`--count`, `-n`	Results count (default: 10, max: 100)

Response: Tweet[]

`x_timeline` — Get User Timeline

Fetch the most recent posts from a user's timeline. Retweets include a retweet field with the original post.

scripts/desearch.py x_timeline elonmusk --count 20

Options:

Option	Description
`--count`, `-n`	Number of posts (default: 20, max: 100)

Response: { user: User, tweets: Tweet[] }

`x_retweeters` — Get Retweeters of a Post

List users who retweeted a specific post. Supports cursor-based pagination.

scripts/desearch.py x_retweeters 1982770537081532854
scripts/desearch.py x_retweeters 1982770537081532854 --cursor "AAAAANextCursorValue=="

Options:

Option	Description
`--cursor`	Pagination cursor from a previous response

Response: { users: User[], next_cursor: string|null } — next_cursor is null when no more pages remain.

`x_replies` — Get User's Replies

Fetch a user's tweets-and-replies timeline. Replies have in_reply_to_screen_name and in_reply_to_status_id set.

scripts/desearch.py x_replies elonmusk --count 10
scripts/desearch.py x_replies elonmusk --query "AI" --count 10

Options:

Option	Description
`--count`, `-n`	Results count (default: 10, max: 100)
`--query`, `-q`	Filter keyword

Response: Tweet[]

`x_post_replies` — Get Replies to a Post

Fetch replies to a specific post by ID.

scripts/desearch.py x_post_replies 1234567890 --count 10
scripts/desearch.py x_post_replies 1234567890 --query "thanks" --count 5

Options:

Option	Description
`--count`, `-n`	Results count (default: 10, max: 100)
`--query`, `-q`	Filter keyword within replies

Response: Tweet[]

Errors

Status 401, Unauthorized (e.g., missing/invalid API key)

{
  "detail": "Invalid or missing API key"
}

Status 402, Payment Required (e.g., balance depleted)

{
  "detail": "Insufficient balance, please add funds to your account to continue using the service."
}

Resources

安全使用建议

This skill sends your queries and the DESEARCH_API_KEY to desearch.ai rather than calling X/Twitter directly — only install if you trust that service and its privacy/usage policies. Keep DESEARCH_API_KEY secret and scoped appropriately. Review rate limits, billing, and the Desearch website (https://desearch.ai) before use. If you need stricter guarantees, inspect the code yourself or run the included script in an isolated environment; there are no other requested credentials or unexpected behaviors in the provided files.

功能分析

Type: OpenClaw Skill Name: desearch-x-search Version: 1.0.1 The skill bundle provides a CLI client for the Desearch X (Twitter) API. The `SKILL.md` documentation is purely descriptive, outlining the skill's purpose, setup, and usage, without any prompt injection attempts or manipulative instructions for the AI agent. The `scripts/desearch.py` code correctly retrieves the `DESEARCH_API_KEY` from environment variables, makes network requests only to the legitimate `api.desearch.ai` endpoint, and uses standard Python libraries (`argparse`, `urllib`, `json`) to safely handle and encode user inputs, preventing command or shell injection. There is no evidence of data exfiltration, malicious execution, persistence mechanisms, or obfuscation. The code's behavior is entirely aligned with its stated purpose.

能力评估

✓ Purpose & Capability

The skill advertises X/Twitter search functionality and requires a single DESEARCH_API_KEY. The bundled script calls https://api.desearch.ai endpoints and implements the advertised commands (search, timeline, retweeters, etc.), so the declared capability matches the required artifact and env var.

✓ Instruction Scope

SKILL.md and the script only instruct the agent to call Desearch endpoints and format results; there are no instructions to read unrelated files, other environment variables, or to transmit data to unexpected endpoints. All network calls target api.desearch.ai as expected.

✓ Install Mechanism

No install spec is provided (instruction-only skill with a small included CLI script). Nothing is downloaded from arbitrary URLs and no installers/run-on-install actions are present.

✓ Credentials

Only DESEARCH_API_KEY is required and it is used to authorize requests to desearch.ai. No unrelated secrets, tokens, or config paths are requested. The amount of environment access is proportional to the skill's function.

✓ Persistence & Privilege

The skill does not request always:true or any elevated platform privileges. It does not modify other skills or system-wide settings. Normal autonomous invocation is allowed (platform default).

版本历史

v1.0.1

- Expanded documentation with detailed response schemas for tweets and users. - Added explicit field descriptions for all tweet-returning endpoints. - Clarified available endpoints, their options, and typical response shapes. - Included example error messages for common authentication and billing issues. - Provided links to official API reference and developer console.

v1.0.0

Initial release of desearch-x-search: real-time advanced X (Twitter) search & monitoring. - Search X posts in real time by keyword, user, or hashtag, with advanced filters (date range, language, engagement thresholds, media type). - Retrieve user timelines, post replies, retweeters, or fetch specific posts by ID or URL. - Includes multiple subcommands: x, x_post, x_urls, x_user, x_timeline, x_retweeters, x_replies, x_post_replies. - Easy setup with DESEARCH_API_KEY environment variable. - Comprehensive usage examples and command options in documentation.

元数据

Slug desearch-x-search

版本 1.0.1

许可证 —

累计安装 4

当前安装数 4

历史版本数 2

常见问题