---
title: "Create Monitor"
method: POST
path: "/monitor"
tags: ["Monitoring"]
---

# Create Monitor

`POST /monitor`

## Request

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

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.

## Request body

- object
  - `handle` string, required: The X username to watch, without the @.
  - `webhook_ids` string[]: 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_filter` string: 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_replies` boolean: 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.

## Response `201`

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

- object
  - `id` string: The new monitor's id, used in the update/delete/health routes below.
  - `handle` string: The normalized (lowercased, @ stripped) handle being watched.
  - `subject` string: Internal query expression for this monitor, currently always from:<handle>.
  - `kind` string: Monitor type. Currently always "account".
  - `status` string: "active" or "paused".
  - `webhook_ids` string[], nullable: The restriction set passed at create, or null for the default (deliver to all).
  - `domain_filter` string, nullable: The normalized domain filter passed at create, or null if none was set (deliver every new post).
  - `include_replies` boolean: 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.
  - `tier` string: The wire-facing poll tier the monitor was created on: `standard` or `fast`. Defaults to `standard` when the create body omits it.
  - `poll_interval_ms` integer: Current poll interval in milliseconds. Not yet a published SLA; subject to change.
  - `poll_interval_note` string: Caveat text returned alongside the interval: it is NOT a published SLA and is subject to change.
  - `created_at` string: ISO 8601 creation timestamp.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: Not found
- `429`: Rate limited
- `5XX`: Server error

---

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