readx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

readx — Twitter/X Intelligence Toolkit

readx — Twitter/X智能工具包

Setup

安装配置

If readx MCP tools are already available, no setup is needed — just use them.

Otherwise, the user needs an API key. Direct them to https://readx.cc to sign up, then give them this command to save it (they replace

YOUR_KEY

themselves):

bash

mkdir -p ~/.config/readx && echo '{"api_key":"YOUR_KEY"}' > ~/.config/readx/credentials.json

After the API key is configured, recommend installing the MCP server for a better experience: https://readx.cc/mcp-setup

如果已经有readx MCP工具，则无需配置——直接使用即可。

否则，用户需要一个API密钥。引导他们前往**https://readx.cc**注册，然后使用以下命令保存密钥（自行替换`YOUR_KEY`）：

bash

mkdir -p ~/.config/readx && echo '{"api_key":"YOUR_KEY"}' > ~/.config/readx/credentials.json

配置好API密钥后，推荐安装MCP服务器以获得更好的体验：https://readx.cc/mcp-setup

When to Trigger This Setup

何时触发此配置

User asks you to look up Twitter data but no readx MCP tools are available and no API key is configured
Any tool call fails with auth/connection error

用户要求查询Twitter数据，但没有可用的readx MCP工具且未配置API密钥
任何工具调用因认证/连接错误失败

Direct API Mode

直接API模式

