History API
History API documentation for replaying TweetStream events on supported plans, including auth, request shape, response shape, and replay use cases.
Direct answer
The History API lets Pro and Scale users replay stored TweetStream events after reconnects, incidents, or downstream outages.
Authentication
Call GET https://api.tweetstream.io/api/history with Authorization: Bearer <API_KEY>. History is available to Pro and Scale users whose subscriptions are active or trialing.
Request shape
Use query parameters to bound the replay window and event type. Keep clients idempotent because history can return events you already received live over WebSocket.
| Parameter | Required | Notes |
|---|---|---|
| handle, handles, handle[], handles[] | No | One handle, repeated handles, or comma-separated handles |
| startDate | No | ISO datetime lower bound, for example 2026-03-01T00:00:00.000Z |
| endDate | No | ISO datetime upper bound |
| limit | No | Defaults to 100; maximum 1000 |
| type | No | tweet, profile, or follow; defaults to tweet events |
Response shape
Responses return stored social events plus metadata about the query. Tweet rows include author, text, timestamps, references, and any available token or OCR enrichment.
| Field | Type | Notes |
|---|---|---|
| data | array | Stored events, newest first |
| metadata.type | string | Present when a specific event family was requested |
| metadata.count | number | Returned event count |
| metadata.handles | array | Normalized handle filters, when supplied |
Replay use cases
Use history for missed-connection recovery, incident review, strategy backtests, and Discord or bot reconciliation after downstream downtime.
- Replay after a reconnect window
- Audit what a bot received during an incident
- Review alerts that matched a handle or keyword
Questions
Start real-time Twitter WebSocket alerts today
WebSocket delivery, OCR, and token detection - no infrastructure to build.
From $199/mo · Minimum/Pro 3-day trial · OCR + token detection included