Skip to main content
The Scrapest WebSocket endpoint delivers real-time tweet events for accounts you are tracking. Each message is a single ResolvedTweet object encoded as JSON.

​
Connection

Connect to the WebSocket endpoint by passing your API key as the x-api-key header during the upgrade handshake. 
wss://scrape.st/ws
​
x-api-key
string
required
Your unique API key. The connection will be rejected with HTTP 401 if this is missing or invalid.

​
Code Examples

const ws = new WebSocket("wss://scrape.st/ws", {
  headers: { "x-api-key": "your-api-key" },
});

ws.onopen = () => console.log("Connected to Scrapest stream");
ws.onmessage = ({ data }) => {
const tweet = JSON.parse(data);
console.log(`[@${tweet.author.screen_name}]: ${tweet.text}`);
};
ws.onclose = () => console.log("Disconnected");
ws.onerror = (e) => console.error("WS error", e);

​
Keep-Alive

The server sends WebSocket ping frames every 30 seconds to keep idle connections alive. If your client does not respond with a pong within 60 seconds, the connection will be terminated. Most WebSocket libraries handle ping/pong automatically. If yours doesn’t, send a "ping" text message and the server will respond with "pong". 
// Browser clients — send a periodic ping if needed
setInterval(() => ws.send("ping"), 25_000);

​
Events (Tweet Payload)

Every message you receive is a JSON-encoded ResolvedTweet object. The payload contains the full tweet and author information.
​
id
string
Unique tweet ID.
​
text
string
Full text of the tweet.
​
created_at
string
ISO 8601 timestamp of when the tweet was created.
​
lang
string
BCP 47 language tag (e.g. "en", "fr").
​
favorite_count
number
Like count.
​
retweet_count
number
Retweet count.
​
reply_count
number
Reply count.
​
quote_count
number
Quote count.
​
bookmark_count
number
Bookmark count.
​
author
object
required
The account that posted the tweet.
​
entities
object
Parsed entities extracted from the tweet text.
​
media
array
Attached media items (photos, videos, GIFs). Each item contains media_url_https, type, and an optional video_info block.
​
retweeted_tweet
boolean
true if this is a retweet.
​
retweeted
object
The original tweet object when retweeted_tweet is true.
​
quoted_tweet
object
The quoted tweet when this is a quote-tweet.
​
note_tweet_text
string
Extended text for long-form “Note Tweets”.
​
in_reply_to_status_id
string
ID of the tweet being replied to.
​
conversation_id
string
ID of the root tweet in the conversation thread.

​
Example Payload

{
  "id": "1760123456789012345",
  "text": "This is a real-time tweet delivered via WebSocket 🚀",
  "created_at": "2024-02-21T00:00:00.000Z",
  "lang": "en",
  "favorite_count": 42,
  "retweet_count": 5,
  "reply_count": 3,
  "quote_count": 1,
  "bookmark_count": 10,
  "author": {
    "id": "44196397",
    "name": "Elon Musk",
    "screen_name": "elonmusk",
    "profile_image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
    "verified": false,
    "is_blue_verified": true
  },
  "entities": {
    "hashtags": [],
    "user_mentions": [],
    "urls": []
  },
  "media": null,
  "retweeted_tweet": false,
  "retweeted": null,
  "quoted_tweet": null,
  "note_tweet_text": null,
  "in_reply_to_status_id": null,
  "conversation_id": "1760123456789012345"
}

​
Error Codes

CodeReason
401 Unauthorizedx-api-key header is missing.
401 Invalid API KeyThe provided key does not exist.
Connection closedYour session was idle for more than 60 seconds with no pong reply.