Track Mentions

The /mentions endpoint returns tweets that mention a specific handle. Use it to monitor brand mentions, route support inquiries, measure campaign engagement, and watch competitive activity. It offers the richest filter set of any Sorsa search endpoint: engagement thresholds and date bounds are first-class parameters in the request body. Results are paginated at up to 20 tweets per page.

Note: For a full walkthrough with production code, multi-channel monitoring patterns, and competitive analysis workflows, see How to Track Twitter Mentions With API on the blog.

Quick Start

curl -X POST https://api.sorsa.io/v3/mentions \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AppleSupport",
    "order": "latest",
    "min_likes": 10,
    "since_date": "2026-03-01"
  }'

Tip: Prefer a UI? Run /mentions without writing code in the API Playground. Every account starts with 100 free requests, no card required.

Endpoint Reference

POST https://api.sorsa.io/v3/mentions

Parameter	Type	Required	Description
`query`	string	Yes	The handle to track, without the @ symbol. Example: `"elonmusk"`.
`order`	string	No	`"latest"` (default, newest first) or `"popular"` (engagement-ranked).
`since_date`	string	No	Start date in `YYYY-MM-DD` format.
`until_date`	string	No	End date in `YYYY-MM-DD` format.
`min_likes`	integer	No	Minimum likes a mention must have.
`min_retweets`	integer	No	Minimum retweets a mention must have.
`min_replies`	integer	No	Minimum replies a mention must have.
`next_cursor`	string	No	Pagination cursor from a previous response.

Each call counts as a single request against your quota, whether it returns one mention or twenty.

Response

{
  "tweets": [
    {
      "id": "2031847200012345678",
      "full_text": "@AppleSupport My iPhone keeps restarting after the latest update. Anyone else?",
      "created_at": "2026-03-08T14:22:31Z",
      "lang": "en",
      "likes_count": 47,
      "retweet_count": 12,
      "reply_count": 8,
      "quote_count": 2,
      "view_count": 15200,
      "is_reply": false,
      "is_quote_status": false,
      "user": {
        "id": "9876543210",
        "username": "frustrated_user",
        "display_name": "Alex",
        "followers_count": 1240,
        "verified": false
      }
    }
  ],
  "next_cursor": "DAABCgABGSmiaxkA..."
}

Each mention carries full engagement metrics and the embedded author profile. The user object holds the complete profile (trimmed above for readability), and all timestamps are ISO 8601. When next_cursor is present, more pages are available; when it is null or absent, you have reached the end. See Pagination for handling patterns and Response Format for the full field list.

/mentions vs /search-tweets

The two endpoints solve different problems:

Use /mentions for posts that tag a specific handle (@brand). It catches @-tags, replies, and references, with min_likes, min_retweets, min_replies, since_date, and until_date available as first-class parameters.
Use /search-tweets for keyword matches that do not include the handle. Searching "Nike" -from:Nike lang:en catches posts that name the brand in prose. Reach for it when you need Boolean logic, media filters, or other operators beyond what /mentions supports.

For complete brand coverage, run both endpoints in parallel and deduplicate by tweet ID.

Common Patterns

Filter by engagement

Pull only mentions that have reached an audience. Useful for reputation dashboards and PR monitoring.

import requests

API_KEY = "YOUR_API_KEY"
URL = "https://api.sorsa.io/v3/mentions"

body = {"query": "nike", "order": "popular", "min_likes": 100}
resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)
mentions = resp.json().get("tweets", [])

Pull every mention (support queue)

Drop the engagement filters and sort chronologically to catch every mention, including zero-engagement ones.

body = {"query": "YourBrandSupport", "order": "latest", "since_date": "2026-05-10"}
resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)

Date-windowed campaign analysis

Bound mentions to a campaign window with since_date and until_date, then loop through next_cursor until it runs out.

import time

def all_mentions(handle, since, until, max_pages=50):
    out, cursor = [], None
    for _ in range(max_pages):
        body = {"query": handle, "order": "latest", "since_date": since, "until_date": until}
        if cursor:
            body["next_cursor"] = cursor
        resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)
        resp.raise_for_status()
        data = resp.json()
        out.extend(data.get("tweets", []))
        cursor = data.get("next_cursor")
        if not cursor:
            break
        time.sleep(0.1)
    return out

Polling for new mentions

Track the newest tweet ID across iterations so you only surface mentions you have not seen before. Compare IDs numerically, since they are returned as strings.

last_seen_id = None
while True:
    resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
                         json={"query": "yourbrand", "order": "latest"})
    tweets = resp.json().get("tweets", [])
    if tweets and last_seen_id is None:
        last_seen_id = tweets[0]["id"]
    elif tweets:
        new = [t for t in tweets if int(t["id"]) > int(last_seen_id)]
        # handle `new` mentions
        if new:
            last_seen_id = new[0]["id"]
    time.sleep(15)

Persist last_seen_id to disk or Redis so the loop survives restarts, and wrap the request in try/except with a backoff so a transient error does not kill the process. For the full real-time pattern with deduplication and backoff, see Real-Time Monitoring.

Common Pitfalls

min_likes set too high for support use cases. A bug report with 2 likes matters more than a meme with 500. For support queues, set min_likes to 0 and rely on keyword routing instead.
Single-page reads on high-volume handles. One request returns up to 20 mentions. For brands with hundreds of daily mentions, always paginate through next_cursor. Each page is one request against your quota, so budget accordingly.
Treating /mentions as full coverage. It only catches @-tagged posts. Combine it with /search-tweets to catch untagged brand references.
Aggressive polling on low-volume accounts. Match the polling interval to mention volume: every 15 seconds for high-traffic brands, every minute or two for smaller accounts. The rate limit is 20 req/s across all plans (Rate Limits).
Not persisting state across restarts. Without a durable checkpoint, a restarted monitor either re-alerts on old mentions or skips the gap.

Next Steps

Search Tweets - keyword-based search for untagged mentions.
Search Operators - operators for complex queries (media, geo, Boolean).
Real-Time Monitoring - polling architecture with deduplication and backoff.
Historical Data - retrieving older tweets by date range.
API Reference - full endpoint specification.

Getting started

Core Mechanics

Solution Guides

Support & Resources

Track Mentions

Track Mentions

Quick Start

Endpoint Reference

Response

/mentions vs /search-tweets

Common Patterns

Filter by engagement

Pull every mention (support queue)

Date-windowed campaign analysis

Polling for new mentions

Common Pitfalls

Next Steps

​Track Mentions

​Quick Start

​Endpoint Reference

​Response

​/mentions vs /search-tweets

​Common Patterns

​Filter by engagement

​Pull every mention (support queue)

​Date-windowed campaign analysis

​Polling for new mentions

​Common Pitfalls

​Next Steps

Track Mentions

Quick Start

Endpoint Reference

Response

/mentions vs /search-tweets

Common Patterns

Filter by engagement

Pull every mention (support queue)

Date-windowed campaign analysis

Polling for new mentions

Common Pitfalls

Next Steps