Skip to main content

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

ChannelSocket.IO, on a stream server's own address (on your dashboard)
Authyour Professional plan's key (the key)
Emitstweet, tweet_user
Limit50 X accounts and 5 sockets per key on each server (the sockets are shared with the Telegram stream)
PlanProfessional

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​

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"] });

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:

messageWhen
api_key_requiredNo key in the handshake.
unknown_keyNot a shrine.trade key.
key_disabledThe key was switched off.
plan_requiredYour plan doesn't include the X stream: it comes with Professional (plan, upgrade).
authorize_unavailableThe key couldn't be checked just now: reconnect in a few seconds.
limit_exceededYour key already has 5 sockets open on this server: close one first.
rate_limitedToo many different keys tried from your address: wait a minute.
server_busyThe 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; a tweet_user event follows;
    • error - could not be set up yet (message says 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 - up while the stream is live, down for 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 - post or repost (a quote post is a post). 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; url has 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 - postedAt is 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: its id, author and url. The repost's own id is 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, of maxSockets.
  • 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); reposts is true there when any of those sockets has it on.
  • max - the accounts your key may follow at once here; newToday of newPerDay - 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​

errorWhen
invalid_requestSomething 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_exceededThe call would take your key past 50 accounts on this server (max, followed, message). Unsubscribe some first.
rate_limitedNo 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_required or key_disabled) first.
  • A server restarting (an update) closes your socket once; reconnect and subscribe again in your connect handler, as above.

LimitsProfessional 5 sockets · 50 X accountsSee plans →