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

1. Get an API key from https://console.desearch.ai
2. 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

• API Reference
• Desearch Console