Twitter User Search
在 X 上发现匹配特定主题的创作者、企业或专家档案，需要对账号名称和简介进行关键词匹配检索。标准化用户搜索结果输出用户名、昵称、个人简介、地理位置、粉丝体量以及蓝标认证信息。
主要特性
- 关键词账号模糊匹配提交任意查询词，全面匹配用户 handle、显示昵称与个人简介文本中的关键词。
- 标准化档案信息输出结构统一的账号对象，包含用户 ID、用户名、昵称、头像图、横幅图以及简介文本。
- 受众体量指标采集当前时刻的粉丝数、关注数、已发推文数、媒体数和点赞收藏计数。
- 认证与账号标记识别蓝标认证状态、官方企业认证类型、机器人自动化标识及账号所在地理位置。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 用于匹配公开 X 用户主页及简介的搜索关键词。 |
results_limit | 可选 | 返回的用户主页数量上限；必须为 20 到 2,000 之间 20 的倍数，默认 20。 |
如何使用
提交搜索词作为异步任务，并轮询拉取标准化用户账号对象。
- 在 query 中填写关键词，并设置 20 的倍数的 results_limit（最高 2,000，默认 20）。
- 向 /v1/x/search-users 发送 POST 请求。
- 轮询 /v1/tasks/{task_id} 直至状态变为 succeeded。
- 在 data.results.items 中读取返回的用户主页对象。
curl -X POST "https://api.socq.ai/v1/x/search-users" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"OpenAI","results_limit":20}'
# 轮询 GET /v1/tasks/{task_id}，解析 data.results.items 中的账号列表。最佳使用场景
- 行业 KOL 与领域专家挖掘： 按技术名词、行业赛道或研究方向搜索，批量发现该领域具有影响力的推特博主与意见领袖。
- 品牌与竞品账号矩阵梳理： 搜索品牌全称或简称，排查其在全球各地区的区域分支账号或非官方粉丝主页。
- 潜在客户与商机线索建立： 结合个人简介中的职位 title 或所属公司关键词，筛选目标客户群体并建立触达线索库。
使用建议
- 该接口专用于发现账号；若想检索单条具体的推文或帖子，请使用 X Search 接口。
- results_limit 必须为 20 的整倍数（例如 20、40、100），以满足底层数据接口分页要求。
- 可借助 is_verified 和 verified_type 字段快速判定该账号是否经过官方机构或蓝标认证。
- 将搜出来的目标 usernames 传入 X User Posts 或 X Following List，可进一步展开其内容与关系图谱。
相关 API
需要其他类型的 X 公开数据时，可以使用以下 API。
- Twitter Tweet Scraper API — 从 x.com 或 twitter.com status URL 获取公开帖子正文、作者、互动、媒体、标签、提及和会话关系。
- Twitter Profile Scraper API — 按 username 获取公开账号身份、简介、头像、封面、账号状态和可见受众统计。
- Twitter User Tweets Scraper API — 按 username 采集近期公开帖子、作者、媒体、标签、提及和互动指标，并排除回复。
- Twitter Search API — 按搜索表达式查找公开帖子，并支持 latest 或 top 排序和结果数量上限。
- X Followers List API — 按一个或多个 X 用户名采集公开关注者账号身份与可见资料指标。
- X Following List API — 采集 X 公开账号关注的个人资料，包括身份、简介、账号状态、可见计数和来源 username。
- X Post Quotes API — 按已知 status URL 采集公开引用帖，返回评论正文、作者、互动、媒体、时间和来源帖子上下文。
- X Post Replies API — 从 X 帖子 URL 采集公开回复，支持选择排序，并返回回复正文、作者、可见互动、媒体和父帖信息。
- X Post Retweeters API — 采集转发已知 X 或 Twitter status URL 的公开账号，并在整个任务中按账号去重后返回标准化主页记录。
- X Trends API — 按已知数字 WOEID 采集当前 X 公开趋势快照，保留来源排名、查询、描述和位置背景。
- Twitter Mentions API