Twitter Keyword Monitor API & Real-time Tweet Alerts

{
  "id": "21",
  "query": "xquik OR \"x api\"",
  "eventTypes": [
    "tweet.new"
  ],
  "isActive": true,
  "createdAt": "2025-01-15T12:00:00Z",
  "nextBillingAt": "2025-01-15T12:00:00Z"
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "monitor_already_exists",
  "message": "Monitor already exists."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

POST

monitors

keywords

Twitter Keyword Monitor API & Real-time Tweet Alerts

curl --request POST \
  --url https://xquik.com/api/v1/monitors/keywords \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": "<string>",
  "eventTypes": [
    "<string>"
  ]
}
'

import requests

url = "https://xquik.com/api/v1/monitors/keywords"

payload = {
    "query": "<string>",
    "eventTypes": ["<string>"]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({query: '<string>', eventTypes: ['<string>']})
};

fetch('https://xquik.com/api/v1/monitors/keywords', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/monitors/keywords"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"eventTypes\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "query": "<string>",
  "eventTypes": [
    "<string>"
  ],
  "isActive": true,
  "createdAt": "<string>",
  "nextBillingAt": "<string>"
}

Create a Twitter keyword monitor when one search query needs continuous tweet checks. Track brand mentions, handles, hashtags, products, campaigns, replies, reposts, links, or media. Store its ID, query, event types, billing time, and webhook destinations.

Requires 22 available credits - active keyword monitors bill 21 credits per hour

Keyword monitors are unlimited. Active monitors check every 1 second. Webhook and event deliveries are included in active monitor billing.

curl -X POST https://xquik.com/api/v1/monitors/keywords \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "xquik api",
    "eventTypes": ["tweet.new"]
  }' |
  jq -c '{
    keyword_monitor_id: .id,
    query: .query,
    event_types: .eventTypes,
    is_active: .isActive,
    created_at: .createdAt,
    next_billing_at: .nextBillingAt,
    verify_endpoint: "/api/v1/monitors/keywords/\(.id)",
    update_endpoint: "/api/v1/monitors/keywords/\(.id)",
    delete_endpoint: "/api/v1/monitors/keywords/\(.id)",
    events_endpoint: "/api/v1/events?keywordMonitorId=\(.id)",
    event_detail_endpoint_pattern: "/api/v1/events/{event_id}",
    webhooks_endpoint: "/api/v1/webhooks",
    deliveries_endpoint_pattern: "/api/v1/webhooks/{webhook_id}/deliveries"
  }'

const response = await fetch("https://xquik.com/api/v1/monitors/keywords", {
  method: "POST",
  headers: {
    "x-api-key": "xq_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "xquik api",
    eventTypes: ["tweet.new"],
  }),
});
const monitor = await response.json();
const monitorState = {
  keyword_monitor_id: monitor.id,
  query: monitor.query,
  event_types: monitor.eventTypes,
  is_active: monitor.isActive,
  created_at: monitor.createdAt,
  next_billing_at: monitor.nextBillingAt,
  verify_endpoint: `/api/v1/monitors/keywords/${monitor.id}`,
  update_endpoint: `/api/v1/monitors/keywords/${monitor.id}`,
  delete_endpoint: `/api/v1/monitors/keywords/${monitor.id}`,
  events_endpoint: `/api/v1/events?keywordMonitorId=${monitor.id}`,
  event_detail_endpoint_pattern: "/api/v1/events/{event_id}",
  webhooks_endpoint: "/api/v1/webhooks",
  deliveries_endpoint_pattern: "/api/v1/webhooks/{webhook_id}/deliveries",
};
process.stdout.write(`${JSON.stringify(monitorState)}\n`);

import json
import requests

response = requests.post(
    "https://xquik.com/api/v1/monitors/keywords",
    headers={"x-api-key": "xq_YOUR_KEY_HERE"},
    json={"query": "xquik api", "eventTypes": ["tweet.new"]},
)
monitor = response.json()
monitor_state = {
    "keyword_monitor_id": monitor["id"],
    "query": monitor["query"],
    "event_types": monitor["eventTypes"],
    "is_active": monitor["isActive"],
    "created_at": monitor["createdAt"],
    "next_billing_at": monitor["nextBillingAt"],
    "verify_endpoint": f"/api/v1/monitors/keywords/{monitor['id']}",
    "update_endpoint": f"/api/v1/monitors/keywords/{monitor['id']}",
    "delete_endpoint": f"/api/v1/monitors/keywords/{monitor['id']}",
    "events_endpoint": f"/api/v1/events?keywordMonitorId={monitor['id']}",
    "event_detail_endpoint_pattern": "/api/v1/events/{event_id}",
    "webhooks_endpoint": "/api/v1/webhooks",
    "deliveries_endpoint_pattern": "/api/v1/webhooks/{webhook_id}/deliveries",
}
print(json.dumps(monitor_state))

