> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 历史数据

Sorsa API 可访问最早追溯至 2006 年 3 月的 X（原 Twitter）公开数据完整档案。历史数据与近期数据使用相同的端点、身份验证和分页方式。无需单独的“完整档案”套餐、企业合同，搜索也没有时间窗口限制。档案查询与其他调用共用请求配额，因此新账号赠送的 100 次免费请求也可用于测试，无需信用卡。

本页介绍历史数据所用的两个端点、平台可以与无法提供的信息，以及适合大规模处理的方式。

> **注意：** 包含方法对比表、CSV 导出管道和更多代码示例的完整教程，请参阅博客上的[历史 Twitter 数据：如何通过 API 搜索旧推文](https://api.sorsa.io/blog/historical-twitter-data)。

***

## 端点

| 端点                       | 使用场景               | 分页            | 每页数量     |
| :----------------------- | :----------------- | :------------ | :------- |
| `POST /v3/search-tweets` | 按关键词搜索档案，支持日期与互动筛选 | `next_cursor` | 约 20 条推文 |
| `POST /v3/user-tweets`   | 特定账号的完整发帖历史        | `next_cursor` | 约 20 条推文 |

`/search-tweets` 支持完整的 [X 搜索运算符](https://docs.sorsa.io/zh-Hans/search-operators)，包括 `since:`、`until:`、`from:`、`to:`、`min_faves:`、`min_retweets:`、`lang:` 和 `filter:`，直接写入 `query` 字段。`/user-tweets` 只接收账号标识符（`user_link`、`username` 或 `user_id`），返回该账号的完整时间线，不支持查询筛选。

***

## 按关键词搜索档案

需要跨用户获取某日期窗口内所有匹配查询的推文时，使用 `/search-tweets`。将带日期范围的查询放入 JSON 请求体：

```python theme={null}
import requests, time

API_KEY = "YOUR_API_KEY"
URL = "https://api.sorsa.io/v3/search-tweets"

def search_archive(query, max_pages=50):
    all_tweets, next_cursor = [], None
    for _ in range(max_pages):
        body = {"query": query, "order": "latest"}
        if next_cursor:
            body["next_cursor"] = next_cursor

        resp = requests.post(
            URL,
            headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
            json=body,
        )
        resp.raise_for_status()
        data = resp.json()

        all_tweets.extend(data.get("tweets", []))
        next_cursor = data.get("next_cursor")
        if not next_cursor:
            break
        time.sleep(0.1)
    return all_tweets


tweets = search_archive('"climate change" since:2015-06-01 until:2015-12-31 lang:en min_faves:10')
```

`order` 支持 `"latest"`（按时间）和 `"popular"`（按互动排名）。按日期范围收集档案时使用 `"latest"`；研究内容时，`"popular"` 可优先返回互动最高的帖子。

***

## 完整账号时间线

需要从新到旧获取某账号的完整发帖历史时，使用 `/user-tweets`，不受 3,200 条推文上限限制。

```python theme={null}
resp = requests.post(
    "https://api.sorsa.io/v3/user-tweets",
    headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
    json={"user_link": "https://x.com/naval"},
)
```

每次只提供 `user_link`、`username` 或 `user_id` 中的一种。使用 `next_cursor` 分页，直到它返回 null。端点按时间倒序遍历时间线。

如果只需要某账号在特定日期范围内的推文，应改用 `/search-tweets` 和 `from:` 运算符，例如 `from:naval since:2020-01-01 until:2021-01-01`。`/user-tweets` 不接受日期筛选。

***

## 可以获取哪些数据？

历史推文与近期推文返回相同字段：

* 完整正文，不截断、不替换 URL
* 六项互动指标：`likes_count`、`retweet_count`、`reply_count`、`quote_count`、`view_count`、`bookmark_count`
* 包含完整作者资料的嵌入式 `user` 对象
* 包含媒体 URL（图片、视频、GIF）和链接预览的 `entities` 数组
* 对话元数据：`conversation_id_str`、`in_reply_to_tweet_id`、`is_reply`、`is_quote_status`
* 语言标记（`lang`）

完整字段参考请参阅[响应格式](https://docs.sorsa.io/zh-Hans/response-format)。

***

## 平台层面的限制

以下限制来自 X，而非 Sorsa。任何公开 API 都无法绕过：

* **已删除推文**会从 X 搜索索引移除，无法获取。
* **受保护账号**不包含在任何公开搜索和时间线结果中。
* **用户资料不是历史快照。** 2014 年的推文返回的是作者当前简介、用户名和粉丝数，而非 2014 年的值。
* **互动指标不是历史快照。** 点赞、转推和浏览数反映当前累计值，而非过去某个日期的数值。如果需要特定时间点的互动数据，请通过[实时监测](https://docs.sorsa.io/zh-Hans/real-time-monitoring)持续采集，并自行保存指标。

***

## 最佳实践

### 拆分较大的日期范围

单次跨多年的查询不便于重试，也无法按时间段审计。跨年度收集可按月拆分，变化剧烈的事件窗口可按周拆分。

```python theme={null}
def monthly_chunks(year):
    out = []
    for month in range(1, 13):
        since = f"{year}-{month:02d}-01"
        nm = month + 1 if month < 12 else 1
        ny = year if month < 12 else year + 1
        until = f"{ny}-{nm:02d}-01"
        out.append((since, until))
    return out

for since, until in monthly_chunks(2020):
    tweets = search_archive(f'bitcoin since:{since} until:{until} lang:en min_faves:50')
```

### 过滤转推噪声

历史热门搜索可能返回大量原生转推，淹没原创内容。进行情感、观点或内容模式研究时，加入 `-filter:nativeretweets`。若还要排除旧式 `RT @user:` 转推，使用 `-filter:retweets`。

### 结合互动与日期筛选

将 `since:`/`until:` 与 `min_faves:` 或 `min_retweets:` 结合，可显著减少噪声和请求量。例如：

```text theme={null}
"product launch" since:2022-03-01 until:2022-03-31 min_faves:100 -filter:retweets lang:en
```

### 全球话题按语言拆分

针对全球事件，按 `lang:` 分别查询，比混合多种语言更容易得到整洁的各语言数据集。

### 分页直到游标为空

只在 `next_cursor` 为 null、空或缺失时结束。不要因为某页数量较少就提前停止。完整方式见[分页](https://docs.sorsa.io/zh-Hans/pagination)。

***

## 相关内容

* [搜索推文](https://docs.sorsa.io/zh-Hans/search-tweets)：`/search-tweets` 端点参考
* [搜索运算符](https://docs.sorsa.io/zh-Hans/search-operators)：完整运算符词典
* [分页](https://docs.sorsa.io/zh-Hans/pagination)：游标分页详情
* [实时监测](https://docs.sorsa.io/zh-Hans/real-time-monitoring)：结合历史回填与后续持续采集
* [追踪提及](https://docs.sorsa.io/zh-Hans/search-mentions)：追踪任意用户名的历史提及
* [优化 API 使用](https://docs.sorsa.io/zh-Hans/optimizing-api-usage)：减少大型数据收集任务的请求数