Monitoring Brand Mentions on Twitter

Collects all public tweets mentioning a brand, product, or keyword on Twitter/X within a date range. Groups by sentiment, surfaces top complaints and praise, and provides engagement totals.

Prerequisites

• APIFY_TOKEN environment variable set
• Optional: Apify MCP server installed

Inputs

Workflow

Progress:
- [ ] Step 1: Define brand terms and date range
- [ ] Step 2: Run tweet-scraper
- [ ] Step 3: Retrieve dataset
- [ ] Step 4: Classify sentiment (positive/negative/neutral)
- [ ] Step 5: Deliver structured report

Step 1: Clarify Parameters

Ask the user for:

• Brand terms — brand name, handle, product name, hashtag, and common misspellings. Build a list. Example: ["@Nike", "Nike", "#Nike", "Nike shoes"]
• Date range — e.g., "last 7 days" or specific dates
• Exclude retweets? (default: yes — filters noise)
• Min engagement (optional — e.g., tweets with ≥10 likes only)
• Language (default: all)

Step 2: Run tweet-scraper

Run once per major search term to maximize coverage. Combine results after.

Recommended — run_actor.js (handles waiting, output, and file saving automatically):

# Quick answer (prints table to chat)
node scripts/run_actor.js \
  --actor "apidojo~tweet-scraper" \
  --input '{"param": "value"}'

# Save as CSV
node scripts/run_actor.js \
  --actor "apidojo~tweet-scraper" \
  --input '{"param": "value"}' \
  --output YYYY-MM-DD_results.csv --format csv

# Save as JSON
node scripts/run_actor.js \
  --actor "apidojo~tweet-scraper" \
  --input '{"param": "value"}' \
  --output YYYY-MM-DD_results.json --format json

APIFY_TOKEN must be set in environment or .env file.

If Apify MCP is available:

Tool: apify:run-actor
Actor: "apidojo~tweet-scraper"
Input:
{
  "searchTerms": ["[BRAND_TERM]"],
  "maxItems": 500,
  "includeReplies": true,
  "tweetLanguage": "en",
  "since": "[YYYY-MM-DD]",
  "until": "[YYYY-MM-DD]"
}

If Apify MCP is not available:

curl -X POST \
  "https://api.apify.com/v2/acts/apidojo~tweet-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchTerms": ["[BRAND_TERM]"],
    "maxItems": 500,
    "includeReplies": true,
    "since": "[YYYY-MM-DD]",
    "until": "[YYYY-MM-DD]"
  }'

Run for each brand term in the list. Wait for SUCCEEDED, collect all results.

Step 3: Fetch and Merge Results

curl "https://api.apify.com/v2/actor-runs/$RUN_ID/dataset/items?token=$APIFY_TOKEN"

Merge datasets from all runs. Deduplicate by tweet id. Result: unified list of all mentions.

Step 4: Classify Sentiment

For each tweet's text field, apply a simple classification pass:

Positive signals: words like "love", "great", "amazing", "best", "recommend", "thank", "perfect" Negative signals: words like "hate", "awful", "broken", "scam", "worst", "never again", "disappointed", "avoid" Neutral: everything else (announcements, news, questions)

Group tweets into three buckets: Positive, Negative, Neutral.

Identify top 5 most-engaged negative tweets (these need the fastest response). Identify top 5 most-engaged positive tweets (retweet candidates / testimonial material).

Step 5: Format Report

Use the output template below.

Output Format

# Brand Mention Report: [BRAND]
Period: [START_DATE] – [END_DATE] | Total mentions: [N] | Analyzed: [DATE]

## Sentiment Summary
| Sentiment | Count | % of Total | Avg Engagement |
|-----------|-------|------------|----------------|
| Positive  | [N]   | [X%]       | [likes+RT avg] |
| Negative  | [N]   | [X%]       | [likes+RT avg] |
| Neutral   | [N]   | [X%]       | [likes+RT avg] |

## 🔴 Top Negative Mentions (Action Required)
1. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
2. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
3. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]

## 🟢 Top Positive Mentions (Amplify These)
1. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
2. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
3. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]

## Volume Over Time
[Day 1]: [N] mentions | [Day 2]: [N] mentions | [Day 3]: [N] mentions...

## Key Themes in Negative Mentions
- [Theme 1]: [N] tweets (e.g., "shipping delays")
- [Theme 2]: [N] tweets (e.g., "customer service")

## Key Themes in Positive Mentions
- [Theme 1]: [N] tweets
- [Theme 2]: [N] tweets

Troubleshooting

Too many results for popular brands: Increase minLikes filter to 5 or 10 to focus on influential mentions. Missing mentions: Twitter search API has ~7-10 day lookback limit for free tier. For historical data, reduce date range. Sentiment misclassification: Sarcasm is hard to catch with keyword matching — flag high-engagement tweets for manual review.