跳到文档正文
浏览和搜索
本页内容

History API

通过 History API 回放已存内容、资料、关注和关联账号事件,或查询单条帖子或单个账号。

打开 OpenAPI 规范
在聊天中打开
按产品代码校对:2026年9月24日

请求历史记录

使用 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 请求

typescript
const 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 行)
History 响应类型typescript
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 的字段与 TWEET History 行中的 content 相同。
  • 同时引用了某条帖子的回复,kind 为 reply,父帖子在 ref 中,被引用的帖子在 quoted 中。
  • metrics 包含 likes、replies、reposts、quotes、bookmarks 和 views。views 可能为 null。

帖子查询请求

typescript
const 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);
{
  "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。
{
  "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。

帖子搜索请求

typescript
const 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);
{
  "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 去重。

读取所有页面

typescript
const 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 共用该额度。

套餐每分钟请求数同时进行中
Pro60 次,突发上限 10 次4
Ultra Speed120 次,突发上限 10 次6
Scale300 次,突发上限 10 次10