History API
Replay stored content, profile, follow, and affiliate events through the History API, or look up one post or account.
Request history
Use GET /api/history to replay stored events after reconnecting or inspect a specific time window.
Check access
Pro, Scale, and Ultra Speed can request every History event type. Standard keys query base-plan tracked accounts; Ultra keys query selected Ultra accounts. Supported types are TWEET, PROFILE, FOLLOW, and AFFILIATE. Delete, pin, and unpin remain live-only events.
Set filters
Without a handle filter, History searches all active accounts tracked by the key. A filter can include only handles that key currently tracks.
| Parameter | Required | Notes |
|---|---|---|
handle, handles, handle[], handles[] | No | One handle, repeated handles, or comma-separated handles |
startDate | No | ISO datetime lower bound |
endDate | No | ISO datetime upper bound |
limit | No | Defaults to 100; maximum 1000 |
type | No | TWEET, PROFILE, FOLLOW, or AFFILIATE; case-insensitive. Defaults to TWEET |
cursor | No | Opaque nextCursor from the previous page; keep every other filter unchanged |
History request
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);Page through a bounded window
History returns up to 1000 rows per request in stable newest-first order.
Set both bounds
Capture one endDate, choose a startDate, and keep both values unchanged for every page in the replay.
Continue with nextCursor
Send each returned nextCursor with the same type, handles, and date bounds. A null cursor ends the window. Process rows idempotently and keep live lifecycle handlers active because History replays stored event families separately from live-only state changes.
Read the response
Read the rows and request metadata before advancing the replay window.
Read rows and metadata
Results use stable newest-first traversal. metadata.count reports the returned rows, metadata.nextCursor continues the same filtered query, and a null cursor ends the result set. Older stored FOLLOW rows can have an empty target; treat the target identity as unavailable and continue processing the event.
History response types
Show full definitions (243 lines)
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 response
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"
}
}Map affiliate rows
For AFFILIATE, the top-level account is the organization and content matches the live affiliate_update payload.
Handle errors
| Status | Body | Meaning |
|---|---|---|
400 | { "error": "Invalid query parameters" } | Malformed dates, limit, type, or handle |
400 | { "error": "Invalid handle provided", "handle": "..." } | Handle validation failed |
400 | { "error": "startDate must be before endDate" } | Date range is reversed |
400 | { "error": "Invalid cursor" } | Cursor is malformed or does not match the other filters |
401 | { "error": "Missing or invalid API key" } | Missing or malformed bearer token |
401 | { "error": "Invalid API key" } | Bearer token was well-formed but does not match an active API key |
403 | { "error": "History is available on Pro, Scale, and Ultra Speed" } | Plan does not include the requested History type |
403 | { "error": "Your subscription is not active", "message": "Please ensure your subscription is active", "status": "PAST_DUE" } | Subscription state does not allow history |
403 | { "error": "Handle ... is not among your tracked accounts" } | Requested replay handle is outside your watchlist |
429 | { "error": "Too many history requests", "retryAfterSeconds": 60 } | Rate limit exceeded |
Look up a post
GET /api/tweet/{id} returns one post and its engagement counts. {id} is the post ID, 1 to 20 digits.
tweethas the same fields ascontentin aTWEETHistory row.- A reply that also quotes a post has
kindreply, its parent inref, and the post it quotes inquoted. metricsholdslikes,replies,reposts,quotes,bookmarks, andviews.viewscan be null.
Post lookup request
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);{
"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
}
}Look up an account
GET /api/user/{id} returns one account's profile. {id} is a numeric account ID or a handle, with or without @. Digits alone are read as an account ID, so a handle made only of digits needs the @.
userhas the same fields asauthorin WebSocket post events.pinnedTweetis the account's pinned post, with the same fields astweetin a post lookup. TweetStream fills it in only for accounts it has seen pin a post. It is null otherwise, after the account unpins, or when the post can't be shown right now.
{
"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"
}
}
}Lookup access and errors
Any paid or trialing plan can use lookups. Each account can make 60 lookups per minute across both endpoints, in bursts of up to 10. Up to 4 can be in progress at once. On 429, wait the number of seconds in retryAfterSeconds (also sent as Retry-After) before retrying.
| Status | Body | Meaning |
|---|---|---|
400 | { "error": "Invalid post ID" } | The post ID is not 1 to 20 digits |
400 | { "error": "Invalid account ID or handle" } | The account ID or handle is malformed |
401 | { "error": "Missing or invalid Authorization header" } | No bearer token was sent |
401 | { "error": "Invalid API key" } | The token does not match an API key |
403 | { "error": "An active subscription is required" } | The account has no paid or trialing subscription |
404 | { "error": "Post not found" } | The post was not found or is not public |
404 | { "error": "Account not found" } | No account has this ID or handle |
429 | { "error": "Rate limit exceeded", "retryAfterSeconds": 1 } | The account reached its lookup limit |
429 | { "error": "Too many lookups in progress", "retryAfterSeconds": 1 } | The account already has 4 lookups in progress |
503 | { "error": "Lookup is temporarily unavailable" } | Retry later, after Retry-After when it is sent |
503 | { "error": "Authentication service unavailable" } | The API key could not be checked. Retry later |
Search posts
GET /api/search/posts returns recent X posts that match an X search query, in X's Latest order (not strictly by ID).
queryis required: an X search query, operators included, up to 512 characters.limitis optional: 1 to 40 posts, 20 by default.- Each item in
postsis the post lookup'stweetobject with itsmetricsinside.viewsis null in search. - Results can be up to 30 seconds old.
- No match is a
200with"posts": []and"next": null.
Post search request
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);{
"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"
}Get the next page
next is the URL of the next page. Request it as it is, with the same API key, until it is null.
- A
nextlink works for 30 minutes. - A page can have fewer than
limitposts before the end. Keep followingnext. - One search returns at most 100 posts; after that
nextisnull. Pages can repeat a post, so deduplicate bytweetId.
Read every page
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;
}Search access and errors
Pro, Scale, and Ultra Speed include post search, with either of the account's API keys. Each request costs one from the account's search allowance, next links included. The allowance is separate from lookups. On 429, wait the number of seconds in retryAfterSeconds (also sent as Retry-After) before retrying.
| Status | Body | Meaning |
|---|---|---|
400 | { "error": "Search query is required" } | query is missing or empty |
400 | { "error": "Search query is too long" } | query is over 512 characters |
400 | { "error": "Invalid search query" } | query has control characters or is sent twice |
400 | { "error": "Invalid limit" } | limit is not a whole number from 1 to 40, or is sent twice |
400 | { "error": "This page link is invalid or has expired; start the search again" } | The next link was changed or expired. Search again without page |
401 | { "error": "Missing or invalid Authorization header" } | No bearer token was sent |
401 | { "error": "Invalid API key" } | The token does not match an API key |
403 | { "error": "Post search requires Pro, Scale, or Ultra Speed" } | The account's plans don't include post search |
405 | — | Only GET is supported |
429 | { "error": "Rate limit exceeded", "retryAfterSeconds": 1 } | Over the plan's searches per minute |
429 | { "error": "Too many searches in progress", "retryAfterSeconds": 1 } | Too many searches running at once |
503 | { "error": "Post search is temporarily unavailable" } | Try again shortly (after Retry-After if sent) |
503 | { "error": "Authentication service unavailable" } | The API key could not be checked. Try again shortly |
Search allowance by plan
When the account has more than one of these plans, the largest allowance applies. REST and MCP share it.
| Plan | Requests per minute | In progress at once |
|---|---|---|
| Pro | 60, in bursts of up to 10 | 4 |
| Ultra Speed | 120, in bursts of up to 10 | 6 |
| Scale | 300, in bursts of up to 10 | 10 |