History API
通过 History API 回放已存内容、资料、关注和关联账号事件,或查询单条帖子或单个账号。
请求历史记录
使用 GET /api/history 在重连后回放已存事件,或检查指定时间窗口。
检查权限
Pro、Scale 和 Ultra Speed 可以请求所有 History 事件类型。标准密钥查询基础套餐的监控账号;Ultra 密钥查询指定的 Ultra 账号。支持的类型为 TWEET、PROFILE、FOLLOW 和 AFFILIATE。delete、pin 和 unpin 仍只在实时流中发送。
设置筛选条件
不提供账号筛选时,History 会查询该密钥当前监控的所有有效账号。筛选条件只能包含该密钥当前监控的账号。
| 参数 | 必填 | 说明 |
|---|---|---|
handle, handles, handle[], handles[] | 否 | 单个账号、重复参数或逗号分隔的多个账号 |
startDate | 否 | ISO datetime 下限 |
endDate | 否 | ISO datetime 上限 |
limit | 否 | 默认 100,最大 1000 |
type | 否 | TWEET、PROFILE、FOLLOW 或 AFFILIATE,不区分大小写,默认为 TWEET |
cursor | 否 | 上一页返回的不透明 nextCursor;其他筛选条件必须保持不变 |
History 请求
typescriptconst apiKey = process.env.TWEETSTREAM_API_KEY;
if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY");
const response = await fetch(
"https://api.tweetstream.io/api/history?limit=25&type=TWEET",
{
headers: {
Authorization: `Bearer ${apiKey}`,
},
},
);
if (!response.ok) {
const detail = await response.text();
throw new Error(`History failed (${response.status}): ${detail}`);
}
const page = await response.json();
console.log(page.data);在有界时间范围内翻页
History 每次请求最多返回 1000 行,并按稳定的新到旧顺序排列。
固定起止时间
记录一个 endDate,选择 startDate,并在此次回放的每一页中保持两者不变。
使用 nextCursor 继续
将返回的每个 nextCursor 与相同的 type、账号和日期范围一起发送。cursor 为 null 时,此时间范围已结束。以幂等方式处理每行,并在恢复期间继续处理实时生命周期事件,因为 History 会分别回放已存事件类别,不会回放仅实时发送的状态变更。
读取响应
先读取数据行和请求元数据,再推进回放窗口。
读取数据行和元数据
结果按稳定的新到旧顺序遍历。metadata.count 是本页行数,metadata.nextCursor 用于继续相同的筛选查询,cursor 为 null 时结果集结束。较早保存的 FOLLOW 行可能带有空 target;这表示目标身份不可用,仍应继续处理该事件。
History 响应类型
显示完整定义(243 行)
type VerifiedType = 'blue' | 'business' | 'government' | 'verified' | 'none';
type TweetVerifiedLabel = {
badge: string | null;
description: string;
url: string | null;
};
type TweetAuthor = {
banner?: string;
bio?: string;
followersCount?: number;
followingCount?: number;
id?: string;
joinedAt?: number;
location?: string;
metrics?: {
likes?: number;
tweets?: number;
};
// Includes a leading @ when present, for example "@elonmusk".
handle?: string;
name?: string;
// History stores X and Truth Social posts; Binance Square content is live-only.
platform?: 'twitter' | 'truth_social';
profileImage?: string;
// The account's own website, when it has one.
url?: string;
verifiedLabel?: TweetVerifiedLabel;
verifiedType?: VerifiedType;
};
type AccountEventActor = TweetAuthor & {
websiteUrl?: string;
};
type ProfileUpdateEvent = {
kind: 'PROFILE';
eventId: string;
observedAt: number;
receivedAt?: number;
actor: AccountEventActor;
changes: {
avatar?: string;
banner?: string;
bio?: string;
handle?: string;
location?: string;
name?: string;
verifiedLabel?: TweetVerifiedLabel | null;
websiteUrl?: string | null;
};
previous?: {
avatar?: string;
banner?: string;
bio?: string;
handle?: string;
location?: string;
name?: string;
verifiedLabel?: TweetVerifiedLabel | null;
websiteUrl?: string | null;
};
};
type FollowEvent = {
kind: 'FOLLOW';
eventId: string;
observedAt: number;
receivedAt?: number;
actor: AccountEventActor;
target: AccountEventActor;
};
type UnfollowEvent = {
kind: 'UNFOLLOW';
eventId: string;
observedAt: number;
receivedAt?: number;
actor: AccountEventActor;
target: AccountEventActor;
};
type AffiliateAccountIdentity = AccountEventActor & {
id: string;
};
type AffiliateUpdateEvent = {
action: 'added' | 'removed';
eventId: string;
observedAt: number;
receivedAt?: number;
organization: AffiliateAccountIdentity;
member: AffiliateAccountIdentity;
};
type TweetMeta = {
tweetId: string;
// Pair with tweetId when merging enrichment. When omitted, use twitter.
platform?: 'twitter' | 'truth_social';
ocr?: {
text: string;
};
detected?: {
tokens?: Array<{
symbol?: string;
name?: string;
contract?: string;
chain?: string;
networkId?: number;
priceUsd?: number;
sources: Array<'text' | 'ocr'>;
}>;
cex?: Array<{
exchange: 'bybit' | 'binance' | 'hyperliquid';
symbol?: string;
priceUsd?: number;
url?: string;
baseAsset?: string;
quoteAsset?: string;
sources: Array<'text' | 'ocr'>;
}>;
prediction?: Array<{
exchange: 'polymarket' | 'kalshi';
marketId?: string;
title?: string;
priceUsd?: number;
url?: string;
sources: Array<'text' | 'ocr'>;
}>;
};
};
type HistoryMedia = {
url: string;
type?: 'image' | 'video' | 'gif';
thumbnail?: string;
};
type TweetUrl = {
url: string;
name?: string;
tco?: string;
};
type TweetMention = {
handle?: string;
id?: string;
name?: string;
};
type HistoryTweetArticle = {
description?: string;
id?: string;
publishedAt?: number;
text?: string;
thumbnail?: string;
title?: string;
updatedAt?: number;
url?: string;
};
type HistoryTweetPollChoice = {
id?: string;
image?: string;
label?: string;
votes?: number;
};
type HistoryTweetPoll = {
choices: HistoryTweetPollChoice[];
endsAt?: number;
totalVotes?: number;
updatedAt?: number;
};
type TweetContentKind = 'post' | 'reply' | 'quote' | 'retweet';
type HistoryTweetReference = {
article?: HistoryTweetArticle;
type: 'reply' | 'quote' | 'retweet';
tweetId?: string;
text?: string;
translatedText?: string;
author?: TweetAuthor;
media?: HistoryMedia[];
poll?: HistoryTweetPoll;
quoted?: HistoryTweetReference;
subtweet?: HistoryTweetReference;
};
type TweetContent = {
tweetId: string;
kind: TweetContentKind;
// Original tweet text when the stored content includes both original and
// translated text.
text: string;
translatedText?: string;
createdAt: number;
author: TweetAuthor;
article?: HistoryTweetArticle;
link?: string;
media?: HistoryMedia[];
mentions?: TweetMention[];
poll?: HistoryTweetPoll;
// Epoch ms from the realtime payload when the stored content includes it.
receivedAt?: number;
urls?: TweetUrl[];
ref?: HistoryTweetReference;
quoted?: HistoryTweetReference;
};
type HistoricalContent =
| TweetContent
| ProfileUpdateEvent
| FollowEvent
| UnfollowEvent
| AffiliateUpdateEvent;
type HistoricalTweetResponse = {
tweetId: string;
twitterId: string;
twitterHandle: string | null;
body: string;
time: string;
// ISO TweetStream receipt time for the historical event.
receivedTime: string;
link: string;
messageType: 'TWEET' | 'PROFILE' | 'FOLLOW' | 'AFFILIATE';
content: HistoricalContent;
meta?: TweetMeta;
};
type HistoryResult = {
data: HistoricalTweetResponse[];
metadata: {
count: number;
nextCursor: string | null;
handle?: string;
handles?: string[];
startDate?: string;
endDate?: string;
type?: 'TWEET' | 'PROFILE' | 'FOLLOW' | 'AFFILIATE';
};
};History 响应
json{
"data": [
{
"tweetId": "account:affiliate:aff_01JQ8YQ5K8B8QKH6M0P8A1V2WX",
"twitterId": "123",
"twitterHandle": "organization",
"body": "Added New Member (@newmember) to affiliate list",
"time": "2025-04-09T00:00:00.123Z",
"receivedTime": "2025-04-09T00:00:00.123Z",
"link": "https://x.com/newmember",
"messageType": "AFFILIATE",
"content": {
"action": "added",
"eventId": "aff_01JQ8YQ5K8B8QKH6M0P8A1V2WX",
"observedAt": 1744156800123,
"receivedAt": 1744156800123,
"organization": {
"id": "123",
"handle": "@organization",
"name": "Organization",
"verifiedType": "business"
},
"member": {
"id": "456",
"handle": "@newmember",
"name": "New Member",
"profileImage": "https://pbs.twimg.com/profile_images/newmember_normal.jpg"
}
}
}
],
"metadata": {
"count": 1,
"nextCursor": null,
"type": "AFFILIATE"
}
}映射关联账号数据行
对于 AFFILIATE,顶层账号是 organization,content 与实时 affiliate_update 载荷一致。
处理错误
| 状态 | 响应 body | 含义 |
|---|---|---|
400 | { "error": "Invalid query parameters" } | 日期、limit、type 或账号格式错误 |
400 | { "error": "Invalid handle provided", "handle": "..." } | 账号校验失败 |
400 | { "error": "startDate must be before endDate" } | 日期范围顺序错误 |
400 | { "error": "Invalid cursor" } | cursor 格式错误或与其他筛选条件不匹配 |
401 | { "error": "Missing or invalid API key" } | Bearer token 缺失或格式错误 |
401 | { "error": "Invalid API key" } | Bearer token 格式正确,但不是有效 API 密钥 |
403 | { "error": "History is available on Pro, Scale, and Ultra Speed" } | 套餐不包含请求的 History 类型 |
403 | { "error": "Your subscription is not active", "message": "Please ensure your subscription is active", "status": "PAST_DUE" } | 订阅状态不允许使用 History |
403 | { "error": "Handle ... is not among your tracked accounts" } | 请求回放的账号不在监控列表中 |
429 | { "error": "Too many history requests", "retryAfterSeconds": 60 } | 超过请求频率限制 |
查询帖子
GET /api/tweet/{id} 返回一条帖子及其互动数据。{id} 是帖子 ID,为 1 到 20 位数字。
tweet的字段与TWEETHistory 行中的content相同。- 同时引用了某条帖子的回复,
kind为reply,父帖子在ref中,被引用的帖子在quoted中。 metrics包含likes、replies、reposts、quotes、bookmarks和views。views可能为 null。
帖子查询请求
typescriptconst apiKey = process.env.TWEETSTREAM_API_KEY;
if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY");
const response = await fetch(
"https://api.tweetstream.io/api/tweet/1234567890",
{
headers: {
Authorization: `Bearer ${apiKey}`,
},
},
);
if (!response.ok) {
const detail = await response.text();
throw new Error(`Lookup failed (${response.status}): ${detail}`);
}
const { tweet, metrics } = await response.json();
console.log(tweet.text, metrics.likes);帖子查询响应
json{
"tweet": {
"tweetId": "1234567890",
"text": "Rate decision at 2pm ET.",
"createdAt": 1744156800000,
"kind": "post",
"link": "https://x.com/marketdesk/status/1234567890",
"author": {
"id": "1189745302",
"handle": "@marketdesk",
"name": "Market Desk",
"platform": "twitter",
"verifiedType": "blue",
"followersCount": 48210,
"followingCount": 312,
"joinedAt": 1358208000000,
"profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg"
}
},
"metrics": {
"likes": 1204,
"replies": 87,
"reposts": 230,
"quotes": 19,
"bookmarks": 41,
"views": 98213
}
}查询账号
GET /api/user/{id} 返回一个账号的资料。{id} 可以是数字账号 ID,也可以是 handle,带不带 @ 均可。纯数字会被当作账号 ID,所以纯数字的 handle 需要加 @。
user的字段与 WebSocket 帖子事件中的author相同。pinnedTweet是该账号的置顶帖子,字段与帖子查询中的tweet相同。只有 TweetStream 看到过该账号置顶帖子时才有值。其他账号、账号取消置顶后,或帖子暂时无法显示时,该字段为 null。
账号查询响应
json{
"user": {
"id": "1189745302",
"handle": "@marketdesk",
"name": "Market Desk",
"platform": "twitter",
"verifiedType": "blue",
"followersCount": 48210,
"followingCount": 312,
"joinedAt": 1358208000000,
"profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg"
},
"pinnedTweet": {
"tweetId": "1234567890",
"text": "Rate decision at 2pm ET.",
"createdAt": 1744156800000,
"kind": "post",
"link": "https://x.com/marketdesk/status/1234567890",
"author": {
"id": "1189745302",
"handle": "@marketdesk",
"name": "Market Desk",
"platform": "twitter",
"verifiedType": "blue",
"followersCount": 48210,
"followingCount": 312,
"joinedAt": 1358208000000,
"profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg"
}
}
}查询权限与错误
所有付费或试用中的套餐都可以使用查询。每个账号每分钟最多可查询 60 次(两个端点合计),突发上限为 10 次。同时最多可有 4 个查询在进行中。收到 429 时,等待 retryAfterSeconds 指定的秒数(Retry-After 中也会给出)后再重试。
| 状态 | 响应 body | 含义 |
|---|---|---|
400 | { "error": "Invalid post ID" } | 帖子 ID 不是 1 到 20 位数字 |
400 | { "error": "Invalid account ID or handle" } | 账号 ID 或 handle 格式错误 |
401 | { "error": "Missing or invalid Authorization header" } | 未发送 Bearer token |
401 | { "error": "Invalid API key" } | token 不是有效 API 密钥 |
403 | { "error": "An active subscription is required" } | 账号没有付费或试用中的订阅 |
404 | { "error": "Post not found" } | 帖子不存在或未公开 |
404 | { "error": "Account not found" } | 没有使用该 ID 或 handle 的账号 |
429 | { "error": "Rate limit exceeded", "retryAfterSeconds": 1 } | 账号已达到查询频率上限 |
429 | { "error": "Too many lookups in progress", "retryAfterSeconds": 1 } | 账号已有 4 个查询在进行中 |
503 | { "error": "Lookup is temporarily unavailable" } | 稍后重试;如有 Retry-After,在其后重试 |
503 | { "error": "Authentication service unavailable" } | 暂时无法验证 API 密钥,请稍后重试 |
搜索帖子
GET /api/search/posts 返回与 X 搜索查询匹配的近期 X 帖子,按 X 的“最新”顺序排列(并非严格按 ID 排序)。
query必填:X 搜索查询,可使用运算符,最多 512 个字符。limit可选:1 到 40 条帖子,默认 20 条。posts中的每一项都是帖子查询返回的tweet对象,metrics位于其中。搜索结果中的views为 null。- 结果最多可能是 30 秒前的数据。
- 没有匹配时返回
200,内容为"posts": []和"next": null。
帖子搜索请求
typescriptconst apiKey = process.env.TWEETSTREAM_API_KEY;
if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY");
const url = new URL("https://api.tweetstream.io/api/search/posts");
url.searchParams.set("query", "solana lang:en -is:retweet");
url.searchParams.set("limit", "20");
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${apiKey}`,
},
});
if (!response.ok) {
const detail = await response.text();
throw new Error(`Search failed (${response.status}): ${detail}`);
}
const { posts, next } = await response.json();
console.log(posts.length, next);帖子搜索响应
json{
"posts": [
{
"tweetId": "2118183412095201280",
"text": "Solana validators shipped the new client today.",
"createdAt": 1793849254045,
"kind": "post",
"link": "https://x.com/marketdesk/status/2118183412095201280",
"author": {
"id": "1189745302",
"handle": "@marketdesk",
"name": "Market Desk",
"platform": "twitter",
"verifiedType": "blue",
"followersCount": 48210,
"followingCount": 312,
"profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg"
},
"metrics": {
"likes": 1204,
"replies": 87,
"reposts": 230,
"quotes": 19,
"bookmarks": 41,
"views": null
}
}
],
"next": "https://api.tweetstream.io/api/search/posts?limit=1&page=AZx3q0Vh1mR2k9Q&query=solana+lang%3Aen+-is%3Aretweet"
}下一页
next 是下一页的 URL。使用同一个 API 密钥原样请求它,直到它为 null。
next链接 30 分钟内有效。- 到达末尾之前,一页中的帖子也可能少于
limit。请继续请求next。 - 一次搜索最多返回 100 条帖子,之后
next为null。不同页面可能包含同一条帖子,请按tweetId去重。
读取所有页面
typescriptconst apiKey = process.env.TWEETSTREAM_API_KEY;
if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY");
const query = "solana lang:en -is:retweet";
let url: string | null =
`https://api.tweetstream.io/api/search/posts?query=${encodeURIComponent(query)}&limit=40`;
while (url) {
const response = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!response.ok) {
throw new Error(`Search failed (${response.status}): ${await response.text()}`);
}
const { posts, next } = await response.json();
for (const post of posts) console.log(post.tweetId, post.text);
url = next;
}搜索权限与错误
Pro、Scale 和 Ultra Speed 包含帖子搜索,账号的两个 API 密钥均可使用。每次请求(包括 next 链接)消耗账号搜索额度中的一次。该额度与查询额度相互独立。收到 429 时,等待 retryAfterSeconds 指定的秒数(Retry-After 中也会给出)后再重试。
| 状态 | 响应 body | 含义 |
|---|---|---|
400 | { "error": "Search query is required" } | 缺少 query 或其为空 |
400 | { "error": "Search query is too long" } | query 超过 512 个字符 |
400 | { "error": "Invalid search query" } | query 含有控制字符,或被重复发送 |
400 | { "error": "Invalid limit" } | limit 不是 1 到 40 之间的整数,或被重复发送 |
400 | { "error": "This page link is invalid or has expired; start the search again" } | next 链接被修改或已过期。请不带 page 重新搜索 |
401 | { "error": "Missing or invalid Authorization header" } | 未发送 Bearer token |
401 | { "error": "Invalid API key" } | token 不是有效 API 密钥 |
403 | { "error": "Post search requires Pro, Scale, or Ultra Speed" } | 账号的套餐不包含帖子搜索 |
405 | 无 | 只支持 GET |
429 | { "error": "Rate limit exceeded", "retryAfterSeconds": 1 } | 超过套餐每分钟的搜索次数 |
429 | { "error": "Too many searches in progress", "retryAfterSeconds": 1 } | 同时进行的搜索过多 |
503 | { "error": "Post search is temporarily unavailable" } | 请稍后重试(如有 Retry-After,在其后重试) |
503 | { "error": "Authentication service unavailable" } | 暂时无法验证 API 密钥,请稍后重试 |
各套餐的搜索额度
账号同时拥有其中多个套餐时,按额度最大的套餐计算。REST 和 MCP 共用该额度。
| 套餐 | 每分钟请求数 | 同时进行中 |
|---|---|---|
| Pro | 60 次,突发上限 10 次 | 4 |
| Ultra Speed | 120 次,突发上限 10 次 | 6 |
| Scale | 300 次,突发上限 10 次 | 10 |