# twitr.sh X/Twitter Account & Keyword Monitor

> twitr.sh X/Twitter Account & Keyword Monitor is a paid API for AI agents from twitr.sh, paid per call via x402, $0.0264/call, status unknown (last checked 2026-10-12).

Creates or extends a real-time monitor on an X/Twitter account or keyword query, streaming tweet and profile-change events for a prepaid number of hours.

## Facts

- Endpoint: POST https://twitr.sh/api/tools/x_monitor?utm_source=zero.xyz
- Price: $0.0264/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-12
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/twitr-sh-x-twitter-account-keyword-monitor-a4c1e229
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_mBslV_DIjacYNnWSxnaXW

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability twitr-sh-x-twitter-account-keyword-monitor-a4c1e229 -d '<json body>'
```

Example prompt: Watch the @vercel Twitter account for new tweets and any profile changes for the next 24 hours — alert me to tweet.new and profile.bio.changed events as they happen.

## When to prefer this

Choose this endpoint when you need continuous, real-time surveillance of a specific X account or keyword query over a defined time window — especially when you want granular event filtering (new tweets, retweets, profile changes, media posts) without setting up your own Twitter developer credentials. Ideal for agents that need to react to live social signals programmatically, paid per session with no subscription.

## Known failure modes

- Invalid or suspended X username returns an error
- Search query exceeds 512 character limit
- Hours value outside 1–168 range is rejected
- Extending a non-existent or expired monitorId fails
- Insufficient USDC payment results in 402 rejection
- Unsupported eventType combinations (profile.* events on keyword monitors) may be silently filtered or error

## How this service works

Pay-per-call X/Twitter API for AI agents. Read tweets, search, monitor accounts in real time, and post — paid in USDC via x402. No signup, no API keys.

## Output

Returns a monitor object with a unique monitor ID, type (account or keyword), status (active), target, expiry timestamp, list of subscribed event types, total USD paid, hours purchased, remaining seconds, and URLs to poll events or manage the monitor. Also includes payment confirmation details via x402.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "type": {
   "enum": [
    "account",
    "keyword"
   ],
   "type": "string",
   "description": "Monitor kind (create). Inferred from username/query when omitted."
  },
  "hours": {
   "type": "integer",
   "maximum": 168,
   "minimum": 1,
   "description": "Prepaid hours to purchase (default 1)."
  },
  "query": {
   "type": "string",
   "maxLength": 512,
   "description": "X search query to monitor (create, type=keyword)."
  },
  "action": {
   "enum": [
    "create",
    "extend"
   ],
   "type": "string",
   "description": "Create a new monitor or extend an existing one."
  },
  "username": {
   "type": "string",
   "description": "X handle to monitor, without @ (create, type=account)."
  },
  "monitorId": {
   "type": "string",
   "description": "Monitor to extend (extend only)."
  },
  "eventTypes": {
   "type": "array",
   "items": {
    "enum": [
     "tweet.new",
     "tweet.reply",
     "tweet.retweet",
     "tweet.quote",
     "tweet.media",
     "tweet.link",
     "tweet.poll",
     "tweet.mention",
     "tweet.hashtag",
     "tweet.longform",
     "profile.avatar.changed",
     "profile.banner.changed",
     "profile.name.changed",
     "profile.username.changed",
     "profile.bio.changed",
     "profile.location.changed",
     "profile.url.changed",
     "profile.verified.changed",
     "profile.protected.changed",
     "profile.pinned_tweet.changed",
     "profile.unavailable.changed"
    ],
    "type": "string"
   },
   "description": "Event types to receive (default: all applicable). Post events (tweet.*) work for any monitor; profile-change events (profile.*.changed) apply to ACCOUNT monitors only."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "message": "Monitor active for 24 hours.",
  "monitor": {
   "type": "account",
   "status": "active",
   "target": "vercel",
   "expires_at": 1785000000000,
   "monitor_id": "mn_a1b2c3d4e5f6g7h8",
   "event_types": [
    "tweet.new"
   ],
   "paid_total_usd": "0.605100",
   "hours_purchased": 24,
   "remaining_seconds": 86400
  },
  "payment": {
   "amount": "0.605100",
   "currency": "USD",
   "protocol": "x402"
  },
  "events_url": "/api/monitors/mn_a1b2c3d4e5f6g7h8/events",
  "manage_url": "/api/monitors/mn_a1b2c3d4e5f6g7h8"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/twitr-sh-x-twitter-account-keyword-monitor-a4c1e229/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from twitr.sh](https://www.zero.xyz/host/twitr.sh/llms.txt)