Skip to main content
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. Check query 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
The cURL, Node.js, Python, and Go examples convert the fetched keyword monitor into one state snapshot row. Store 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

Use GET /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 returned query 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.
Open the matching event before diagnosing webhook delivery. Then join its event ID with 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. Check nextBillingAt 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’s streamEventId 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.
Never report those outcomes as one generic alert failure. Each outcome needs a different correction. Query changes affect matching. Monitor state affects future event creation. Webhook work affects notification transport. Record the investigation window in UTC. Compare tweet, event, and delivery timestamps inside that window. Avoid using dashboard refresh time as evidence. Finish with one durable incident record. Include monitor ID, query, Tweet ID, event ID, webhook ID, and delivery result. Link every conclusion to a returned field. This makes another operator’s review repeatable.

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. Compare eventTypes 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

The provided monitor ID is not a valid format.

401 Unauthenticated

Missing or invalid API key.

404 Not Found

No keyword monitor exists with this ID, or it belongs to a different account.

429 Rate Limited

Too many requests. Wait for the Retry-After header before retrying.