Skip to docs content
Browse and search
On this page

History API

Replay stored content, profile, follow, and affiliate events through the History API, or look up one post or account.

Open OpenAPI spec
Open in chat
Reviewed against product code on September 24, 2026

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.

ParameterRequiredNotes
handle, handles, handle[], handles[]NoOne handle, repeated handles, or comma-separated handles
startDateNoISO datetime lower bound
endDateNoISO datetime upper bound
limitNoDefaults to 100; maximum 1000
typeNoTWEET, PROFILE, FOLLOW, or AFFILIATE; case-insensitive. Defaults to TWEET
cursorNoOpaque nextCursor from the previous page; keep every other filter unchanged

History request

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);

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';
  };
};
{
  "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

StatusBodyMeaning
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.

  • tweet has the same fields as content in a TWEET History row.
  • A reply that also quotes a post has kind reply, its parent in ref, and the post it quotes in quoted.
  • metrics holds likes, replies, reposts, quotes, bookmarks, and views. views can be null.

Post lookup request

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
  }
}

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 @.

  • user has the same fields as author in WebSocket post events.
  • pinnedTweet is the account's pinned post, with the same fields as tweet in 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.

StatusBodyMeaning
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).

  • query is required: an X search query, operators included, up to 512 characters.
  • limit is optional: 1 to 40 posts, 20 by default.
  • Each item in posts is the post lookup's tweet object with its metrics inside. views is null in search.
  • Results can be up to 30 seconds old.
  • No match is a 200 with "posts": [] and "next": null.

Post search request

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"
}

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 next link works for 30 minutes.
  • A page can have fewer than limit posts before the end. Keep following next.
  • One search returns at most 100 posts; after that next is null. Pages can repeat a post, so deduplicate by tweetId.

Read every page

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;
}

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.

StatusBodyMeaning
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.

PlanRequests per minuteIn progress at once
Pro60, in bursts of up to 104
Ultra Speed120, in bursts of up to 106
Scale300, in bursts of up to 1010