X Monitors

Beta

Monitor X (Twitter) for new posts. Webclaw periodically polls a profile, search, list, or reply thread, matches new tweets against your filters, and notifies you via webhook when something matches. This is the X analog of URL watches.

Note

X monitors are a paid feature — free or lapsed accounts receive a 403. Maximum 50 monitors per user. Each check is billed at your plan rate (Starter 5, Growth 3, Pro 2, Scale 1 credits), whether automated or triggered manually.

Create a monitor

POST/v1/x/monitors

Create a new X monitor with a poll interval, filters, and an optional webhook.

json

{
  "kind": "profile",
  "target": "@webclaw",
  "name": "Webclaw posts",
  "interval_minutes": 15,
  "webhook_url": "https://hooks.example.com/webclaw",
  "include_retweets": true,
  "include_replies": true,
  "include_quotes": true,
  "min_faves": 0,
  "keyword": "launch",
  "lang": "en"
}

Parameters

Field	Type	Required	Description
`kind`	`string`	Yes	What to poll. One of `profile`, `search`, `list`, or `replies`.
`target`	`string`	Yes	Interpreted per `kind`: a handle (a leading `@` is stripped), a search query, a list id, or a tweet id.
`name`	`string`	No	Human-readable label for the monitor.
`interval_minutes`	`integer`	No	Poll interval in minutes (2–10080). Default: 15.
`webhook_url`	`string`	No	Discord, Slack, or generic webhook fired on new matches.
`include_retweets`	`boolean`	No	Match retweets. Default: `true`.
`include_replies`	`boolean`	No	Match replies. Default: `true`.
`include_quotes`	`boolean`	No	Match quote tweets. Default: `true`.
`min_faves`	`integer`	No	Minimum likes for a tweet to match. Default: 0.
`keyword`	`string`	No	Only match tweets containing this text.
`lang`	`string`	No	Only match tweets in this language code (e.g. `en`).

Response

A monitor object. The create response returns the core fields; the list and detail endpoints return the full object (see below).

json

{
  "id": "xmon_8f3a1b2c",
  "kind": "profile",
  "target": "webclaw",
  "name": "Webclaw posts",
  "interval_minutes": 15,
  "webhook_url": "https://hooks.example.com/webclaw",
  "active": true
}

Monitor kinds

Kind	Target	Polls
`profile`	Handle	New posts from an account.
`search`	Query	New tweets matching a search query.
`list`	List id	New tweets in a list timeline.
`replies`	Tweet id	New replies to a specific tweet.

List monitors

GET/v1/x/monitors

List all X monitors for the authenticated user.

json

// Query params: ?limit=20&offset=0
{
  "monitors": [
    {
      "id": "xmon_8f3a1b2c",
      "kind": "profile",
      "target": "webclaw",
      "name": "Webclaw posts",
      "interval_minutes": 15,
      "webhook_url": "https://hooks.example.com/webclaw",
      "active": true,
      "include_retweets": true,
      "include_replies": true,
      "include_quotes": true,
      "min_faves": 0,
      "keyword": "launch",
      "lang": "en",
      "last_checked_at": "2026-03-19T08:00:00Z",
      "last_matched_at": "2026-03-18T21:14:00Z",
      "created_at": "2026-03-10T14:22:00Z"
    }
  ]
}

Monitor details

GET/v1/x/monitors/{id}

Get a single monitor as a full monitor object.

Monitor object

Field	Type	Description
`id`	`string`	Unique monitor identifier.
`kind`	`string`	`profile`, `search`, `list`, or `replies`.
`target`	`string`	The handle, query, list id, or tweet id being polled.
`name`	`string`	Label for the monitor.
`interval_minutes`	`integer`	Poll interval in minutes.
`webhook_url`	`string \| null`	Webhook fired on new matches.
`active`	`boolean`	Whether the monitor is polling.
`include_retweets`	`boolean`	Whether retweets match.
`include_replies`	`boolean`	Whether replies match.
`include_quotes`	`boolean`	Whether quote tweets match.
`min_faves`	`integer`	Minimum likes to match.
`keyword`	`string \| null`	Required substring, if set.
`lang`	`string \| null`	Required language code, if set.
`last_checked_at`	`string \| null`	ISO 8601 timestamp of the most recent check.
`last_matched_at`	`string \| null`	ISO 8601 timestamp of the most recent match.
`created_at`	`string`	ISO 8601 timestamp the monitor was created.