The cURL, Node.js, and Python examples convert the created or reactivated keyword monitor into one state row. Store keyword_monitor_id, query, event_types, is_active, next_billing_at, verify_endpoint, update_endpoint, delete_endpoint, events_endpoint, event_detail_endpoint_pattern, webhooks_endpoint, and deliveries_endpoint_pattern before routing alerts.

Keyword Monitor Handoff

Use POST /monitors/keywords when a queue, CRM, warehouse, Slack alert, or agent needs 1-second checks for one X search query. Create the monitor first. Then create a signed webhook with POST /webhooks. Test it with POST /webhooks/{id}/test.

Monitor ID

Store id as keyword_monitor_id. Use Get Keyword Monitor to verify state, Update Keyword Monitor to pause or resume, and Delete Keyword Monitor only when the query should stop permanently.

Normalized Query

Store query; Xquik includes it on keyword monitor events and signed webhook payloads.

Event Filter

Store eventTypes; keep List Webhooks subscriptions aligned so expected tweets deliver.

Active State

Read isActive and nextBillingAt before enabling alerts or estimating hourly monitor burn.

Stored Event Join

Use monitorType: "keyword", keywordMonitorId, and query from List Events to join stored events back to the monitor. Use Get Event for one event’s full payload.

Webhook Delivery Join

Use deliveryId for receiver idempotency and List Deliveries for delivery audit rows. Join delivery streamEventId to event IDs. Do not use x_event_id as the delivery join key.

Active keyword monitors check every 1 second and cost 21 credits per active monitor-hour. Creation or reactivation requires 22 available credits. Pause with Update Keyword Monitor and { "isActive": false } when the alert should stop.

How Do I Monitor Twitter Keywords With an API?

Use one focused query for each alert purpose. First, write the exact words, phrases, handles, or hashtags requiring alerts. Then select the tweet event types that should reach downstream workers. Create the monitor and store its returned ID immediately. Next, connect a signed webhook for the selected event types. Send a signed test before accepting production alerts. Store each event before returning a successful receiver response. Use the event ID and delivery ID for separate idempotency checks. This workflow helps applications monitor Twitter keywords without maintaining a stream connection. The Twitter keyword monitor checks its stored query every second. Matching tweets become stored events and signed webhook deliveries. Use List Events when a webhook consumer needs recovery.

How Do I Choose Twitter Keywords to Monitor?

Start with terms that represent one operational decision. Support teams can watch product names, error phrases, or direct handles. Campaign teams can watch campaign hashtags and reply language. Developers can watch API names, integration phrases, or release mentions. Prefer an exact phrase when word order changes meaning. Use OR when any listed term should match. Use a space when every listed term must appear. Use a leading minus sign to exclude known noise. Group mixed OR conditions with parentheses. For example, monitor direct mentions with @xquik. Monitor a phrase with "x api". Combine related terms with (@xquik OR "xquik api"). Exclude reposts with -is:retweet when repost alerts add no value. Test the proposed query with Search Tweets first. Review returned tweets before enabling continuous keyword monitoring. Narrow irrelevant matches before paying for an active monitor. Never add undocumented operators merely to increase apparent coverage.

How Do I Track Twitter Mentions and Brand Keywords?

Include the exact handle when direct mentions require action. Add the brand name when plain-text mentions also matter. Add specific product names only when workers own those alerts. Keep unrelated brands in separate monitors and queues. Tracking mentions requires stable evidence from every matched tweet. Store the tweet ID, author ID, event type, query, and timestamp. Keep keywordMonitorId beside each stored event. This join shows which query matched the tweet. The selected query monitors conversations across public matching tweets. It does not calculate sentiment or brand reputation. It also cannot reveal private tweets or direct messages. Treat mentions of your brand as matched tweets, not inferred opinions.

When Should I Use Keyword Alerts, Tweet Search, or Account Monitoring?

Choose the surface that matches the required time range and scope.

Requirement	Use	Result
Continuous matches across many accounts	Keyword monitor	Stored matching tweet events and real time alerts.
Historical or on-demand query results	Search Tweets	One cursor-paginated tweet result set.
Selected changes from one known account	Create Account Monitor	Tweet and profile events from that username.

