Monitors
Twitter Keyword Monitor Status & Query Checks
Get one keyword monitor’s X query, tracked event types, active state, polling interval, creation time, and latest event checkpoint. See request fields.
- 200
- 400
- 401
- 404
- 429
GET
Twitter Keyword Monitor Status & Query Checks
Inspect One Twitter Keyword Monitor
Use this route when a workflow already stores one keyword monitor ID. It returns the exact X search query, tracked tweet events, active state, creation time, and next billing checkpoint. Use the list route when the ID is unknown. Checkquery before routing new matches. It preserves the Twitter keyword
search that created the monitor. Check eventTypes before assuming replies,
quotes, reposts, or other tweet events are enabled.
Store
id, query, eventTypes, isActive, and nextBillingAt together.
Pass the same monitor ID to event filters, updates, deletion, and webhook
workflows. This keeps every Twitter monitor handoff tied to one tracked search.
Use this status check before pausing or editing a monitor. A successful read
does not prove a matching tweet exists. Read the events endpoint for captured
tweets, then open one event for its complete payload.
Free - does not consume credits
keyword_monitor_id, query, event_types,
is_active, next_billing_at, update_endpoint, delete_endpoint,
events_endpoint, event_detail_endpoint_pattern, webhooks_endpoint, and
deliveries_endpoint_pattern before changing filters, pausing alerts, or
reconciling webhooks.
State handoff
UseGET /monitors/keywords/{id} before changing routing, billing checks, or
alert state for one keyword monitor. The endpoint returns the current stored
monitor for your account only; deleted or cross-account IDs return 404.
Current Filter
Treat
query and eventTypes as the active matching contract. Mirror
eventTypes into List Webhooks before
relying on signed alerts.Active State
Use
isActive to decide whether the monitor should poll and bill. Use
Update Keyword Monitor to pause or
resume it.Billing Check
Read
nextBillingAt before credit alerts, budget checks, or account
handoffs. Paused monitors stay visible but do not add hourly monitor burn.Event Join
Use
id as keywordMonitorId with
List Events to reconcile stored events and
webhook deliveries for this query. Use
Get Event for one event’s full payload.Delivery Audit
Use List Deliveries when webhook
delivery evidence must be retained. Join delivery
streamEventId to event
IDs. Do not use x_event_id as the delivery join key.Delete Path
Use Delete Keyword Monitor only
when the query should stop permanently. Export event and delivery evidence
first when support or audit workflows need history.
Verify One Alert Before Incident Review
Inspect one stored monitor before investigating a missed or unexpected alert. Start with the monitor ID recorded by the alerting system. A list response can hide which row the workflow actually used. Compare the returnedquery with the intended Twitter search expression.
Check capitalization, quoted phrases, exclusions, and operators. Store the
returned value as evidence. Do not reconstruct it from a dashboard label.
Next, compare eventTypes with the event under review. A monitor configured
only for tweet.new cannot explain an expected profile-change alert. Update
the filter only after recording its current value.
Read isActive before examining an empty event window. A paused monitor stays
available through this endpoint. It does not create future matching events.
Check nextBillingAt when the monitor should be active.
Use the returned ID to query stored events. Keep these outcomes separate:
- The monitor exists, but its query does not match the expected tweet.
- The query matches, but the required event type is absent.
- The event type exists, but the monitor is paused.
- The monitor is active, but no stored event matches the review window.
- A stored event exists, but its webhook delivery needs inspection.
streamEventId from delivery records. This separates search
matching from notification transport.
Finish with a compact incident note. Record the monitor ID, exact query,
active state, event types, event ID, and delivery result. That record lets
another operator repeat the check without listing every monitor.
Diagnose One Keyword Monitor
Start with the returned monitor ID, query, event types, and active state. ChecknextBillingAt and remaining credits before investigating a missing alert.
Run the exact query through tweet search. Relevant results confirm query coverage, not webhook delivery.
Inspect stored events by keywordMonitorId. Inspect delivery records by webhook ID. Keep streamEventId separate from each delivery ID.
Do not edit the monitor during diagnosis. Capture its previous state before any approved change.
Prove a Keyword Alert With Stored Evidence
Build one evidence chain for the alert under review. Start with this endpoint’s monitor response. Preserve its ID, exact query, active state, and event types. Run the exact query through Tweet Search. Save matching Tweet IDs and creation times. A search match proves query coverage. It does not prove that a monitor stored an event. Next, list stored events for the same keyword monitor ID. Match the expected Tweet ID when the event payload exposes it. Preserve the event ID and event timestamp. An event proves monitor ingestion. It does not prove webhook delivery. Finally, inspect deliveries for the subscribed webhook. Join each delivery’sstreamEventId to the stored event ID. Record its status and attempt time. A
delivery record proves notification handling.
Keep three outcomes separate:
- Search found the tweet, but no monitor event exists.
- A monitor event exists, but no delivery references it.
- A delivery exists, but the receiving application rejected it.
Distinguish Configuration Drift From Missing Tweets
Compare the returned query with the approved query character by character. Check quoted phrases, exclusions, hashtags, usernames, and search operators. One missing operator can change every matched tweet. CompareeventTypes with the approved event scope. Keep the full returned
array. Do not summarize several values as a broad monitoring label.
Check isActive and nextBillingAt together. A stored monitor can remain
visible while paused. A future billing timestamp supports the next budget
review. Neither field proves that a specific tweet created an event.
Use Update Account Monitor only for account
monitors. Keyword monitors use their dedicated update route. Keep monitor types
separate when support tickets contain several IDs.
Path parameters
string
required
The unique keyword monitor ID. Returned when you create a keyword monitor or list keyword monitors.
Headers
string
required
Your API key. Session cookie authentication is also supported. Generate a key from the dashboard.
Response
200 OK
string
Unique keyword monitor ID.
string
Normalized X search query.
string[]
Subscribed event types.
boolean
Whether the monitor is currently active.
string
ISO 8601 creation timestamp.
string
Next hourly credit charge time for active monitor billing.
400 Invalid ID
401 Unauthenticated
404 Not Found
429 Rate Limited
Retry-After header before retrying.
- 200
- 400
- 401
- 404
- 429
Twitter Keyword Monitor Status & Query Checks