# ๐Ÿ”Ž X (Twitter) Brand Mention & Keyword Monitor (`kazkn/x-mentions-delta-monitor`) Actor Monitor X (Twitter) brand mentions, handles, hashtags, phrases, and keywords from a signed-in session. Export strict visible matches or only new deduplicated events through a persistent checkpoint. Requires ct0 and auth\_token cookies; no paid X API. - **URL**: https://apify.com/kazkn/x-mentions-delta-monitor.md - **Developed by:** [KazKN](https://apify.com/kazkn) (community) - **Categories:** Social media, Marketing, Automation - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** โ€” the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** โ€” [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** โ€” the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** โ€” the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** โ€” the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README Monitor brand mentions, handles, hashtags, phrases, or keywords on X (Twitter) from a signed-in session. Choose a recent snapshot or a persistent feed of new, deduplicated eventsโ€”without a paid X API subscription. [![Turn authenticated X search into a clean feed of new brand mentions with stable IDs and visible match evidence in strict mode](docs/assets/x-mentions-delta-monitor-hero-v1.png)](https://console.apify.com/actors/PydwZNm405SifBARu/input) **Concrete outcome:** a bounded snapshot or a persistent feed of new matching posts. Stable mentionId values make every delivered row safe to upsert; each row also includes the exact `query`, the returned `matchedText`, the post URL, and timestamps for downstream alerts. Visible match evidence is guaranteed only in strict mode; X search semantics mode preserves X's own candidate decision. > **Before you start:** a live run requires the `ct0` and `auth_token` cookies from an X account that can use search. The step-by-step instructions below show where to find them and exactly what to paste. | Your intent | Outcome preset | Concrete result | | ----------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Review recent matching posts without changing a checkpoint | `snapshot` | Up to the run limit from the selected lookback; oldest first within each query; query groups follow the input order | | Continue one monitor and receive only unseen matching posts | `delta` | Stable `NEW` records after the saved checkpoint; the first successful run returns the current lookback and creates that checkpoint | ### โšก Quick start โ€” after your cookies are ready > **Pricing activation:** the new pay-per-event plan is scheduled for **August 24, 2026 at 00:15 UTC**. Before it becomes the current plan, a live run can stop safely with `PPE_REQUIRED_FOR_LIVE_MODE`. Check the Actor's live **Pricing** tab before running. 1. Sign in to [x.com](https://x.com/) with a dedicated secondary account. 2. Retrieve its `ct0` and `auth_token` cookie values using the detailed instructions in **๐Ÿ” Connect your X session** below. 3. Paste this exact one-line format into **๐Ÿ” X session cookies**: ```text ct0=PASTE_CT0_VALUE; auth_token=PASTE_AUTH_TOKEN_VALUE ``` 4. Choose **โšก New mentions only** for recurring monitoring, or **๐Ÿ“ธ Recent snapshot** for a one-off export. 5. Replace `@YourBrand` in **๐Ÿ”Ž Brands or searches**. Add up to 25 searches. 6. Keep **โœ… Strict visible match** unless you deliberately need X search operators such as `OR`, `from:`, `lang:`, or `filter:`. 7. Give the monitor a stable name such as `yourbrand-en`. Reuse that exact name for later delta runs. 8. Choose the first-run lookback in hours or days, set the maximum number of mentions, and click **Start**. 9. Open the run's **Dataset** tab to inspect, download, or integrate the returned records. ### Copy to your AI assistant Actor reference: `kazkn/x-mentions-delta-monitor`. Load both secrets from protected environment variables. Never paste or share the real token or X cookies in an AI prompt, chat, source file, screenshot, README, or support message. ```bash : "${APIFY_TOKEN:?Set APIFY_TOKEN in your shell environment}" : "${X_SESSION_COOKIES:?Set X_SESSION_COOKIES in your shell environment}" test -n "${X_SESSION_COOKIES}" export APIFY_TOKEN X_SESSION_COOKIES RUN_RESPONSE="$( curl -fsS --request POST \ "https://api.apify.com/v2/acts/kazkn~x-mentions-delta-monitor/runs?waitForFinish=120" \ --header "Authorization: Bearer ${APIFY_TOKEN}" \ --header "Content-Type: application/json" \ --data "$(jq -nc '{ preset: "delta", queries: ["@YourBrand"], matchMode: "strict", xSessionCookies: env.X_SESSION_COOKIES, monitorId: "yourbrand-en", maxResults: 100, lookbackValue: 7, lookbackUnit: "days" }')" )" RUN_ID="$(jq -r '.data.id' <<<"${RUN_RESPONSE}")" DATASET_ID="$(jq -r '.data.defaultDatasetId' <<<"${RUN_RESPONSE}")" test -n "${RUN_ID}" && test -n "${DATASET_ID}" curl -fsS \ "https://api.apify.com/v2/datasets/${DATASET_ID}/items?clean=true&format=json" \ --header "Authorization: Bearer ${APIFY_TOKEN}" ``` The assistant can change the non-secret searches, monitor name, lookback, or result limit. Keep `APIFY_TOKEN` and `X_SESSION_COOKIES` outside the prompt and inject them only from your local environment or secret manager. ### ๐ŸŽ What you get - A flat Dataset row for every accepted query/post combination. - Stable IDs suitable for database upserts and downstream deduplication. - Visible match evidence in strict mode: where the term matched and the relevant text. - A persistent named checkpoint for recurring delta runs. - Explicit failures for expired cookies, rate limits, timeouts, invalid responses, or an oversized unseen backlog. - JSON, CSV, Excel, XML, RSS, and JSONL exports through Apify Dataset tools. This Actor does **not** provide sentiment analysis, engagement metrics, profiles, media downloads, complete X history, guaranteed completeness, or guaranteed delivery latency. Results are limited to posts returned by authenticated X search and visible to the connected account. ### ๐Ÿ” Connect your X session #### What these cookies are After you sign in to X, the browser stores session cookies. This Actor needs two of them: - `auth_token` identifies the signed-in X session. - `ct0` is the CSRF value used with that session. They are **not** your X password, an X API key, a Bearer Token, or your Apify API token. Treat both values like a password: anyone who obtains a valid session cookie may be able to use that session. Use a dedicated secondary X account with only the access needed for monitoring. The account determines what search can return. Sessions can expire or be revoked, and X may rate-limit or restrict automated sessions. #### Chrome or Microsoft Edge 1. Open in the desktop browser and confirm that you are signed in to the intended account. If X shows **Log in**, log in before continuing. 2. Open Developer Tools: - Windows or Linux: press `F12` or `Ctrl+Shift+I`. - macOS: press `Option+Command+I`. 3. Select the **Application** tab. If it is hidden, click the `ยป` overflow button and choose **Application**. 4. In the left sidebar, open **Application โ†’ Storage โ†’ Cookies**. 5. Select `https://x.com`. A table of cookies appears. 6. Use the filter box to search for `ct0`. 7. Find the row whose **Name** is exactly `ct0`. Double-click its **Value** cell and copy the complete value. Copy the value onlyโ€”not the domain, path, expiry date, or the word `ct0`. 8. Search for `auth_token`. Find the exact row and copy its complete **Value** cell. 9. Keep Developer Tools private. Do not include either value in a screenshot, support message, source file, or log. #### Firefox 1. Sign in at in Firefox. 2. Open Developer Tools with `F12`, `Ctrl+Shift+I` on Windows/Linux, or `Option+Command+I` on macOS. 3. Select **Storage**. If it is hidden, open the `ยป` overflow menu. 4. In the left sidebar, expand **Cookies** and select `https://x.com`. 5. Locate the rows named exactly `ct0` and `auth_token`. 6. For each row, copy only the complete value from the **Value** column. #### Safari on macOS 1. In Safari, open **Safari โ†’ Settings โ†’ Advanced** and enable the option that shows features for web developers if the **Develop** menu is not already visible. 2. Sign in at . 3. Open **Develop โ†’ Show Web Inspector**. 4. Select the **Storage** tab, then **Cookies**, then the `x.com` entry. 5. Locate `ct0` and `auth_token` and copy only their complete **Value** cells. Browser labels can move between versions. The goal is always the cookie table for the signed-in `x.com` page, not the browser's general **Privacy** or **Clear browsing data** screen. #### Exactly what to paste Paste the two names and their copied values into the single **๐Ÿ” X session cookies** field, on one line, separated by a semicolon and a space: ```text ct0=PASTE_CT0_VALUE; auth_token=PASTE_AUTH_TOKEN_VALUE ``` Replace `PASTE_CT0_VALUE` and `PASTE_AUTH_TOKEN_VALUE`; do not type the placeholder text literally. A correctly shaped example looks like this, but these fake values will not work: ```text ct0=abc123example; auth_token=def456example ``` Do not paste: - JSON, a browser cookie export, or an array of cookie objects. - A leading `Cookie:` label or request headers. - Quotes, braces, line breaks, or Markdown backticks. - Attributes such as `Domain`, `Path`, `Expires`, `HttpOnly`, `Secure`, `SameSite`, or `Size`. - Your email, username, password, X Bearer Token, X API key, or Apify token. Extra cookies are unnecessary. Even if your browser shows dozens of rows, copy only `ct0` and `auth_token`. The field is a masked [Apify secret input](https://docs.apify.com/actors/development/actor-definition/input-schema/secret-input), so Apify encrypts it before persistence and decrypts it only for the Actor run. You must still keep the cookies private. If you accidentally disclose them, sign out that X session or revoke it under X **Settings and privacy โ†’ Security and account access โ†’ Apps and sessions โ†’ Sessions**, then sign in again and copy fresh values. If a run reports that the session is invalid or expired, repeat the sign-in and copy steps before retrying. ### ๐ŸŽฏ Input reference | Input field | What to enter | Default and limits | Example | | ------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | **๐ŸŽฏ Monitoring result** | **Recent snapshot** for a one-off lookback, or **New mentions only** for a persistent feed | Default: New mentions only | New mentions only | | **๐Ÿ”Ž Brands or searches** | Handles, brand names, hashtags, phrases, or advanced X search queries | 1โ€“25 searches; each up to 512 characters; strict mode allows at most 32 positive terms and 256 positive-term characters; duplicates ignoring case are rejected | `@Vinted`, `Vinted`, `#Vinted` | | **โœ… Match precision** | Strict visible proof or full X search semantics | Default: Strict visible match | Strict visible match | | **๐Ÿ” X session cookies** | The two cookie values in the exact one-line format documented above | Required for live runs; maximum 16,384 characters | `ct0=VALUE; auth_token=VALUE` | | **๐Ÿ—‚ Monitor name** | A stable checkpoint name; reuse it only for runs that belong to the same feed | 1โ€“64 ASCII letters, numbers, spaces, `_`, or `-`; must start with a letter or number | `vinted-en` | | **๐Ÿ“ฆ Maximum mentions** | Maximum Dataset records across every search in this runโ€”not per search | 1โ€“1,000; default 100 | `100` | | **๐Ÿ•’ First-run lookback** | Number used for the first delta run or any snapshot | 1โ€“168 hours or 1โ€“7 days; default 7 | `7` | | **โฑ Lookback unit** | Hours for a short window or days for an easier multi-day window | Hours or Days; default Days | Days | Programmatic inputs created before the hours/days selector may still use the legacy `lookbackHours` field. New integrations should use `lookbackValue` plus `lookbackUnit`. If both new lookback fields are omitted through the API, the compatibility default is 24 hours. The unit changes the valid range: values from 8 through 168 are hours-only. When **Days** is selected, enter a value from 1 through 7; the Actor rejects a larger value with `INPUT_LOOKBACK_INVALID`. ### ๐Ÿ”Ž Build useful searches Start with simple searches in strict mode: ```json { "queries": ["@YourBrand", "Your Brand", "#YourBrand"] } ``` Useful query types include: - Handle mention: `@YourBrand` - Brand or product keyword: `Vinted` - Hashtag: `#Vinted` - Phrase sent to X search: `"second hand fashion"` - Exclusion: `Vinted -jobs` - Language or author filter: `Vinted lang:en` or `from:username` - Alternatives: `Vinted OR Depop` X can change search behavior, and search operators do not guarantee a result. Test a new query directly on X first. For advanced operators, select **๐Ÿงฉ X search semantics** so the Actor does not reinterpret X's decision locally. #### โœ… Strict visible match versus ๐Ÿงฉ X search semantics | Mode | Acceptance rule | Best for | Important limitation | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | **Strict visible match** | Every positive search term must be visible in one checked context: post text, quoted-post text, reposted-post text, or the queried author's username for a pure `@handle` search | Brand monitoring where every row needs human-readable evidence | Operators and negative terms are ignored during local evidence checking; an `OR` query can therefore be too restrictive | | **X search semantics** | Keeps candidates returned by X for the complete query | `OR`, `from:`, `lang:`, `filter:`, exclusions, and other advanced syntax | `matchedIn` is `x_search_context`; this proves X returned the candidate, not which visible term caused the match | For the cleanest brand-mention Dataset, use one simple brand, handle, or hashtag per search with strict mode. Use X search semantics only when preserving X's own advanced query evaluation matters more than local visible-term proof. ### ๐Ÿงญ How a run works 1. The Actor validates the input, normalizes searches, and rejects case-insensitive duplicates. 2. It parses the secret field and forwards only `ct0` and `auth_token` to the X search client. 3. It converts the chosen lookback to a start time and searches each query through the authenticated session. 4. In strict mode, it removes candidates without visible evidence. In X search semantics mode, it preserves X's returned candidates. 5. It normalizes fields and creates `mentionId` from the X post ID plus the normalized query. 6. It deduplicates records and applies the global result limit. Results are oldest first within each query; query groups follow the input order. 7. It writes records to the run's Dataset. 8. For a successful delta run, it advances the named checkpoint only after Dataset storage succeeds. If the same post matches two different queries, the Actor can emit two records because the query is part of `mentionId`. This keeps attribution to each monitor search explicit. ### ๐Ÿ—‚ Snapshots, delta monitoring, and schedules #### Recent snapshot A snapshot searches the selected lookback but does not use or advance a checkpoint. It is useful for testing queries, collecting a recent sample, or making a one-off export. When more valid candidates exist than the result limit, the Dataset contains only the bounded result set and the run log records the truncation diagnostic. #### New mentions only The first successful delta run for a monitor name searches the selected lookback, emits its accepted records, and saves a persistent checkpoint. Later successful runs with the same normalized monitor name request newer posts and suppress stable mention IDs already recorded. The Actor fails with `X_SEARCH_BACKLOG_LIMIT` instead of advancing the checkpoint when an unseen backlog exceeds the bounded 1,000-post scan. This protects the feed from silently jumping past unprocessed posts. #### Scheduling safely Use an [Apify schedule](https://docs.apify.com/actors/running/schedules) to run the delta preset repeatedly. Pick an interval that normally keeps the unseen volume below the scan bound. The Actor permits only one active run per monitor name; an overlapping run stops with `MONITOR_ALREADY_RUNNING` before it searches or bills mention rows. A crash between Dataset delivery and checkpoint storage can still replay a row because those operations are not one transaction. Downstream consumers should always upsert or deduplicate on `mentionId`. Use a different monitor name when you need an independent checkpointโ€”for example, `brand-en`, `brand-fr`, and `competitors`. ### ๐Ÿ“ฆ Dataset output Every row has the same flat structure: ```json { "eventType": "NEW", "mentionId": "ea52f50b...", "tweetId": "1820000000000000000", "query": "@YourBrand", "text": "Trying @YourBrand today.", "matchedIn": "post_text", "matchedText": "Trying @YourBrand today.", "authorUsername": "example_user", "createdAt": "2026-08-06T09:00:00.000Z", "url": "https://x.com/example_user/status/1820000000000000000", "collectedAt": "2026-08-06T10:00:00.000Z" } ``` | Field | Meaning | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `eventType` | Always `NEW`; in a snapshot it means a normalized event returned by that run, not a persistent delta claim | | `mentionId` | SHA-256 identity derived from the X post ID and normalized query; use as the idempotency key | | `tweetId` | Original X post ID | | `query` | Normalized search that produced this record | | `text` | Post text returned by X search | | `matchedIn` | `post_text`, `quoted_post_text`, `retweeted_post_text`, `author_username`, or `x_search_context` | | `matchedText` | Visible evidence used by strict mode, or the returned post text in X search semantics mode | | `authorUsername` | Author username when X returns it; otherwise `null` | | `createdAt` | Publication timestamp returned by X | | `url` | Direct `x.com` post URL | | `collectedAt` | Timestamp of this monitoring cycle | The Dataset belongs to the run, and its retention follows your current Apify plan and storage settings. Export important records or use an appropriately configured named storage when you need a longer retention period. The named checkpoint is separate from the Dataset. ### ๐Ÿ”Œ API, exports, webhooks, and integrations #### Start a run through the API Use the complete command in **Copy to your AI assistant** above. It calls the exact Actor reference, keeps both secrets in environment variables, waits for the run, captures its Dataset ID, and downloads the results. For production automation, inject secrets from a protected secret manager or a private Apify Task rather than typing their values into a shared terminal. #### Download Dataset items Copy the Dataset ID from the run and request a supported format such as `json`, `csv`, `xlsx`, `xml`, `rss`, or `jsonl`: ```bash curl "https://api.apify.com/v2/datasets//items?format=json&clean=true" \ --header "Authorization: Bearer ${APIFY_TOKEN}" ``` You can also use the Dataset tab's **Export results** button without writing code. #### Trigger downstream workflows Configure an [Apify webhook](https://docs.apify.com/integrations/webhooks) for successful Actor runs, then let the receiving service fetch the Dataset items. Make, Zapier, n8n, Google Sheets, databases, and custom APIs should deduplicate on `mentionId`. A successful run can legitimately contain zero rows when authenticated X search returns no candidate for the query and lookback. ### ๐Ÿ’ณ Pricing and subscription discounts This Actor uses **pay per event** pricing with three simple units: the run start, each configured search that completes successfully, and each accepted query/post match row written to the Dataset. A successful search check is billable even when it finds zero accepted mentions because the Actor still authenticated, searched X, and verified the monitoring window. The Actor submits the search-check count only after every executed search and all returned records pass validation. If any executed search fails authentication, network, timeout, upstream processing, or response validation, the cycle submits no search-check events. **Platform usage is included** in the event prices: no separate platform-usage line is added to your event bill, and the creator covers those platform costs from the event revenue. Reading, exporting, or retaining Dataset data after the run can still consume the normal storage and transfer usage of your Apify account. The plan below is scheduled to start on **August 24, 2026 at 00:15 UTC**; before that time, the current price can differ. The Actor's live **Pricing** tab is always the final source of truth. | Apify plan | Pricing tier | Run start | Successful search checked | New mention delivered | Discount vs Free | | ------------------- | ------------ | --------: | ------------------------: | --------------------: | ---------------: | | Free | FREE | $0.000500 | $0.005000 | $2.50 / 1,000 | โ€” | | Starter | BRONZE | $0.000450 | $0.004500 | $2.25 / 1,000 | 10% | | Scale | SILVER | $0.000400 | $0.004000 | $2.00 / 1,000 | 20% | | Business | GOLD | $0.000325 | $0.003250 | $1.625 / 1,000 | 35% | | Enterprise Platinum | PLATINUM | $0.000250 | $0.002500 | $1.25 / 1,000 | 50% | | Enterprise Diamond | DIAMOND | $0.000200 | $0.002000 | $1.00 / 1,000 | 60% | #### What is charged? - **Monitor run started** โ€” one automatic start event at the price for your Apify tier. With the Actor's fixed 256 MB memory allocation, one run creates one start event. - **Successful search checked** โ€” one charge after each configured X search completes successfully. A legitimate zero-result search is charged; a search that fails before completion is not. - **New mention delivered** โ€” one charge per Dataset row. The billable unit is one accepted query/post pair, so one X post matching two configured searches can create two rows and two charges. - **No separate platform-usage surcharge** โ€” the user does not receive a second run-compute line; the creator covers those platform costs, while Dataset storage and transfer remain normal usage on the user's Apify account. - **No charge for suppressed duplicates** โ€” a delta run that finds only IDs already checkpointed produces no new mention event. In the rare crash window after Dataset delivery but before checkpoint storage, a replayed row can be charged again; its stable `mentionId` makes the replay detectable. - **No $0.01 minimum invoice** โ€” $0.01 is only the lowest maximum-charge limit a user can select for a run. #### Cost examples The exact formula is `run start + successful searches + delivered query/post rows`. These examples assume one run: | Scenario | Free | Starter | Scale | Business | Platinum | Diamond | | ----------------------- | --------: | --------: | --------: | --------: | --------: | --------: | | 1 search, 0 mentions | $0.005500 | $0.004950 | $0.004400 | $0.003575 | $0.002750 | $0.002200 | | 1 search, 10 mentions | $0.030500 | $0.027450 | $0.024400 | $0.019825 | $0.015250 | $0.012200 | | 1 search, 100 mentions | $0.255500 | $0.229950 | $0.204400 | $0.166075 | $0.127750 | $0.102200 | | 25 searches, 0 mentions | $0.125500 | $0.112950 | $0.100400 | $0.081575 | $0.062750 | $0.050200 | For one quiet search with no new mention on the Free tier, one daily run for 30 days costs about **$0.165**; one hourly run for 30 days costs about **$3.96**. Delivered mentions are then added at the price for your Apify tier. Before starting a broad monitor, set **Maximum charge per run** in Apify Console. The Actor first limits the number of searches to the available search-check budget. After those checks are charged, it limits Dataset delivery to the remaining mention budget and does not advance the delta checkpoint past rows that could not be delivered. ### ๐Ÿ›  Troubleshooting | Symptom or error | What it means | What to do | | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `X_SESSION_COOKIES_REQUIRED` | The secret field is empty for a live run | Retrieve both cookies and paste the exact one-line format | | `X_SESSION_COOKIES_INVALID` or `INPUT_X_SESSION_COOKIES_INVALID` | A value is missing, empty, duplicated, multiline, or malformed | Remove JSON, labels, attributes, quotes, and line breaks; paste only `ct0=VALUE; auth_token=VALUE` | | `X_SESSION_INVALID_OR_EXPIRED` | X rejected the session or it expired | Sign in again in the browser and copy fresh values for both cookies | | `X_SESSION_COOKIES_REJECTED` | The search client rejected the supplied cookie pair | Confirm the values came from the same currently signed-in `x.com` session | | `X_SESSION_VALIDATION_FAILED` | X returned no usable result for both the requested search and the control validation search | Confirm search works manually in that account, refresh the cookies, then retry | | `X_SEARCH_RATE_LIMITED` | X rate-limited the session | Stop retrying immediately, wait, and reduce run frequency or query volume | | `X_SEARCH_TIMEOUT` | Authenticated search did not finish before the Actor deadline | Retry later with fewer searches; repeated failures can indicate an upstream change | | `X_SEARCH_AUTH_OR_UPSTREAM_FAILED` | Authentication failed or X changed/responded unexpectedly | Refresh the session; if the problem persists, include the safe error code and run ID in supportโ€”not the cookies | | `X_SEARCH_RESPONSE_INVALID` | X returned a response the Actor could not validate | Retry once later and report the run ID if it persists | | `X_SEARCH_BACKLOG_LIMIT` | A delta feed has more than 1,000 unseen posts in the bounded scan | Run more frequently or split high-volume queries into separate monitor names; the checkpoint is not advanced | | `MONITOR_ALREADY_RUNNING` | Another run currently owns the same monitor-name lock | Let that run finish; do not retry concurrently | | `INPUT_LOOKBACK_INVALID` or legacy `INPUT_LOOKBACK_HOURS_INVALID` | The lookback is outside 1โ€“168 hours or 1โ€“7 days | Reduce the number or switch the unit; values from 8 through 168 are hours-only | | `PPE_EVENT_NOT_CONFIGURED`, `PPE_EVENT_SET_MISMATCH`, `PPE_DOUBLE_CHARGE_CONFIGURATION`, or `PPE_REQUIRED_FOR_LIVE_MODE` | The live Pricing event set is missing, inactive, or does not exactly match the Actor's billing contract | Stop the schedule and contact support with the run ID; no live mention search was started | | `INPUT_QUERY_COMPLEXITY_INVALID` | A strict-mode query contains too many positive terms for bounded local evidence matching | Simplify the query, split it into separate searches, or use X search semantics for advanced operators | | Run succeeds with zero rows | No accepted candidate was returned inside the lookback, or strict mode removed candidates without visible proof | Test the query on X, widen the lookback, try one simple query, then compare strict mode with X search semantics | | Unrelated-looking rows in X search semantics mode | Xโ€”not the Actor's strict verifierโ€”accepted the candidate | Switch to strict mode or simplify the query if every row must contain visible evidence | | Duplicate delivery downstream | A failure between Dataset and checkpoint writes replayed a record | Deduplicate or upsert on `mentionId` | Never send cookies in a support request. Share only the Apify run ID, safe error code, non-secret input fields, and whether manual X search worked in the same account. ### โ“ Frequently asked questions #### Do I need the paid X API? No paid X API is required. The Actor uses authenticated X search with the session cookies you provide. #### Do I enter my X password in the authentication field? No. Enter only `ct0=VALUE; auth_token=VALUE` in **๐Ÿ” X session cookies**. Never enter a password, email address, API key, or Bearer Token. #### Why are two cookie values in one field? The Actor validates one cookie header-shaped string and extracts the two required names. Both values must come from the same active browser session. #### Why did the first delta run return older posts? It must initialize the monitor from the selected lookback. Later successful runs with the same monitor name return only records beyond the saved checkpoint and suppress previously stored mention IDs. #### Does changing the monitor name reset the feed? Yes. Each normalized monitor name has its own checkpoint. Changing it starts an independent feed from the selected lookback. #### Can I monitor several brands in one run? Yes, up to 25 searches. The maximum-mentions limit is global across the run, so a high-volume early search can consume much of the limit. Separate important feeds when you need independent capacity and checkpoints. #### Why can the same X post appear more than once? If it matches different searches, each query/post pair receives its own `mentionId`. If the IDs are identical, treat the later row as a replay and deduplicate it. #### Can the Actor read protected posts? It can only receive what authenticated X search returns to the connected account. Do not assume that another accountโ€”or a signed-out visitorโ€”can see the same posts. #### Is the cookie stored in the Dataset or logs? The Actor does not write the cookie string to its Dataset or application logs. The input field is marked secret so Apify encrypts it before storing the run input. Avoid copying it into non-secret fields or external logs. #### How much does a run cost? The run cost is the tier-specific start event plus one tier-specific `query-checked` event for every search that completes successfully, plus one `mention-delivered` event for every accepted query/post row. On Free, that is $0.0005 per run, $0.005 per successful search, and $0.0025 per delivered row. Starter, Scale, Business, Platinum, and Diamond receive the discounts shown in the pricing table. Check the Actor's live **Pricing** tab before starting a run because that surface is the final source of truth. ### KazKN Monitoring & Intelligence Suite [![KazKN Monitoring and Intelligence Suite โ€” social, commerce, and marketplace signals](docs/assets/kazkn-monitoring-intelligence-suite.svg)](https://apify.com/kazkn)
X Mentions Delta Monitor logo
X Mentions Delta Monitor
๐Ÿ”ต You are here
New, deduplicated X mentions with stable IDs and visible match evidence in strict mode. 		Zalo Member Profile Exporter logo
Zalo Exporter
Export visible groups, members, contacts, profiles, or bounded chat history. 		Shopify Apps Spy logo
Shopify Apps Spy
Detect Shopify apps and export product, review, and catalog intelligence. 		Vinted Smart Scraper logo
Vinted Smart Scraper
Compare cross-country prices and monitor resale opportunities across markets. 		Vestiaire Collective Smart Scraper logo
Vestiaire Collective Scraper
Collect live and sold luxury listings with seller and price intelligence.
### ๐Ÿ”’ Responsible operation - Use an account and data access you control. - Keep session cookies out of datasets, logs, screenshots, repositories, and support messages. - Prefer a dedicated account, conservative schedules, bounded queries, and non-overlapping runs. - Rotate the session immediately if a cookie may have been exposed. - Build downstream workflows that tolerate replay and deduplicate on `mentionId`. This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by X Corp. X search behavior and browser interfaces can change. # Actor input Schema ## `preset` (type: `string`): Recent snapshot returns up to your result limit without draining the full backlog. New mentions only emits records not seen by earlier successful runs. ## `queries` (type: `array`): Add 1โ€“25 X handles, brand names, hashtags, phrases, or advanced X search queries. Use one simple search per row for the clearest strict-match evidence. Example: @YourBrand. ## `matchMode` (type: `string`): Strict visible match keeps only posts where every positive search term is visible in the post, quoted post, repost, or queried author. X search semantics preserves advanced X matching and labels results whose matching context is not visible. ## `xSessionCookies` (type: `string`): Required for live runs. Paste exactly one line: ct0=PASTE\_CT0\_VALUE; auth\_token=PASTE\_AUTH\_TOKEN\_VALUE. Copy only the Value cells from your signed-in browser's x.com cookie tableโ€”no JSON, Cookie: prefix, quotes, attributes, password, API key, or line breaks. Use a dedicated secondary account because sessions can expire or be restricted. ## `monitorId` (type: `string`): Runs with the same monitor name share one persistent checkpoint. Use a different name for an independent feed. ## `maxResults` (type: `integer`): Maximum normalized mention records across all searches in this run. ## `lookbackValue` (type: `integer`): How far back the first run or recent snapshot searches. Use up to 168 hours or 7 days. ## `lookbackUnit` (type: `string`): Choose hours for short monitoring windows or days for easier multi-day searches. ## `lookbackHours` (type: `integer`): Hidden compatibility field for saved inputs created before lookback units were available. ## `sourceMode` (type: `string`): Internal private-build canary switch. Live is mandatory for user runs. ## `fixtureScenario` (type: `string`): Internal deterministic scenario for zero-spend private canaries. ## Actor input object example ```json { "preset": "delta", "queries": [ "@YourBrand" ], "matchMode": "strict", "monitorId": "default", "maxResults": 100, "lookbackValue": 7, "lookbackUnit": "days", "sourceMode": "live", "fixtureScenario": "baseline" } ``` # Actor output Schema ## `mentions` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("kazkn/x-mentions-delta-monitor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("kazkn/x-mentions-delta-monitor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call kazkn/x-mentions-delta-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,kazkn/x-mentions-delta-monitor" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/PydwZNm405SifBARu/builds/hga5uTNlaQk0eha30/openapi.json