Twitter Search API

Twitter Search

主要特性

• 从一个表达式发现帖子提交一个非空关键词或搜索表达式，把匹配的 X 公开帖子整理为结构化记录。
• 适配两种研究目的的排序latest 用于查看近期匹配，top 用于查看较突出匹配；默认采用 latest。
• 明确搜索采集深度以 20 为步长请求 20 至 2,000 条结果，为本次搜索设置最大采集数量。
• 让匹配结果保留原始查询正文、作者、互动、媒体、实体、时间和关系字段可与 extra.search_query、collected_at 一起使用。

参数

如何使用

把明确的研究问题写成搜索表达式，选择合适的排序方式，并让查询条件跟随匹配帖子一起进入数据集。

1. 为希望发现的 X 帖子编写一个聚焦且非空的表达式。
2. 选择 latest 或 top，并设置 20 至 2,000 之间且为 20 倍数的 results_limit。
3. 向 /v1/x/search POST 请求，再轮询 /v1/tasks/{task_id} 直到任务完成。
4. 保存 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