A focused Twitter monitoring tool should not mix these three scopes. Use Twitter search for backfill and investigation. Use an account monitor for one known profile. Use keyword alerts for continuous matches across public tweets. Brand monitoring often needs both keyword and account monitors. Keep their event IDs, monitor IDs, and queue routes separate. That separation prevents one alert source from impersonating another.

How Do Real-Time Tweet Alerts Reach My Application?

Create the keyword monitor before registering its webhook destination. Subscribe the webhook to the same selected event types. Then send a signed test to validate the receiver. Verify every signature before parsing the request body. Store deliveryId before queuing downstream work. Store streamEventId before processing the matching tweet. Return success only after the durable queue write completes. The Events API provides recovery when live delivery fails. The Deliveries API shows webhook attempts for one registered endpoint. Use Webhook Verification for receiver validation. Use List Deliveries for delivery audits. API access errors require different recovery actions. Replace invalid credentials after a 401 response. Add credits before retrying a 402 response. Respect Retry-After before repeating a 429 request.

How Do I Backfill Tweets Before Starting Keyword Monitoring?

Run the same query through Search Tweets before creating the monitor. Page until the response reports no next page. Store every tweet ID and its source query. Record the newest collected tweet timestamp as the handoff boundary. Then create the keyword monitor with the reviewed query. Deduplicate backfill and monitor events by stable tweet ID. Keep the stored monitor ID beside every continuous event. Do not reuse a search cursor after changing the query. A Twitter tracker must distinguish historical results from live alerts. Search results answer an on-demand time range. Monitor events represent continuous checks after activation. Combining both sources without a boundary creates duplicate tweets.

How Do I Monitor Multiple Keyword Groups?

Use one monitor when all terms share one alert action. Combine those terms with explicit OR grouping. Use separate monitors when terms require different owners or queues. Separate monitors also preserve distinct query evidence. Store each monitor ID, normalized query, event types, and billing time. Pause obsolete monitors instead of creating uncertain duplicates. List keyword monitors before repeating a timed-out create request. A paused duplicate can reactivate with the submitted event types. Review active monitors before each billing checkpoint. Every active keyword monitor adds its hourly charge. Pause queries that no longer trigger a real downstream action. Do not broaden queries merely to generate more alerts.

How Do I Keep Twitter Keyword Alerts Actionable?

Assign one owner and queue to each monitor ID. Route alerts by query, event type, and matched tweet ID. Keep support alerts separate from campaign or competitor alerts. Define the required action before activating the monitor. Review false matches from stored events at a regular interval. Add exact phrases or exclusions when irrelevant tweets repeat. Remove a term when it no longer supports an operational decision. Keep the previous query beside every configuration change. Do not delete evidence when a query changes. Stored events explain why earlier alerts reached their original queue. Record the change time and the responsible operator. Use a new monitor when ownership or alert purpose changes completely. Measure matched tweets, accepted alerts, rejected alerts, and processing failures. Those counts reveal query precision without inventing sentiment scores. Pause noisy monitors while operators correct their stored queries. Resume only after a reviewed search returns useful tweets.

What Does a Twitter Keyword Monitor Not Provide?

A keyword monitor does not return a complete historical archive. It does not provide follower, following, like, or bookmark changes. It does not verify giveaway follows, replies, or reposts by itself. It does not calculate sentiment, reach, or engagement quality. Use Followers for follower snapshots. Use Following for following snapshots. Use focused tweet endpoints for replies, quotes, and retweeters. Use Search Tweets when an operator needs historical matching tweets. This endpoint remains a query-specific Twitter tracker with webhook delivery. It stores concrete tweet matches instead of inferred marketing conclusions.

Headers

string

required

Your API key. Session cookie authentication is also supported. Generate a key from the dashboard.

string

required

Must be application/json.

Body

string

required

X search query to monitor. Whitespace is normalized. Maximum length is 512 characters.

string[]

required

Array of event types to subscribe to. At least 1 required. See Valid Event Types below.

Valid Event Types

Valid keyword monitor types: tweet.new, tweet.quote, tweet.reply, tweet.retweet, tweet.media, tweet.link, tweet.poll, tweet.mention, tweet.hashtag, tweet.longform.

tweet.new

Matching tweet returned by the query. Used when no reply, quote, or retweet signal is present.

tweet.quote

Matching quote tweet returned by the query. Include this when quote activity should create keyword monitor events and webhook deliveries.

tweet.reply

Matching reply returned by the query. Include this when support routing, conversation tracking, or alerting needs replies.

