Add Monitor

Start watching an X account. From this moment on, every new tweet is delivered to your webhook.

Each monitor counts as one slot against your plan limit, regardless of tier.

Headers

Request Body

You must supply exactly one of webhook_id or webhook_url. Sending both, or neither, returns 400.

Detection tiers

Both consume one plan slot. fast availability depends on your plan.

Notes

• Monitoring starts now. We record the account's newest tweet as a baseline and deliver only what comes after. No history is backfilled.
• userName is resolved to X's permanent numeric account ID. If the account later changes its handle, monitoring continues uninterrupted.
• include_replies: false means only the account's own posts and threads, with no replies to other people. Turn it on for full conversational coverage.
• You can only have one monitor per account. Adding one you already watch, active or paused, returns 409 ALREADY_MONITORED. Change it with Update monitor instead.
• Adding an account you previously removed reuses the original monitor rather than creating a duplicate. The response has reactivated: true, and it re-baselines, so tweets posted since you removed it are not replayed.
• Using webhook_url creates the webhook and the monitor in a single atomic operation. If either fails, neither is created.

What real-time monitoring is used for

The pattern is the same across most use cases: pick the accounts whose posts should trigger something, and let the tweet itself be the trigger.

• Market and trading signals, where a handful of accounts move prices and fast detection earns its keep.
• Brand and reputation monitoring, catching complaints and viral threads while they are still live.
• Competitor watch, for launches, pricing changes, and announcements.
• Lead routing, pushing tweets that show buying intent into a CRM or Slack channel.
• News and content pipelines, assembling a feed from curated reporters without polling any of them.

Detection frequency is the one decision worth thinking about. standard at around 15 seconds is right for nearly everything, because a content pipeline or an alert does not benefit from the extra 13 seconds. Reach for fast only where latency changes the outcome, since both tiers consume the same single plan slot either way.

Response (200)

{
  "monitor_id": "b7e2c910-4f38-4a5d-9c81-2e6a7f0d3b45",
  "target_user_id": "44196397",
  "userName": "elonmusk",
  "tier": "fast",
  "include_replies": false,
  "webhook_id": "8f14e45f-ceea-467a-9f2b-1c3d4e5f6a7b",
  "status": "active",
  "reactivated": false,
  "message": "Monitoring @elonmusk. New tweets from now on will be delivered to your webhook."
}

When webhook_url was used, the response also carries the new webhook's secret:

{
  "signing_secret": "whsec_9f2b1c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "note": "Store this secret now. It is shown only once."
}

Response Fields

Rate limit

20 requests per minute.

If you pass webhook_url to create a webhook inline, the request consumes two allowances: monitor-add and webhook-create (10/min). Whichever runs out first returns the 429. Passing an existing webhook_id instead consumes only the monitor-add allowance.

Limits use a fixed 60-second window and are shared across every API key on your account, so creating extra keys does not raise the ceiling. Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset; a 429 adds Retry-After. See rate limits for the full table.

Errors

Example

Using an existing webhook:

curl -X POST https://api.getxapi.com/twitter/monitor/add \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "elonmusk",
    "webhook_id": "8f14e45f-ceea-467a-9f2b-1c3d4e5f6a7b",
    "tier": "fast"
  }'

Creating the webhook inline:

curl -X POST https://api.getxapi.com/twitter/monitor/add \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "elonmusk",
    "webhook_url": "https://your-server.com/hooks/getxapi",
    "include_replies": true
  }'