Twitter Account Activity API: Polling Alternative

The watermark loop, which is the whole pattern

Store one value per watch: the highest post ID you have already processed. Each run reads newest first, stops at the watermark, and handles everything above it. The loop is idempotent, so a double run processes nothing twice, and it self-heals after an outage because the watermark did not move while the job was down.

import requests

BASE = "https://api.twitterapis.com"
HEAD = {"Authorization": "Bearer YOUR_API_KEY"}

def poll_mentions(user_name, watermark):
    """Return (new_events, new_watermark). Pages until it reaches the watermark."""
    fresh, cursor, top = [], None, watermark
    while True:
        params = {"username": user_name}
        if cursor:
            params["cursor"] = cursor
        body = requests.get(
            f"{BASE}/twitter/user/mentions", params=params, headers=HEAD
        ).json()

        for post in body.get("tweets", []):
            if watermark and int(post["id"]) <= int(watermark):
                return fresh, top          # caught up, stop paging
            if top is None or int(post["id"]) > int(top):
                top = post["id"]
            fresh.append(post)

        if not body.get("has_more"):
            return fresh, top
        cursor = body["next_cursor"]

# run this on a cron; persist the watermark between runs
events, watermark = poll_mentions("nasa", watermark=None)
print(len(events), "new mentions, watermark now", watermark)

const BASE = "https://api.twitterapis.com";
const HEAD = { Authorization: "Bearer YOUR_API_KEY" };

async function pollMentions(userName, watermark) {
  const fresh = [];
  let cursor = null;
  let top = watermark;

  for (;;) {
    const url = new URL(`${BASE}/twitter/user/mentions`);
    url.searchParams.set("username", userName);
    if (cursor) url.searchParams.set("cursor", cursor);
    const body = await (await fetch(url, { headers: HEAD })).json();

    for (const post of body.tweets ?? []) {
      if (watermark && BigInt(post.id) <= BigInt(watermark)) {
        return { fresh, watermark: top };  // caught up, stop paging
      }
      if (!top || BigInt(post.id) > BigInt(top)) top = post.id;
      fresh.push(post);
    }

    if (!body.has_more) return { fresh, watermark: top };
    cursor = body.next_cursor;
  }
}

// run this on a schedule; persist the watermark between runs
const { fresh, watermark } = await pollMentions("nasa", null);
console.log(fresh.length, "new mentions, watermark now", watermark);

The detail that matters is the inner paging loop. Reading only the first response is what makes naive polling drop events during a burst, because a spike can push more than one page of activity between two runs. Keep following next_cursor until you reach the watermark, and a burst arrives complete.

Make your first API call

Before you write the loop above, prove the one request it depends on. The whole setup is a key and a single GET, and it fits inside the free credit with room to spare.

Create an API key

Sign up with Google or email and the key is in your dashboard straight away: no X developer account, no use-case review and no card. Every new account starts with $0.50 in credit, which at $0.0008 a read is 625 polls. Public activity, meaning mentions, replies, new posts, reposters and followers, needs nothing more than that key in an Authorization: Bearer header. Direct messages are the one exception: they read against an X session you register once with a free call to POST /twitter/customer/session.

curl "https://api.twitterapis.com/twitter/user/mentions?username=nasa" \
  -H "Authorization: Bearer YOUR_API_KEY"

A 200 means the key works. A 401 means the header is wrong or missing, so re-copy the key and check that the word Bearer comes first. An empty result on a quiet account is a valid answer, not an error, so test against an account that is mentioned often. The real-time mention monitoring guide takes this same request from one call to a running service.

The first test to run

Run the watermark loop twice in a row against a busy account. The first run returns a page of events and stores a watermark; the second, seconds later, should return nothing or close to it. If the second run repeats events, the watermark is not being saved between runs, and that bug would have sent every alert twice in production. Then set the stored watermark back to an older post ID and run once more: the loop should page through the gap and stop at that ID, which is exactly what happens after a real outage. If you plan to reply to events, test that path with POST /twitter/draft/create, which saves a draft to the account and never publishes it. What a monitor should report when it is quietly failing, rather than merely quiet, is covered in what a monitoring API should tell you when it is failing.

What a continuous watch costs

Both figures assume one call per run at the standard $0.0008 rate, which holds while activity fits a single page. Any realistic polling interval sits far under our 600 req/min ceiling, so interval is a cost decision: poll a high-value account every minute and sweep a long tail hourly on the same key. Size a mixed workload on the Twitter API cost calculator.

Flat pricing, no plan

There is no tier to pick before you know your volume, no monthly minimum and no seat. Every public activity read on this page, mentions, replies, new posts, reposters and followers, is $0.0008 a call. The two DM reads are $0.0016 a call, and so is posting a reply. Checking your balance through GET /account/me is free, and so is registering a webhook or a monitor. That makes the bill a straight product of three numbers you choose: how many accounts you watch, how often you poll each one, and how many pages a busy interval needs. The poll cadence cost breakdown for 50 accounts works that product through at every common interval.

Only completed calls are metered

A call that fails is not billed, so a retry loop with backoff around a timeout or a 429 costs time and not credit. A call that completes is billed even when it finds nothing new, and that is the part polling budgets tend to miss: a quiet account polled every minute costs the same as a busy one, because the empty answer took the same work. The lever is therefore interval, not activity. Poll the accounts where a minute matters every minute, sweep the long tail hourly, and the two groups bill at very different rates on the same key.

Respond to an event from the same key

Detecting a mention is half of most workflows; the other half is answering it. The write endpoints run as the X account behind your registered session, on the same key that runs the watch, so there is no second integration to wire up.

Create or schedule posts in reply

POST /twitter/tweet/create takes the reply text and the ID of the post you are answering in reply_to, so the event your loop just stored is all the context the reply needs. To answer at a set time instead, POST /twitter/scheduled/create takes the same fields plus execute_at in epoch seconds, and it will post publicly at that moment unless you cancel it with POST /twitter/scheduled/delete first. Both bill $0.0016 a call. For anything a person should approve, save a draft instead: it lands in the account's own composer and is never published by the API.

Upload media with a reply

Attaching an image is two steps. POST /twitter/media/upload takes the image as base64 in media_data and returns a media_id for $0.0008. Pass that ID in media_ids on the create or scheduled call, up to four per post. For a video, a GIF or a large file, read GET /twitter/media/status until processing has finished before you attach it, because an ID that is still processing is the usual reason an attachment fails.

Should I use the MCP server or the REST API?

Narrower surfaces for a single event type

If mentions are the only event you care about, the Twitter mentions API goes deeper on that one loop. Follower-change watches are covered on the Twitter followers API, and to react to an event rather than only record it, the Twitter engagement API covers replying, liking and reposting from the same key. The Twitter REST API overview documents the paging and error contract every watch depends on.