Update a monitor

PATCH/v1/x/monitors/{id}

Update monitor settings. Only provided fields are changed.

json

{
  "name": "Updated Name",
  "interval_minutes": 60,
  "webhook_url": "https://hooks.example.com/new-endpoint",
  "active": false
}

json

{ "success": true }

Delete a monitor

DELETE/v1/x/monitors/{id}

Permanently remove a monitor.

json

{ "success": true }

Trigger manual check

POST/v1/x/monitors/{id}/check

Immediately run a check in the background. Billed at your plan rate (Starter 5, Growth 3, Pro 2, Scale 1 credits).

json

{ "status": "checking" }

Webhook payload

When a check finds new matching tweets and a webhook_url is configured, Webclaw sends a POST request with this payload. Discord and Slack webhook URLs receive native embed/text formatting instead.

json

{
  "event": "x.monitor.matched",
  "monitor_id": "xmon_8f3a1b2c",
  "kind": "profile",
  "target": "webclaw",
  "new_count": 1,
  "tweets": [
    {
      "id": "1770000000000000000",
      "screen_name": "webclaw",
      "text": "We just shipped X monitors.",
      "url": "https://x.com/webclaw/status/1770000000000000000",
      "created_at": "2026-03-19T15:30:00Z",
      "favorite_count": 42,
      "retweet_count": 7,
      "reply_count": 3,
      "lang": "en",
      "is_retweet": false,
      "is_reply": false,
      "is_quote": false
    }
  ],
  "checked_at": "2026-03-19T15:30:05Z"
}

SDK examples

Python

python

from webclaw import Webclaw

client = Webclaw(api_key="wc_...")

# Create a profile monitor
monitor = client.x.monitors.create(
    kind="profile",
    target="@webclaw",
    name="Webclaw posts",
    interval_minutes=15,
    webhook_url="https://hooks.example.com/webclaw"
)

# List all monitors
monitors = client.x.monitors.list()

# Trigger an immediate check
client.x.monitors.check(monitor.id)

TypeScript

typescript

import Webclaw from "@webclaw/sdk";

const client = new Webclaw({ apiKey: "wc_..." });

// Create a profile monitor
const monitor = await client.x.monitors.create({
  kind: "profile",
  target: "@webclaw",
  name: "Webclaw posts",
  intervalMinutes: 15,
  webhookUrl: "https://hooks.example.com/webclaw",
});

// List all monitors
const { monitors } = await client.x.monitors.list();

// Trigger an immediate check
await client.x.monitors.check(monitor.id);

cURL

bash

# Create a monitor
curl -X POST https://api.webclaw.io/v1/x/monitors \
  -H "Authorization: Bearer wc_..." \
  -H "Content-Type: application/json" \
  -d '{"kind": "profile", "target": "@webclaw", "interval_minutes": 15}'

# List monitors
curl https://api.webclaw.io/v1/x/monitors \
  -H "Authorization: Bearer wc_..."

# Trigger manual check
curl -X POST https://api.webclaw.io/v1/x/monitors/xmon_8f3a1b2c/check \
  -H "Authorization: Bearer wc_..."

Note

To page a full audience list instead of watching for new posts, use the X Audience endpoint.

X Monitors

Create a monitor

Parameters

Response

Monitor kinds

List monitors

Monitor details

Monitor object

Update a monitor

Delete a monitor

Trigger manual check

Webhook payload

SDK examples

Python

TypeScript

cURL

Ready to build? Start extracting.