Monitoring

Create Monitor

Start watching an X account. Every new post from that account is delivered, HMAC-signed, to your registered webhook(s) on a shared poll interval. Free: monitor creation is account administration, not a metered read. Cost: Free per call.

post/monitor

Request

  • Base URL: https://api.twitterapis.com/twitter
  • URL: https://api.twitterapis.com/twitter/monitor
  • Auth: HTTP bearer

Request body

handlestring required

The X username to watch, without the @.

webhook_idsstring[]

Array of webhook ids (from POST /twitter/webhook) to restrict delivery to. Omit to deliver to every active webhook on the account, the default.

domain_filterstring

Optional. A bare hostname (example.com) or a full URL (https://example.com/blog) to restrict delivery to posts that link to that host or a subdomain of it. Normalized server-side: lowercased, scheme/path/query/fragment/leading www./trailing :port stripped. Omit for no filter (deliver every new post, the default). Rejected with 400 if what remains after normalization is not a valid hostname shape.

include_repliesboolean

Optional. true to deliver the account's replies as well as its own posts, which is the default and what every monitor has always done; false to hold replies back and deliver only the account's own posts. Must be a real boolean if provided: the string "false" and the number 0 are rejected with a 400 rather than coerced, because coercing them would quietly give you the opposite of what you typed and the wrong answer here is invisible, it looks exactly like the account not having posted. null is a 400 too; there is no clear-it state, since true already is the unrestricted value.

Example request

{
  "handle": "elonmusk",
  "webhook_ids": [],
  "domain_filter": "example.com"
}

Response

Watch an X account for new posts and push them to your webhook(s).

idstring

The new monitor's id, used in the update/delete/health routes below.

handlestring

The normalized (lowercased, @ stripped) handle being watched.

subjectstring

Internal query expression for this monitor, currently always from:<handle>.

kindstring

Monitor type. Currently always "account".

statusstring

"active" or "paused".

webhook_idsstring[] nullable

The restriction set passed at create, or null for the default (deliver to all).

domain_filterstring nullable

The normalized domain filter passed at create, or null if none was set (deliver every new post).

include_repliesboolean

Whether replies are delivered as well as top-level posts. Echoed back from what was actually stored, not from what was requested, so the caller can see the applied value.

tierstring

The wire-facing poll tier the monitor was created on: standard or fast. Defaults to standard when the create body omits it.

poll_interval_msinteger

Current poll interval in milliseconds. Not yet a published SLA; subject to change.

poll_interval_notestring

Caveat text returned alongside the interval: it is NOT a published SLA and is subject to change.

created_atstring

ISO 8601 creation timestamp.

Changes

No recorded changes to this operation across all 1 revision of this API.