Push new posts to your webhook with monitors
Create a monitor once and let the API deliver matching posts to your URL.
Polling an account every minute is the most expensive way to find out that something new was posted. A monitor inverts it: you declare the account and the filter once, and the API pushes matching posts to your webhook.
Create a monitor
curl -X POST 'https://api.skilltweet.com/v1/monitors' \
-H 'X-API-KEY: $AGENTTWEET_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"username": "openai",
"keywords": ["api", "launch"],
"webhook_url": "https://example.com/hooks/x",
"interval_minutes": 5
}'| Field | Constraints |
|---|---|
username | The X handle to watch, 1–15 characters, without the @ |
keywords | Optional filter, up to 10 terms of 1–24 characters; empty means every post |
webhook_url | Where matching posts are delivered; optional, monitors also work without it |
interval_minutes | Polling cadence, 1 to 1,440 minutes, default 5 |
One key owns its own monitors: GET /v1/monitors lists them, DELETE /v1/monitors/:id removes one.
What your endpoint receives
New posts are delivered as a JSON POST with content-type: application/json and the user agent AgentTweet-Monitor/1.0:
{
"event": "tweet.new",
"monitor_id": "…",
"username": "openai",
"delivered_at": "2026-11-10T09:15:00.000Z",
"tweets": [
{ "id": "…", "text": "…", "author": "…" }
]
}Two details worth knowing before you write the handler:
- The first cycle never fires the webhook. Otherwise creating a monitor would dump the account's whole recent history at you in one burst. Delivery starts from the second poll on, and only for posts that appeared in between.
- Delivery is best effort with a 10-second budget. Return any 2xx quickly and process asynchronously; if your endpoint is slow or down, that cycle is logged as a failed delivery rather than retried forever.
The posts in tweets are the same flat JSON you would get from /v1/tweets/search, so one handler covers both paths.
Filtering without code
keywords is matched server-side, so a monitor on a noisy account with three keywords costs the same as one without, while your endpoint only wakes up for posts that matter. Keep webhook_url empty when you would rather poll on your own schedule — GET /v1/monitors and the timeline endpoints cover that case.
Where to go next
- Token billing and top-up tiers for how normal API calls are charged.
- Make your first request for the envelope every endpoint shares.
- The API docs have the full monitor reference, including delivery records.