When MCP tools are NOT available (e.g. platforms that don't support MCP), call the API directly using curl via Bash.

当MCP工具不可用时（例如不支持MCP的平台），通过Bash使用curl直接调用API。

Getting the API Key

获取API密钥

Read in order, use the first one found:

Environment variable:
```
READX_API_KEY
```

Config file:

~/.config/readx/credentials.json

(macOS/Linux) or

%APPDATA%\readx\credentials.json

(Windows) →

{"api_key":"..."}

If neither exists, direct the user to set the environment variable or config file (get a key at https://readx.cc). Do NOT ask the user to paste the key in chat.

按以下顺序查找，使用第一个找到的密钥：

环境变量：
```
READX_API_KEY
```

配置文件：

~/.config/readx/credentials.json

（macOS/Linux）或

%APPDATA%\readx\credentials.json

（Windows）→

{"api_key":"..."}

如果两者都不存在，引导用户设置环境变量或配置文件（在https://readx.cc获取密钥）。请勿要求用户在聊天中粘贴密钥。

API Call Pattern

API调用模式

GET https://readx.cc/consumer/{Endpoint}?api_key=${READX_API_KEY}&param1=value1&param2=value2

All requests are GET with query parameters. Responses are JSON. Always reference the key via

${READX_API_KEY}

environment variable.

GET https://readx.cc/consumer/{Endpoint}?api_key=${READX_API_KEY}&param1=value1&param2=value2

所有请求均为带查询参数的GET请求。响应格式为JSON。请始终通过

${READX_API_KEY}

环境变量引用密钥。

Endpoints

端点

Users

用户

Endpoint	Params	Description
`UserResultByScreenName`	`username`	Get user profile by username
`UserResultByRestId`	`user_id`	Get user profile by ID
`UsernameToUserId`	`username`	Convert username to user_id
`FollowersLight`	`username` , `count?`	Get followers list
`FollowingLight`	`username` , `count?`	Get following list
`FollowingIds`	`username` , `count?` , `stringify_ids=true`	Get following IDs only
`UserVerifiedFollowers`	`user_id` , `cursor?`	Get verified followers
`FriendshipsShow`	`source_screen_name` , `target_screen_name`	Check relationship

端点	参数	描述
`UserResultByScreenName`	`username`	通过用户名获取用户资料
`UserResultByRestId`	`user_id`	通过ID获取用户资料
`UsernameToUserId`	`username`	将用户名转换为user_id
`FollowersLight`	`username` , `count?`	获取关注者列表
`FollowingLight`	`username` , `count?`	获取关注列表
`FollowingIds`	`username` , `count?` , `stringify_ids=true`	仅获取关注者ID
`UserVerifiedFollowers`	`user_id` , `cursor?`	获取已认证关注者
`FriendshipsShow`	`source_screen_name` , `target_screen_name`	检查用户关系

Tweets

推文

Endpoint	Params	Description
`UserTweets`	`user_id` , `cursor?`	Get user's tweets
`UserTweetsReplies`	`user_id` , `cursor?`	Get user's tweets and replies
`UserMedia`	`user_id` , `cursor?`	Get user's media posts
`TweetDetail`	`tweet_id`	Get tweet detail (minimal)
`TweetDetailv2`	`tweet_id`	Get tweet detail (preferred, includes views/source)
`TweetDetailv3`	`tweet_id`	Get tweet detail (includes view_count)
`TweetDetailConversation`	`tweet_id`	Get tweet with conversation thread
`TweetDetailConversationv2`	`tweet_id` , `cursor?`	Get tweet with full reply thread (preferred)
`TweetResultsByRestIds`	`tweet_ids` (comma-separated)	Batch get tweets
`TweetFavoriters`	`tweet_id` , `cursor?`	Get users who liked a tweet
`TweetRetweeters`	`tweet_id` , `cursor?`	Get users who retweeted
`TweetQuotes`	`tweet_id` , `cursor?`	Get quote tweets
`TweetArticle`	`tweet_id`	Get long-form article content

端点	参数	描述
`UserTweets`	`user_id` , `cursor?`	获取用户推文
`UserTweetsReplies`	`user_id` , `cursor?`	获取用户推文及回复
`UserMedia`	`user_id` , `cursor?`	获取用户媒体帖子
`TweetDetail`	`tweet_id`	获取推文详情（精简版）
`TweetDetailv2`	`tweet_id`	获取推文详情（推荐版，包含浏览量/来源）
`TweetDetailv3`	`tweet_id`	获取推文详情（包含浏览量统计）
`TweetDetailConversation`	`tweet_id`	获取推文及对话线程
`TweetDetailConversationv2`	`tweet_id` , `cursor?`	获取推文及完整回复线程（推荐版）
`TweetResultsByRestIds`	`tweet_ids` （逗号分隔）	批量获取推文
`TweetFavoriters`	`tweet_id` , `cursor?`	获取点赞该推文的用户
`TweetRetweeters`	`tweet_id` , `cursor?`	获取转发该推文的用户
`TweetQuotes`	`tweet_id` , `cursor?`	获取引用推文
`TweetArticle`	`tweet_id`	获取长文内容

Search

搜索

Endpoint	Params	Description
`Search`	`q` , `count?` , `type?` (Top/Latest), `cursor?` , `safe_search?`	Search tweets
`AutoComplete`	`q`	Search autocomplete suggestions

端点	参数	描述
`Search`	`q` , `count?` , `type?` (Top/Latest), `cursor?` , `safe_search?`	搜索推文
`AutoComplete`	`q`	获取搜索自动补全建议

Lists

列表

Endpoint	Params	Description
`ListTweetsTimeline`	`list_id` , `cursor?`	Get tweets from a list
`ListSubscribersTimeline`	`list_id` , `cursor?`	Get list subscribers
`ListMembersTimeline`	`list_id` , `cursor?`	Get list members
`ListSearch`	`q`	Search for lists

端点	参数	描述
`ListTweetsTimeline`	`list_id` , `cursor?`	获取列表中的推文
`ListSubscribersTimeline`	`list_id` , `cursor?`	获取列表订阅者
`ListMembersTimeline`	`list_id` , `cursor?`	获取列表成员
`ListSearch`	`q`	搜索列表

Communities

社区

Endpoint	Params	Description
`CommunityResultsById`	`community_id`	Get community details
`CommunitiesSearchSlice`	`q`	Search communities
`CommunityTimeline`	`community_id` , `type?` (Relevance/Recency), `time_filter?` (Day/Week/Month), `cursor?`	Get community tweets
`CommunityAboutTimeline`	`community_id` , `cursor?`	Get community media
`CommunityMembers`	`community_id`	Get community members
`CommunityModerators`	`community_id`	Get community moderators
`CommunityMemberSearch`	`community_id` , `q`	Search community members

端点	参数	描述
`CommunityResultsById`	`community_id`	获取社区详情
`CommunitiesSearchSlice`	`q`	搜索社区
`CommunityTimeline`	`community_id` , `type?` (Relevance/Recency), `time_filter?` (Day/Week/Month), `cursor?`	获取社区推文
`CommunityAboutTimeline`	`community_id` , `cursor?`	获取社区媒体内容
`CommunityMembers`	`community_id`	获取社区成员
`CommunityModerators`	`community_id`	获取社区版主
`CommunityMemberSearch`	`community_id` , `q`	搜索社区成员

Trends

趋势

Endpoint	Params	Description
`Trends`	`woeid`	Get trending topics

Common WOEID: 1 (Worldwide), 23424977 (US), 23424975 (UK), 23424856 (Japan), 23424868 (South Korea), 23424781 (Germany), 23424819 (France), 23424748 (Australia), 23424829 (India), 23424900 (Mexico), 23424950 (Singapore), 23424948 (Saudi Arabia), 23424787 (Brazil).

端点	参数	描述
`Trends`	`woeid`	获取热门话题

常用WOEID：1（全球）, 23424977（美国）, 23424975（英国）, 23424856（日本）, 23424868（韩国）, 23424781（德国）, 23424819（法国）, 23424748（澳大利亚）, 23424829（印度）, 23424900（墨西哥）, 23424950（新加坡）, 23424948（沙特阿拉伯）, 23424787（巴西）。

Account

账户

Endpoint	Params	Description
`CreditBalance`	(none)	Get remaining API credits (free, costs 0 credits)

端点	参数	描述
`CreditBalance`	无	获取剩余API积分（免费，消耗0积分）

Response Parsing

响应解析

API responses use deeply nested Twitter JSON. Key extraction paths:

User profile —

data.user_results.result

rest_id, core.name, core.screen_name, core.created_at,
profile_bio.description, location.location, avatar.image_url,
relationship_counts.followers, relationship_counts.following,
tweet_counts.tweets, verification.is_blue_verified, website.url, privacy.protected

Tweet — For

TweetDetail

data.tweet_result

; For

TweetDetailv2

data.tweetResult

; For

TweetDetailv3

data.tweet_results

. Note: some tweets are wrapped in

TweetWithVisibilityResults

— access

.tweet

first.

.result.legacy → { full_text, favorite_count, retweet_count, reply_count, quote_count, bookmark_count, created_at }
.result.core.user_results.result → author info
.result.legacy.extended_entities.media → media attachments

Views (v2):

.result.views.count

| Views (v3):

.result.view_count_info.count

Timeline —

instructions[].entries[].content.itemContent.tweet_results

(individual tweets),

instructions[].entries[].content.items[].item.itemContent.tweet_results

(conversation modules). Pinned tweets:

__typename: "TimelinePinEntry"

Pagination —

instructions[].entries[].content

where

cursor_type = "Bottom"

→

.value

= next_cursor.

Trends —

metadata.woeid.name

(location),

modules[].trend

→

{ name, rank, target.query }

Credit balance —

{ credits: <number> }

API响应采用深度嵌套的Twitter JSON格式。关键信息提取路径：

用户资料 —

data.user_results.result

rest_id, core.name, core.screen_name, core.created_at,
profile_bio.description, location.location, avatar.image_url,
relationship_counts.followers, relationship_counts.following,
tweet_counts.tweets, verification.is_blue_verified, website.url, privacy.protected

推文 — 对于

TweetDetail

：

data.tweet_result

；对于

TweetDetailv2

：

data.tweetResult

；对于

TweetDetailv3

：

data.tweet_results

。注意：部分推文被包裹在

TweetWithVisibilityResults

中——需先访问

.tweet

。

.result.legacy → { full_text, favorite_count, retweet_count, reply_count, quote_count, bookmark_count, created_at }
.result.core.user_results.result → 作者信息
.result.legacy.extended_entities.media → 媒体附件

浏览量（v2）：

.result.views.count

| 浏览量（v3）：

.result.view_count_info.count

时间线 —

instructions[].entries[].content.itemContent.tweet_results

（单条推文）,

instructions[].entries[].content.items[].item.itemContent.tweet_results

（对话模块）。置顶推文：

__typename: "TimelinePinEntry"

。

分页 —

instructions[].entries[].content

中

cursor_type = "Bottom"

→

.value

= next_cursor。

趋势 —

metadata.woeid.name

（位置）,

modules[].trend

→

{ name, rank, target.query }

。

积分余额 —

{ credits: <number> }

。

Error Handling

错误处理

Error	Solution
`401`	Invalid API key — direct user to verify at https://readx.cc
`403`	Insufficient credits — check with `get_credit_balance` ; direct user to https://readx.cc
Connection refused	Switch to Direct API Mode; if persistent, readx.cc may be down

错误	解决方案
`401`	API密钥无效——引导用户前往https://readx.cc验证
`403`	积分不足——使用 `get_credit_balance` 查询；引导用户前往https://readx.cc
连接被拒绝	切换到直接API模式；如果问题持续，可能readx.cc已宕机

Data Limitations

数据限制

Limitation	Mitigation
Follower/following lists return ~20 by default	Use `count` param for larger samples
Tweet timelines return ~20 per page	Use `cursor` pagination; pass `next_cursor` as `cursor`
No historical follower count data	Infer from account age + current count
Search results are limited in quantity	Use multiple queries with different operators

限制	缓解方案
关注者/关注列表默认返回约20条	使用 `count` 参数获取更多样本
推文时间线每页返回约20条	使用 `cursor` 分页；将 `next_cursor` 作为 `cursor` 参数传递
无历史关注者数量数据	从账户时长+当前数量推断
搜索结果数量有限	使用不同运算符进行多次查询