> ## Documentation Index > Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt > Use this file to discover all available pages before exploring further. # Track Mentions # 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](https://api.sorsa.io/blog/twitter-mentions-api) on the blog. ## Quick Start ```bash theme={null} 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](https://api.sorsa.io/playground). Every account starts with 100 free requests, no card required. *** ## Endpoint Reference ```text theme={null} 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 ```json theme={null} { "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](https://docs.sorsa.io/pagination) for handling patterns and [Response Format](https://docs.sorsa.io/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`](https://docs.sorsa.io/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. ```python theme={null} 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. ```python theme={null} 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. ```python theme={null} 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. ```python theme={null} 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](https://docs.sorsa.io/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](https://docs.sorsa.io/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](https://docs.sorsa.io/search-tweets) - keyword-based search for untagged mentions. * [Search Operators](https://docs.sorsa.io/search-operators) - operators for complex queries (media, geo, Boolean). * [Real-Time Monitoring](https://docs.sorsa.io/real-time-monitoring) - polling architecture with deduplication and backoff. * [Historical Data](https://docs.sorsa.io/historical-data) - retrieving older tweets by date range. * [API Reference](https://docs.sorsa.io/api-reference/search/search-mentions) - full endpoint specification.