subscribe_tweets - new posts from X accounts, live
Name the X accounts you want to follow and you get each new post from them as a tweet event, seconds after it's posted. Their reposts come too, for each account you switch them on for. It comes with Professional. You connect straight to one of our X stream servers. Add and remove accounts on the open socket whenever you like; tweet_user tells you when an account you added is live (or doesn't exist).
| Channel | Socket.IO, on a stream server's own address (on your dashboard) |
| Auth | your Professional plan's key (the key) |
| Emits | tweet, tweet_user |
| Limit | 50 X accounts and 5 sockets per key on each server (the sockets are shared with the Telegram stream) |
| Plan | Professional |
Servers
There are stream servers in the US, Europe and Asia. Their addresses are on your dashboard once your plan is Professional, with whether each is up. The servers run independently: connect to the one closest to you, or to several and keep whichever copy of a post comes first (by id).
Your key, follows and limits on one server don't affect another. The same servers carry the Telegram stream: one socket can follow X accounts and Telegram chats.
Example
- JavaScript
- Python
import { io } from "socket.io-client";
// YOUR_STREAM_SERVER: a server's address from your dashboard
const socket = io("https://YOUR_STREAM_SERVER", { auth: { api_key: "YOUR_KEY" } });
socket.on("tweet", (t) => {
const delay = ((t.receivedAt - t.postedAt) / 1000).toFixed(2);
console.log(`${t.kind} @${t.user} (+${delay}s): ${t.text}\n ${t.url}`);
});
socket.on("tweet_user", (u) => console.log(`@${u.user}: ${u.status}`, u.message ?? ""));
socket.on("connect_error", (e) => console.error(e.message, e.data?.message));
// Follows belong to the socket: send them again after every (re)connect.
socket.on("connect", () => {
// Posts from all three; cz_binance's reposts too.
const users = ["elonmusk", { user: "cz_binance", reposts: true }, "https://x.com/jack"];
socket.emit("subscribe_tweets", { users }, (ack) => {
if (!ack.ok) return console.error(ack.error, ack.message);
console.log(ack.users, `feed ${ack.feed}`);
});
});
// later: socket.emit("unsubscribe_tweets", { users: ["jack"] });
import socketio
sio = socketio.Client()
@sio.on("tweet")
def on_tweet(t):
delay = (t["receivedAt"] - t["postedAt"]) / 1000
print(f"{t['kind']} @{t['user']} (+{delay:.2f}s): {t['text']}\n {t['url']}")
@sio.on("tweet_user")
def on_user(u):
print(f"@{u['user']}: {u['status']}", u.get("message", ""))
@sio.event
def connect(): # send the follows again after every (re)connect
users = ["elonmusk", {"user": "cz_binance", "reposts": True}]
sio.emit("subscribe_tweets", {"users": users},
callback=lambda ack: print(ack.get("users") or ack))
# YOUR_STREAM_SERVER: a server's address from your dashboard
sio.connect("https://YOUR_STREAM_SERVER", auth={"api_key": "YOUR_KEY"}, transports=["websocket"])
sio.wait()
Connecting
Pass your key in the handshake: auth: { api_key } (or the x-api-key header). A connection without a valid key is refused with a connect_error whose message is one of:
message | When |
|---|---|
api_key_required | No key in the handshake. |
unknown_key | Not a shrine.trade key. |
key_disabled | The key was switched off. |
plan_required | Your plan doesn't include the X stream: it comes with Professional (plan, upgrade). |
authorize_unavailable | The key couldn't be checked just now: reconnect in a few seconds. |
limit_exceeded | Your key already has 5 sockets open on this server: close one first. |
rate_limited | Too many different keys tried from your address: wait a minute. |
server_busy | The server is full: try again in a minute, or use another server. |
Subscribe
socket.emit("subscribe_tweets", { users: ["elonmusk", "cz_binance"] }, ack);
users is a list of X handles: elonmusk, @elonmusk and https://x.com/elonmusk all work, in any case. A comma-separated string or { user: "elonmusk" } work too. Each call adds to what the socket follows; following an account twice changes nothing.
Reposts
A followed account's own posts always come, quote posts among them; its replies don't. Its reposts of other accounts' posts come only if you switch them on for that account:
socket.emit("subscribe_tweets", {
users: [
"elonmusk", // posts only
{ user: "cz_binance", reposts: true }, // posts and reposts
],
}, ack);
// For every account in the call:
socket.emit("subscribe_tweets", { users: ["elonmusk", "jack"], reposts: true }, ack);
reposts is off by default. In an entry it wins over the same switch for the whole call. Name an account you already follow with reposts to change it: it takes no new slot and costs nothing of the day's new accounts. Naming it without reposts leaves it as it is. The switch belongs to the socket, like its follows.
Your key may follow 50 accounts at once on a server, counted across all its sockets there: an account two of your sockets follow takes one of the 50. A call that would go past 50 is refused whole (limit_exceeded), and nothing of it is followed.
A key may also add 100 new accounts a day on each server, and the server takes so many new accounts a day from all keys together. Accounts already in use on that server don't count, so you can add and drop those as often as you like.
Ack
{
"ok": true,
"users": [
{ "user": "elonmusk", "status": "live", "name": "Elon Musk", "reposts": false },
{ "user": "cz_binance", "status": "pending", "reposts": true }
],
"max": 50,
"feed": "up"
}
users- everything the socket follows now, with its status:live- set up: new posts come through;pending- being set up, usually a few seconds; atweet_userevent follows;error- could not be set up yet (messagesays why, e.g. a protected account); it is tried again every few minutes.
reposts- this socket's switch for the account.rejected- only when an account was not followed because X has no account with that handle (or it is suspended).feed-upwhile the stream is live,downfor the moment it reconnects. Your follows are kept either way.
Response - tweet
{
"id": "2119785061592018079",
"kind": "post",
"user": "elonmusk",
"name": "Elon Musk",
"text": "gm",
"url": "https://x.com/elonmusk/status/2119785061592018079",
"avatar": "https://pbs.twimg.com/profile_images/…_reasonably_small.jpg",
"lang": "en",
"postedAt": 1794231117042,
"receivedAt": 1794231117430
}
id- the post's ID, a string (it is too big for a JavaScript number).kind-postorrepost(a quote post is apost). Reposts come only where you switched them on.user/name- the author's handle, in the case X uses, and display name: for a repost, the account that reposted.text- the post's text; for a repost, the reposted post's. A very long post can come shortened;urlhas the whole post.url- the post on X; for a repost, the reposted post.postedAt- when the post was made (for a repost, when it was reposted), in ms.receivedAt- when our server had it, in ms;receivedAt - postedAtis the delay.
A repost carries the post it reposts:
{ "id": "2119785372109914113", "kind": "repost", "user": "cz_binance", "text": "gm", "url": "https://x.com/elonmusk/status/2119785061592018079",
"reposted": { "id": "2119785061592018079", "user": "elonmusk", "url": "https://x.com/elonmusk/status/2119785061592018079" }, "...": "..." }
reposted- the post it reposts: itsid, author andurl. The repost's ownidis what tells two reposts apart.
Every post from a followed account arrives once per socket that follows it (a repost only where reposts is on).
Response - tweet_user
{ "user": "cz_binance", "status": "live", "name": "CZ 🔶 BNB" }
{ "user": "no_such_acct", "status": "not_found", "message": "no X account with this handle (or it is suspended)" }
Sent when an account you added finishes setting up. A not_found account is dropped from your list and gives its slot back.
Unsubscribe
socket.emit("unsubscribe_tweets", { users: ["jack"] }, (ack) => console.log(ack.removed, ack.users));
socket.emit("unsubscribe_tweets", {}); // every account on this socket
The ack's users is what the socket still follows. Closing the socket unsubscribes everything on it.
Your subscriptions
socket.emit("subscriptions", {}, (s) => console.log(s.tweets.key, s.telegram.key));
Changes nothing: it tells you what this socket follows, and what your key follows on this server over all its sockets (what the limits count), for X and Telegram both:
{
"ok": true,
"sockets": 2,
"maxSockets": 5,
"tweets": {
"users": [{ "user": "elonmusk", "status": "live", "name": "Elon Musk", "reposts": false }],
"key": [{ "user": "cz_binance", "status": "live", "name": "CZ 🔶 BNB", "reposts": true, "sockets": 1 },
{ "user": "elonmusk", "status": "live", "name": "Elon Musk", "reposts": false, "sockets": 2 }],
"max": 50,
"newToday": 2,
"newPerDay": 100,
"feed": "up"
},
"telegram": { "chats": [], "key": [], "max": 25, "newToday": 0, "newPerDay": 25, "feed": "up" }
}
sockets- your key's sockets open on this server now, ofmaxSockets.users- what this socket follows, as in the ack.key- every account your key follows on this server, on any of its sockets, with how many of them follow it (sockets);repostsistruethere when any of those sockets has it on.max- the accounts your key may follow at once here;newTodayofnewPerDay- the new accounts your key added here today.telegram- the same for the Telegram stream.
Follows belong to sockets: a socket that reconnects follows nothing until it subscribes again, while key still lists what your other sockets follow.
Errors
error | When |
|---|---|
invalid_request | Something in users is not an X handle (1-15 letters, digits or _), or reposts isn't true or false; nothing of the call is followed. |
limit_exceeded | The call would take your key past 50 accounts on this server (max, followed, message). Unsubscribe some first. |
rate_limited | No more new accounts on this server for now: your key's 100 a day, or the server's day for all keys, is used up (retryAfterMs, message says which). Accounts already in use there don't count and always work. |
An error comes in the ack, and also as a subscription_error event (for clients that don't pass an ack).
Notes
- Included in Professional: posts don't count against any other limit.
- If your plan ends or your key is switched off, the server closes your sockets within a couple of minutes, sending a
subscription_error(plan_requiredorkey_disabled) first. - A server restarting (an update) closes your socket once; reconnect and subscribe again in your
connecthandler, as above.
LimitsProfessional 5 sockets · 50 X accountsSee plans →