POST https://xquik.com/api/v1/monitors
Create a Twitter account monitor for one known profile. Select tweet, profile,
follow, or follower events. Store the monitor ID. Then connect signed webhooks.
Requires 30 available credits. They pay for the first active monitor hour. The username lookup is free.
Monitors are unlimited. Active monitors check every 1 second. Active monitor billing includes webhook and event deliveries.
Create a Twitter monitor for one account
Use this Twitter monitor API for continuous checks on one known profile. Send the username without@. Choose only the required event types.
This API endpoint gives you one stable monitor ID. Use it to join events and
webhook deliveries.
Use POST /monitors for X (Twitter) API monitoring from one username.
This tweet monitor covers selected posts, replies, quotes, reposts, and profile
changes. It does not search posts from every public account.Choose the right Twitter monitoring option
Choose one option for the required alert scope.Do not replace one option with another after collection starts.
Store the chosen monitor type with every alert.
How do I monitor a Twitter account with an API?
Create one active monitor for each username requiring continuous checks. Send the username without@ and choose exact event types.
Xquik resolves the username to one stable X (Twitter) user ID.
Store both the monitor ID and resolved user ID.
Your application needs no open stream connection.
The account monitor checks selected changes every second.
Real-time Twitter alerts start after connecting a signed webhook.
Stored events remain available for later inspection through the Events API.
Use the monitor ID for updates, pauses, deletion, and event joins.
Use the X (Twitter) user ID for stable account joins.
Never use a display name as the account key.Which Twitter account activity can trigger alerts?
Selecttweet.new for original posts from the monitored account.
Add tweet.reply, tweet.quote, or tweet.retweet for conversation activity.
Use format events for media, links, polls, mentions, hashtags, and long posts.
Each selected event type produces its own alerts.
Profile events cover names, usernames, bios, locations, URLs, avatars, and banners.
They also cover verification, protection, pinned posts, and account availability.
Use profile.unavailable.changed when account availability affects a workflow.
Keep previous and current profile values with the stored event.
Account activity events cover deleted posts and lives the account posts.
tweet.deleted fires when the account deletes a post the monitor saw.
It usually arrives within a minute and holds the post as last seen.
broadcast.started fires when the account posts its running live video.
space.started fires when the account posts a live Space it hosts.
A scheduled Space fires once it starts.
Following events show whom the account follows and unfollows.
New follows usually arrive within a minute, and unfollows within about 15 minutes.
following.added holds the followed account’s profile.
following.removed fires when the account unfollows someone.
For an account that follows over 5,000, older unfollows take up to 2 hours.
Follower events show who follows the account and who leaves its followers.
New followers usually arrive within a minute, and losses within about 15 minutes.
follower.added holds the new follower’s profile.
follower.removed fires when a follower leaves.
It also fires when X suspends or removes the follower’s account.
Lost followers are named for accounts with up to 100,000 followers.
Above 5,000 followers, older losses take up to 2 hours.
Above 100,000, losses are named among the newest 5,000 followers only.
following.added and follower.added also hold followedAt, the time of the follow.
Some follow times are exact. Others are the earliest time the follow can have.
followedAtExact is true for an exact time and false for an earliest time.
followedAt is missing when no follow time is known.
The event’s occurredAt stays the time Xquik saw the change.
An added event holds followKind when the monitor reported that account removed.
That covers removals from the last 30 days.
refollow means it followed again. return means the old follow never ended.
following.removed and follower.removed also hold reason, why the account left.
unavailable means X no longer serves that account, as after a suspension or deletion.
unfollowed means X confirms the follow ended.
A removal event never fires for a follow that still stands.
reason is missing when the cause is unknown.
With unavailable, unavailableReason is not_found or suspended.
Count events show when the account’s follower or following count moves.
profile.followers.changed and profile.following.changed hold previous, current and change.
Count events report only real changes.
Each count sends at most 1 event a minute.
They work on protected accounts too.
Choose only events that trigger an action.
Extra event types create alerts that workers must still review.
Update the monitor when the required event set changes.
Do not infer unselected changes from tweet or profile counts.How do real-time Twitter alerts reach my application?
Create the account monitor before registering its delivery endpoint. Then create an HTTPS webhook with the required event filters. Save the one-time webhook secret in a secret manager. Send a signed test before accepting production deliveries. VerifyX-Xquik-Signature, X-Xquik-Timestamp, and X-Xquik-Nonce first.
Compute the signature from the raw request body.
Reject invalid signatures before parsing or queuing the payload.
See Webhook Verification for complete receiver examples.
Use deliveryId for delivery-level idempotency.
Use streamEventId for one-time monitor event processing.
Store the queue row before returning a successful receiver response.
Inspect Webhook Deliveries when alerts stop arriving.How do I monitor competitor Twitter account activity?
Create one account monitor for each competitor username. Track new tweets, replies, quotes, reposts, links, and media. Add profile events for bio, username, avatar, banner, and pinned-post changes. Store each event type, timestamp, monitor ID, and X (Twitter) user ID. This workflow records account changes. It does not calculate sentiment, brand reputation, or share of voice. Use a keyword monitor for mentions across unrelated accounts. Use tweet search for a retrospective competitor query. Keep competitor alerts separate from your own account alerts. Route each monitor ID to its intended queue or workspace. A competitor event then cannot trigger unrelated jobs.How do I monitor multiple Twitter accounts?
Create one monitor request per username. Monitors are unlimited, but each active monitor has hourly billing. Keep at least 30 credits before creating or restoring each monitor. Store every returned monitor ID before creating the next request. An active duplicate returns409 monitor_already_exists.
Use List Monitors to recover its stored ID.
Use Update Monitor to change events or active state.
Pause a monitor when you can. Do not create a replacement.
Store each resolved X (Twitter) user ID beside the current username.
The user ID stays the same when a username-change event arrives.
Review nextBillingAt before keeping large monitor sets active.What does an account monitor not track?
Account monitors exclude likes, bookmarks, and direct-message activity. They do not return a complete historical timeline or follower list. They do not search specific keywords across every account. Use Followers for the follower list as it stands now. Use Following for the current following list. Use User Tweets for timeline retrieval. Use Create Keyword Monitor for matching queries. Do not use aggregate counts in place of participant or relationship records. Choose the endpoint that returns the required tweets, profiles, or relationships.How do I recover from monitor and webhook failures?
List account monitors before repeating an uncertain create request. Reuse the stored monitor when the first request succeeded. Retry the same username and event types only when no monitor exists. A webhook failure does not require a new monitor. Fix the receiver, verify its signature code, and send another signed test. Then inspect delivery attempts and joinstreamEventId to the stored event.Account monitor handoff
UsePOST /monitors for one X account. Send alerts to a queue, CRM,
warehouse, Slack, or an agent. It checks the selected events every second.
Create the monitor first. Then create a signed webhook with
POST /webhooks. Call
POST /webhooks/{id}/test before enabling
production alerts.What should a webhook receiver save?
Save the monitor ID, username, user ID, event type, event time, and delivery ID. Use the monitor ID to group alerts for one account. Use the delivery ID to stop the same job twice. Keep the event ID for later checks. These fields support replay, audits, retries, and alert routing. Active account monitors check every 1 second. Each active hour costs 30 credits. You need 30 available credits to create or restore a monitor. They pay for the first active hour. The username lookup is free. Pause the monitor through Update Monitor (PATCH /monitors/{id}). Set
{ "isActive": false } when alerts should stop.Headers
Body
Valid event types
Choose only the exact event types in the goal map below.Match event types to monitor goals
Response
201 Created
400 Invalid input
Missingusername or missing/invalid eventTypes array. A username that’s
no X (Twitter) username or user ID gets its own message.
{ "error": "invalid_input", "message": "Set username to an X username or user ID, like @NASA." }401 Missing API key
Missing or invalid API key or OAuth bearer token.402 Payment required
Keep at least 30 credits available before sending this request. The API may returninsufficient_credits when the balance is too low.404 User not found
Xquik could not find that username or user ID. Check the spelling.409 Duplicate
An active monitor already tracks this X account. Use Update Monitor to change event types instead. Create or Update Monitor skips this answer. It updates the monitor you have and answers200.429 Rate limited
Too many requests. Wait for theRetry-After header before retrying.Xquik reactivates a previously deleted monitor with new event types. An active
duplicate returns
409.Next steps.
- List Monitors to view account monitors.
- Get Monitor to fetch one monitor.
- Update Monitor to pause or resume checks.
- Create Webhook to receive events.
- List Webhooks to check subscriptions.
- List Events to audit stored events.
- Get Event to inspect one event.
- List Deliveries to inspect webhook attempts.
Response examples
- 400
{ "error": "invalid_input", "message": "Invalid input. Check the request body." } - 401
{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." } - 402
{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." } - 403
{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." } - 404
{ "error": "user_not_found", "message": "X user not found. Check the username." } - 409
{ "error": "monitor_already_exists", "message": "Monitor already exists." } - 429
{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }