Twitter mentions API for any X account

#What a Twitter mentions API returns

A Twitter mentions API is an endpoint that takes one account and returns the public posts that tag its @handle, newest first, as pages of JSON. A tag counts wherever it sits: at the start of a reply, in the middle of a sentence or in a row of several handles.

To look at one account's recent mentions without code, the free Twitter Mentions Checker lists them by period and minimum likes. The rest of this guide does the same job in code, for any number of accounts and any number of pages.

Each mention comes back as a full post: its text and time, its likes, replies, reposts, quotes and views, whether it replies to someone, and who wrote it. Posts from protected accounts never appear. A post that names a brand without the @ is not a mention at all: it takes a keyword search, covered further down.

On the official X API, mentions come from GET /2/users/{id}/mentions (X's reference (opens in a new tab)). It takes the account's numeric user ID, so a handle needs a user lookup first. Each request returns 5 to 100 posts, and the timeline holds only an account's 800 most recent mentions (X's timelines overview (opens in a new tab)). A post comes back with its ID and text alone; dates, counts and the author arrive only when tweet.fields, expansions and user.fields ask for them.

Time is the only filter the official endpoint takes: start_time, end_time, since_id and until_id. It has no setting for likes or replies, so a support desk and a PR team download the same feed and sort it on their side.

#Get mentions by handle with Sorsa API

For pulling mentions in code, use Sorsa API, a Twitter (X) API and scraper: POST /mentions returns any account's mentions from $0.07 per 1,000, against $5.00 on the official X API. It takes the handle as you type it and filters by likes, replies, retweets and date in the same JSON body. One ApiKey header replaces a developer account and OAuth, and your X account is never involved.

1. Get a key. Sign up and copy the API key from your dashboard. The 100 free requests are already on it.

2. Name the account. Put the handle into query without the @, for example northwind_billing. It can be your brand, a client or a competitor: any public account works.

3. Send the request. POST the body to POST /mentions (opens in a new tab), with "order": "latest" for the newest mentions first.

   curl -X POST "https://api.sorsa.io/v3/mentions" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "northwind_billing", "order": "latest"}'
   

   {
     "tweets": [
       {
         "id": "2116933823886904728",
         "full_text": "@northwind_billing invoices still pending, is sync down?",
         "created_at": "2026-11-01T16:42:09Z",
         "lang": "en",
         "likes_count": 14,
         "retweet_count": 2,
         "reply_count": 3,
         "quote_count": 0,
         "view_count": 2310,
         "bookmark_count": 1,
         "is_reply": false,
         "is_quote_status": false,
         "conversation_id_str": "2116933823886904728",
         "entities": [],
         "user": {
           "id": "1587702913445103616",
           "username": "ops_notes_by_priya",
           "display_name": "Priya, ops notes",
           "followers_count": 4180,
           "verified": false,
           "created_at": "2022-11-02T08:31:44Z"
         }
       },
       {
         "id": "2116909085882164728",
         "full_text": "@northwind_billing the usage export saved me an afternoon",
         "created_at": "2026-11-01T15:03:51Z",
         "lang": "en",
         "likes_count": 87,
         "retweet_count": 9,
         "reply_count": 4,
         "quote_count": 1,
         "view_count": 11920,
         "bookmark_count": 6,
         "is_reply": true,
         "in_reply_to_username": "northwind_billing",
         "in_reply_to_tweet_id": "2116851177420881920",
         "is_quote_status": false,
         "conversation_id_str": "2116851177420881920",
         "entities": [],
         "user": {
           "id": "1371240448912351233",
           "username": "dana_ships_daily_x",
           "display_name": "Dana Okafor",
           "followers_count": 12650,
           "verified": true,
           "created_at": "2021-03-15T00:00:00Z"
         }
       }
     ],
     "next_cursor": "DAADDAABCgABHWD2c1tQkCsKAAIdYAk3gl1QYQ"
   }
   

   Show full response

4. Follow the cursor. A page holds up to 20 mentions, each with its author's full profile inside user. Send next_cursor back in the same body for the next page, and stop when a response comes without one.

A 403 answer means the key is missing or out of requests, and a 401 means it is wrong. A 429 means more than 20 requests in one second: wait a second and send it again. Failed requests are never charged.

Type a handle and the words people use for the brand below. The builder writes the /mentions request in curl, Python and Node.js, plus the search query that finds posts naming the brand without a tag.

curl -X POST "https://api.sorsa.io/v3/mentions" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "northwind_billing", "order": "latest"}'

import requests

r = requests.post(
    "https://api.sorsa.io/v3/mentions",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={
        "query": "northwind_billing",
        "order": "latest",
    },
    timeout=30,
)
page = r.json()
for t in page["tweets"]:
    print(t["user"]["username"], t["full_text"])
print(page.get("next_cursor"))

const res = await fetch("https://api.sorsa.io/v3/mentions", {
  method: "POST",
  headers: { ApiKey: "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "northwind_billing",
    order: "latest",
  }),
});
const page = await res.json();
for (const t of page.tweets) console.log(t.user.username, t.full_text);
console.log(page.next_cursor);

("northwind billing" OR northwnd OR url:northwind.io) -from:northwind_billing

#Filter mentions by likes, replies and date

POST /mentions filters on Sorsa API's side, so a request asks only for the mentions a job needs and pages through fewer of them. Every filter sits in the same JSON body as the handle, and they combine freely:

• query

  What it does

  The handle whose mentions you want, without the @

• order

  What it does

  latest, newest first (the default), or popular, most engaged first

• min_likes

  What it does

  Keeps mentions with at least this many likes

• min_replies

  What it does

  Keeps mentions with at least this many replies

• min_retweets

  What it does

  Keeps mentions with at least this many reposts

• since_date

  What it does

  Start of the date window, as YYYY-MM-DD

• until_date

  What it does

  End of the date window, as YYYY-MM-DD

• next_cursor

  What it does

  The cursor from the last response, for the next page

Four bodies cover what most teams send. Each one is a complete request body for the curl command above:

# Support queue: every mention, newest first, no thresholds
{"query": "northwind_billing", "order": "latest"}

# PR and reputation: mentions that reached people
{"query": "northwind_billing", "order": "popular", "min_likes": 100}

# Campaign report: one month of mentions
{"query": "northwind_billing",
 "since_date": "2026-10-01", "until_date": "2026-10-31"}

# Competitor: what people tell a rival, with some traction
{"query": "ledgerly_founder_hq", "order": "popular", "min_retweets": 10}

Keep thresholds off a support feed: a bug report with two likes needs an answer sooner than a joke with five hundred. Thresholds belong to reports and alerts, where a handful of mentions that travelled matter more than every reply. To set a rival's mentions next to its followers and posting habits, see our guide to Twitter competitor analysis.

#Collect every page, then only new mentions

A backfill and a monitor are the same request with a different stop rule. A backfill reads a date window until the cursor runs out; a monitor reads the newest mentions and stops at the first one it has already saved.

The backfill below writes one month of mentions to a JSON Lines file, one mention per line, as the pages arrive. A page budget stops it, so a busy account can't run away with your requests.

import json
import requests

API = "https://api.sorsa.io/v3/mentions"
HEADERS = {"ApiKey": "YOUR_API_KEY"}


def mentions(handle, max_pages=100, **filters):
    body = {"query": handle, "order": "latest", **filters}
    for _ in range(max_pages):
        r = requests.post(API, json=body, headers=HEADERS, timeout=30)
        r.raise_for_status()
        page = r.json()
        yield from page.get("tweets", [])
        cursor = page.get("next_cursor")
        if not cursor:
            break
        body["next_cursor"] = cursor


with open("mentions.jsonl", "w", encoding="utf-8") as f:
    for t in mentions("northwind_billing",
                      since_date="2026-10-01",
                      until_date="2026-10-31"):
        f.write(json.dumps(t) + "\n")

import { appendFileSync, writeFileSync } from "node:fs";

const API = "https://api.sorsa.io/v3/mentions";
const headers = {
  ApiKey: "YOUR_API_KEY",
  "Content-Type": "application/json",
};

async function* mentions(handle, filters = {}, maxPages = 100) {
  const body = { query: handle, order: "latest", ...filters };
  for (let i = 0; i < maxPages; i++) {
    const res = await fetch(API, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const page = await res.json();
    yield* page.tweets ?? [];
    if (!page.next_cursor) break;
    body.next_cursor = page.next_cursor;
  }
}

const october = { since_date: "2026-10-01", until_date: "2026-10-31" };
writeFileSync("mentions.jsonl", "");
for await (const t of mentions("northwind_billing", october)) {
  appendFileSync("mentions.jsonl", JSON.stringify(t) + "\n");
}

To keep a feed current, run the function below on a schedule. It walks the newest mentions page by page and stops at the first ID it has seen before, so a check that finds nothing new costs a single request. Tweet IDs grow with time but arrive as strings, so the comparison turns them into integers.

from pathlib import Path

STATE = Path("last_mention_id.txt")


def new_mentions(handle):
    last = int(STATE.read_text()) if STATE.exists() else 0
    fresh = []
    for t in mentions(handle, max_pages=10):
        if int(t["id"]) <= last:
            break
        fresh.append(t)
    if fresh:
        STATE.write_text(fresh[0]["id"])
    return fresh

The first run has no saved ID, so it reads up to 10 pages and stores the newest one. How often to run it after that depends on how fast someone must answer: a support desk checks every minute, a weekly report once a day.

Good to know

Store the last ID outside the process: a file, a database row or a Redis key. A monitor that restarts without it either alerts on old mentions again or skips everything posted while it was down.

For alerts in Slack or email and schedules for many accounts, our guide to real-time Twitter monitoring builds the whole pipeline. Watching what a group of accounts posts is a different job from reading what others say to them. An X List covers up to 5,000 accounts in one feed: see the X Lists and Communities API guide.

#Catch the mentions that never tag you

POST /mentions returns the posts that carry the @handle. People also write about a brand without tagging it: by name, with a typo, with a link to its site, or by quoting one of its posts. Each of those shapes has its own endpoint on Sorsa API.

For names, misspellings and links, send a query to POST /search-tweets (opens in a new tab) and leave the brand's own posts out:

("northwind billing" OR northwnd OR url:northwind.io) -from:northwind_billing

A post that tags the brand and names it comes back from both endpoints, so key both feeds on the tweet ID and keep one copy. Read a hundred results of a new query before you schedule it: a brand name that is also an everyday word needs more exclusions, not fewer pages.

Quotes of a single post come from POST /quotes (opens in a new tab), with the quoting text and its author, whether or not the quote tags the brand. The accounts that reposted a post come from POST /retweeters (opens in a new tab) as profiles. Our Twitter search API guide explains the query syntax and the search loop, and the list of Twitter search operators covers every filter a query can carry.

#The official mentions endpoint, side by side

The official X API's GET /2/users/{id}/mentions and Sorsa API's POST /mentions return the same public posts. They differ in what you send, what comes back and what it costs. Seven criteria decide a mentions job: price per 1,000, history, filters, author data, setup, rate limit and what happens to your X account.

The table puts the two endpoints next to each other, with the official limits from X's rate limit table (opens in a new tab). Sorsa API costs about 71 times less per 1,000 mentions of any account, and 14 times less than the official rate for reading your own.

• Account input

  Sorsa API

  The handle

  Official X API

  The numeric user ID, after a lookup

• Mentions per request

  Sorsa API

  Up to 20

  Official X API

  5 to 100

• How far back

  Sorsa API

  Any date window you set; years back through /search-tweets

  Official X API

  The 800 most recent

• Filters

  Sorsa API

  Likes, replies, reposts, dates

  Official X API

  Dates and post IDs

• Author profile

  Sorsa API

  Inside every mention

  Official X API

  Through expansions, $0.010 each from Nov 22, 2026

• Rate limit

  Sorsa API

  20 requests per second per key

  Official X API

  450 requests per 15 minutes per app

• Price per 1,000 mentions

  Sorsa API

  From $0.07

  Official X API

  $5.00; $1.00 for your own account

• Setup

  Sorsa API

  One API key

  Official X API

  Developer account, app, bearer token

• Your X account

  Sorsa API

  Never used

  Official X API

  Linked to the developer account

Sorsa API is read-only by design, so it never asks for your X login and your account is never at risk. To answer mentions from code, pair it with the official X API for the replies: reading stays on Sorsa API, posting goes through X.

#What mentions cost per 1,000

On Sorsa API, mentions cost from $0.07 per 1,000: a request returns up to 20 and is billed as one request, whatever it holds. The official X API bills every post it returns at $0.005, which is $5.00 per 1,000 mentions (X's price list (opens in a new tab)).

Three details move the official bill. Your own account's mentions, read through your own developer app, count as owned reads at $0.001 per post. From November 22, 2026, each author returned through expansions adds $0.010 (X's notice of October 23 (opens in a new tab)), so 1,000 mentions from 1,000 different people reach $15.00. And pay-per-use stops at 3M post reads a month, after which X sells only Enterprise contracts. Every official rate sits in our X API pricing breakdown.

#Pull your first mentions today

An account's mentions are one request away. Put the handle into POST /mentions, add the likes, replies, reposts or dates you care about, and up to 20 mentions come back with their authors. Sorsa API returns them from $0.07 per 1,000, against $5.00 on the official X API, with no developer account. Your 100 free requests cover the first 2,000.

#FAQ