tweet.retweet

Matching retweet returned by the query. Include this when repost activity should create keyword monitor events and webhook deliveries.

Response

201 Created

string

Unique keyword monitor ID.

string

Normalized query being monitored.

string[]

Event types this monitor is subscribed to.

boolean

Whether the monitor is currently active.

string

ISO 8601 creation timestamp.

string

Next hourly credit charge time. New active monitors are due immediately.

{
  "id": "21",
  "query": "xquik api",
  "eventTypes": ["tweet.new"],
  "isActive": true,
  "createdAt": "2026-02-24T10:30:00.000Z",
  "nextBillingAt": "2026-02-24T10:30:00.000Z"
}

400 Invalid Input

{ "error": "invalid_input", "message": "Invalid query or event types" }

Missing query, query longer than 512 characters, or invalid eventTypes.

401 Unauthenticated

{ "error": "unauthenticated", "message": "Missing or invalid API key" }

Missing or invalid API key.

402 Payment Required

{ "error": "insufficient_credits", "message": "Insufficient credits" }

At least 22 available credits are required before creating or reactivating an active keyword monitor. Possible errors include no_credits and insufficient_credits.

409 Duplicate

{ "error": "monitor_already_exists", "message": "Monitor already exists." }

An active keyword monitor already exists for this normalized query. Use Update Keyword Monitor to change event types or pause it.

429 Rate Limited

{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }

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

If a keyword monitor for the same query exists but is paused, creating it again reactivates that monitor with the new event types.

Next steps: List Keyword Monitors, Get Keyword Monitor, Update Keyword Monitor, Create Webhook, List Webhooks, List Events, Get Event, or List Deliveries.

{
  "id": "21",
  "query": "xquik OR \"x api\"",
  "eventTypes": [
    "tweet.new"
  ],
  "isActive": true,
  "createdAt": "2025-01-15T12:00:00Z",
  "nextBillingAt": "2025-01-15T12:00:00Z"
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "monitor_already_exists",
  "message": "Monitor already exists."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

Twitter Keyword Monitor API & Real-time Tweet Alerts

curl --request POST \
  --url https://xquik.com/api/v1/monitors/keywords \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": "<string>",
  "eventTypes": [
    "<string>"
  ]
}
'

import requests

url = "https://xquik.com/api/v1/monitors/keywords"

payload = {
    "query": "<string>",
    "eventTypes": ["<string>"]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({query: '<string>', eventTypes: ['<string>']})
};

fetch('https://xquik.com/api/v1/monitors/keywords', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/monitors/keywords"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"eventTypes\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "query": "<string>",
  "eventTypes": [
    "<string>"
  ],
  "isActive": true,
  "createdAt": "<string>",
  "nextBillingAt": "<string>"
}

​Keyword Monitor Handoff

Monitor ID

Normalized Query

Event Filter

Active State

Stored Event Join

Webhook Delivery Join

​How Do I Monitor Twitter Keywords With an API?

​How Do I Choose Twitter Keywords to Monitor?

​How Do I Track Twitter Mentions and Brand Keywords?

​When Should I Use Keyword Alerts, Tweet Search, or Account Monitoring?

​How Do Real-Time Tweet Alerts Reach My Application?

​How Do I Backfill Tweets Before Starting Keyword Monitoring?

​How Do I Monitor Multiple Keyword Groups?

​How Do I Keep Twitter Keyword Alerts Actionable?

​What Does a Twitter Keyword Monitor Not Provide?

​Headers

​Body

​Valid Event Types

tweet.new

tweet.quote

tweet.reply

tweet.retweet

​Response

​201 Created

​400 Invalid Input

​401 Unauthenticated

​402 Payment Required

​409 Duplicate

​429 Rate Limited

Keyword Monitor Handoff

How Do I Monitor Twitter Keywords With an API?

How Do I Choose Twitter Keywords to Monitor?

How Do I Track Twitter Mentions and Brand Keywords?

When Should I Use Keyword Alerts, Tweet Search, or Account Monitoring?

How Do Real-Time Tweet Alerts Reach My Application?

How Do I Backfill Tweets Before Starting Keyword Monitoring?

How Do I Monitor Multiple Keyword Groups?

How Do I Keep Twitter Keyword Alerts Actionable?

What Does a Twitter Keyword Monitor Not Provide?

Headers

Body

Valid Event Types

Response

201 Created

400 Invalid Input

401 Unauthenticated

402 Payment Required

409 Duplicate

429 Rate Limited