X Feed Monitor

Real-time X/Twitter monitoring with cursor-based incremental sync and webhook notifications. Track keywords, hashtags, or @mentions via Grok's x_search API. Optional AI sentiment analysis. Cost-controlled. Ready for scheduling.

Features

• Search X/Twitter by keyword, hashtag, or @mention
• Engagement metrics: likes, retweets, replies, views
• Incremental sync with cursor persistence (only new posts each run)
• Webhook notifications on completion (Slack/Discord/Zapier)
• Cost controls: hard-cap USD spend or API call count
• Dry-run mode: preview cost without spending
• Optional sentiment and topic analysis
• Dataset output plus optional JSON/CSV export

Quick start

1. Get a free Grok API key at console.x.ai.
2. Run the actor with this input:

{
  "queries": ["@anthropic", "#AI"],
  "estimateOnly": true,
  "grokApiKey": "xai-..."
}

3. estimateOnly: true previews the cost without spending API credits. Remove it and rerun to collect posts.

Live monitoring workflow

The common use case is a self-updating feed:

1. Run once with persistState: true (the default). The actor saves a cursor to the key-value store.
2. Schedule the actor in Apify Console → Schedules at your chosen cadence (every 15 min, hourly, daily).
3. Set a webhook URL to receive a POST on every completion.

Each scheduled run fetches only new posts since the last run and pings the webhook.

Input

Queries and scope

• queries (array, required): strings or objects {q, label?, limit?}.
• maxResults (integer, 1-100, default 50): cap per query.
• maxPages (integer, 1-10, default 1): pagination limit.
• sinceId (string): only fetch posts newer than this ID.
• sinceMinutes (integer): only fetch posts from the last N minutes.
• includeReplies (boolean, default true): include replies.
• includeReposts (boolean, default true): include reposts.
• includeQuotes (boolean, default true): include quote posts.

Analysis

• mode (enum, default collect): collect, analyze, or both.
• analysisLevel (enum, default none): none, light, or full.
• includeMetrics (boolean, default true): include likes/retweets/replies/views.

Scheduling and state

• persistState (boolean, default true): save cursor between runs.
• stateKey (string): KV store namespace for cursor (marked secret to satisfy Apify's name-pattern scanner).
• dedupe (boolean, default true): remove duplicates within a run.

Output and cost controls

• outputFormat (enum, default dataset): dataset, json, or csv.
• estimateOnly (boolean, default false): preview cost without fetching.
• maxCostUsd (number): abort if projected cost exceeds this.
• maxApiCalls (integer): alternative hard cap.
• webhook (string, secret): URL to POST results on completion.
• grokApiKey (string, secret): xAI API key.

Output

Each post in the default dataset:

{
  "post_id": "1234567890",
  "author_handle": "anthropic",
  "text": "Claude 4 is now available.",
  "created_at": "2026-04-15T10:30:00Z",
  "url": "https://x.com/anthropic/status/1234567890",
  "metrics": {
    "likes": 42,
    "retweets": 10,
    "replies": 5,
    "views": 1500
  },
  "query": "@anthropic",
  "sentiment": "positive",
  "topics": ["product-launch"]
}

sentiment and topics are included only when analysisLevel is not none.

Webhook payload

If webhook is set, the actor POSTs this JSON after each run:

{
  "runId": "abc123",
  "completed_at": "2026-04-18T10:30:00Z",
  "summary": {
    "queries": 2,
    "total_posts": 47,
    "new_posts_since_last_run": 47,
    "estimated_cost_usd": 0.08,
    "api_calls": 3
  },
  "dataset_url": "https://api.apify.com/v2/datasets/..."
}

Examples

Brand monitoring

{
  "queries": ["@yourbrand", "\"your product\""],
  "mode": "both",
  "analysisLevel": "light",
  "persistState": true,
  "webhook": "https://hooks.slack.com/services/T00/B00/XXX"
}

Competitor tracking (daily digest)

{
  "queries": ["@competitor1", "@competitor2"],
  "maxResults": 100,
  "persistState": true,
  "sinceMinutes": 1440
}

Trend analysis (full analysis, cost-capped)

{
  "queries": ["#trending", "#breaking"],
  "mode": "analyze",
  "analysisLevel": "full",
  "maxResults": 100,
  "maxCostUsd": 1.00
}

Cost estimation

Grok x_search pricing is roughly $0.01-$0.03 per query at default maxResults=50.

• 5 queries, collect only: ~$0.06
• 5 queries, light analysis: ~$0.15
• 10 queries, full analysis: ~$0.75
• 50 queries, full analysis: ~$4.00

Use estimateOnly: true or maxCostUsd to cap spending.

Privacy and security

• grokApiKey, webhook, and stateKey are marked isSecret: true. Apify encrypts them at rest and redacts from run logs.
• Fetched posts are public X/Twitter content; no private data is collected.

Troubleshooting

• 401 Unauthorized: invalid or missing Grok key. Regenerate at console.x.ai and paste into grokApiKey.
• 429 Too Many Requests: reduce maxResults, maxPages, or query count.
• Webhook never fires: verify the URL with curl -X POST; confirm endpoint is active.
• Zero new posts after first run: cursor working as intended. Set persistState: false to re-fetch.

Changelog

• v1.3 (2026-04-18): stateKey marked isSecret to clear Apify name-pattern warning; README simplified.
• v1.2 (2026-04-18): webhook marked isSecret (signed URLs may contain auth tokens); expanded README.
• v1.0: initial release with collect, analyze, incremental sync, cost controls.

Resources

• xAI API Console - get a free Grok key
• Apify Schedules - automate runs
• Apify Webhooks - advanced routing