Twitter Search
X 搜索结果是根据查询筛选出的公开帖子，每条匹配都带有语言、作者、媒体、实体、会话背景和可见互动。将原始查询与结果一同保留，更容易复核周期性话题扫描、发布监听和不同批次的结果变化。
主要特性
- 从一个表达式发现帖子提交一个非空关键词或搜索表达式，把匹配的 X 公开帖子整理为结构化记录。
- 适配两种研究目的的排序latest 用于查看近期匹配，top 用于查看较突出匹配；默认采用 latest。
- 明确搜索采集深度以 20 为步长请求 20 至 2,000 条结果，为本次搜索设置最大采集数量。
- 让匹配结果保留原始查询正文、作者、互动、媒体、实体、时间和关系字段可与 extra.search_query、collected_at 一起使用。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填的非空关键词或 X 帖子搜索表达式，用于发现匹配的公开帖子。 |
results_limit | 可选 | 可选的请求结果上限。默认 20，可填写 20 至 2,000 之间且为 20 倍数的值。 |
sort_by | 可选 | 可选排序方式：latest 查看近期匹配，top 查看较突出匹配；默认 latest。 |
如何使用
把明确的研究问题写成搜索表达式，选择合适的排序方式，并让查询条件跟随匹配帖子一起进入数据集。
- 为希望发现的 X 帖子编写一个聚焦且非空的表达式。
- 选择 latest 或 top，并设置 20 至 2,000 之间且为 20 倍数的 results_limit。
- 向 /v1/x/search POST 请求，再轮询 /v1/tasks/{task_id} 直到任务完成。
- 保存 data.results.items，再沿 next_cursor 读取到 has_more 变为 false。
curl -X POST "https://api.socq.ai/v1/x/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"artificial intelligence","results_limit":40,"sort_by":"latest"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 监听特定产品发布： 搜索产品、版本、会议或活动短语，再按发布时间和采集时间整理相关帖子。
- 追踪品牌与产品提及： 围绕指定名称或短语汇总作者、正文、可见互动、话题标签、提及和媒体。
- 梳理正在发展的主题： 用 latest 跟进新帖子，用 top 查看同一研究表达式下较突出的内容。
- 维护周期性查询数据集： 为每条结果保留 extra.search_query，定期运行已版本化的表达式，并只追加未出现过的帖子 ID。
使用建议
- 先使用聚焦表达式检查匹配质量，仅在覆盖范围过窄时逐步放宽措辞。
- 时效性监听选择 latest，更看重突出匹配而非时间顺序时选择 top。
- results_limit 应为 20 的倍数，并应理解为上限，而不是保证返回的数量。
- 查询词发生变化时保存表达式版本，便于比较不同周期的结果集。
- 按帖子 id 去重，同时保留 extra.search_query 和 collected_at 作为发现背景。
相关 API
需要其他类型的 X 公开数据时，可以使用以下 API。
- Twitter Tweet Scraper API — 从 x.com 或 twitter.com status URL 获取公开帖子正文、作者、互动、媒体、标签、提及和会话关系。
- Twitter Profile Scraper API — 按 username 获取公开账号身份、简介、头像、封面、账号状态和可见受众统计。
- Twitter User Tweets Scraper API — 按 username 采集近期公开帖子、作者、媒体、标签、提及和互动指标，并排除回复。
- 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 公开趋势快照，保留来源排名、查询、描述和位置背景。