---
title: "X/Twitter Monitor"
method: POST
path: "/api/tools/x_monitor"
tags: ["Intelligence"]
---

# X/Twitter Monitor

`POST /api/tools/x_monitor`

## Request

- Base URL: `https://twitr.sh`
- URL: `https://twitr.sh/api/tools/x_monitor`
- Auth: none declared. Required headers: `Idempotency-Key`

Watch an X/Twitter account or keyword query in real time: new tweets, replies, quotes, mentions, hashtags, and profile changes, delivered to your agent by free polling or HMAC-signed webhooks. Prepaid by the hour with a hard stop at expiry — no open-ended billing. The way to track a brand, competitor, or topic without re-polling paid reads.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `action` 'create' | 'extend', required: Create a new monitor or extend an existing one.
  - `type` 'account' | 'keyword': Monitor kind (create). Inferred from username/query when omitted.
  - `username` string: X handle to monitor, without @ (create, type=account).
  - `query` string: X search query to monitor (create, type=keyword).
  - `eventTypes` string[]: Event types to receive (default: all applicable). Post events (tweet.*) work for any monitor; profile-change events (profile.*.changed) apply to ACCOUNT monitors only.
  - `hours` integer: Prepaid hours to purchase (default 1).
  - `monitorId` string: Monitor to extend (extend only).

## Response `200`

Result dataset.

- object
  - `items` object[], required: Array of returned items. Shape varies per tool — see each tool's documentation.
  - `runId` string: Run ID for debugging/audit.
  - `duration` integer: Run duration in seconds.

## Other responses

- `201`: Monitor created — body carries {monitor, events_url, manage_url, extend}. Poll events_url (free, SIWX) or register a webhook at /api/webhooks.
- `202`: Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only).
- `400`: Bad request — missing resultsLimit or Idempotency-Key where required. Body is a Problem with `retryable:false` and a `hint`; never charged.
- `402`: Payment Required. Per-result reads require x402 upto on Base: authorize the maximum and pay only for delivered records, with a $0.0024 non-empty minimum and zero for empty results. Fixed-price operations may additionally offer exact x402 and MPP.
- `403`: Acting handle not connected to this wallet — connect it via /api/x-accounts/start first; never charged.
- `404`: Unknown tool path — GET /openapi.json for the valid list; never charged.
- `409`: Active-monitor cap reached — never charged.
- `410`: Extend target already expired — create a new monitor; never charged.
- `429`: Rate limited — `retryable:true`; retry unchanged after the Retry-After header; never charged.
- `500`: Unexpected handler error — inspect payment receipt before retrying.
- `502`: Upstream provider error — `retryable:true`; inspect payment receipt before retrying; prepaid operations may already be charged.
- `503`: Service capacity temporarily unavailable — `retryable:true`; retry later; never charged.

---

[API](https://skmtc.dev/twitr/apis/twitr-sh.md) · [All operations](https://skmtc.dev/twitr/apis/twitr-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/twitr/apis/twitr-sh/revisions/f6390fcee344?raw)