- name
- desearch-x-search
- description
- 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. Supports advanced filters like date range, language, engagement thresholds, and media type.
- metadata
- {"clawdbot":{"emoji":"𝕏","homepage":"https://desearch.ai","requires":{"env":["DESEARCH_API_KEY"]}}}
X (Twitter) Search By Desearch
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 enOptions:
| 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 1892527552029499853Response: 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 10Options:
| 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 20Options:
| 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 10Options:
| 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 5Options:
| 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."
}