TwitterAPIs

Searches recent tweets with X's advanced-search operators: from:, to:, since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N, min_retweets:N, filter:links, -filter:replies, lang:en, and free text. Returns tweet text, author info, engagement metrics and a pagination cursor. product='Latest' gives chronological results; 'Top' (the default) is engagement-ranked. Example queries: 'AI agents min_faves:100', 'from:openai filter:links since:2024-01-01', '#buildinpublic -filter:replies lang:en'. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/search/tweet-advanced-search

Searches Twitter/X user accounts by display name or handle (X's People search). Bio text is not searched, so a word that appears only in a bio returns no match. Returns matching profiles (username, display name, bio, follower count, verification status) with a pagination cursor. Covers brand handles, partial handles, and people known only by name. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/search/user-search

Returns a user's complete public profile by @handle: display name, bio, follower count, following count, verification status, location, website, account creation date, pinned tweet, and the numeric user_id. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-info

Returns a user's complete public profile by numeric user id: display name, bio, follower and following counts, verification status, location, website, account creation date and pinned tweet. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-info-by-id

Reports whether a Twitter/X account is alive, suspended, or deleted. Returns a status field that is one of 'alive', 'suspended', 'not_found' or 'unavailable', plus the numeric id when the account is alive and X's own reason when it gives one. It distinguishes a suspended or deleted account from a handle that does not exist, which a profile read answers the same way. Every outcome is a successful response: the answer is in the status field, and a suspension is not an error. A protected (private) account counts as alive, since protection is a visibility setting and not an account state. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-status

Returns a user's full 'About' object: the structured profile facts X surfaces beyond the bio, including account category and professional/business labels, verification and identity-verification flags, joined date, location and linked website, follower/following counts, and X's 'About this account' transparency panel (the account's country, how the account was created, and its username-change history). Takes a username or a user_id. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-user-about

Returns the 'About' object (account country, how the account was created, username-change history, verification and the other About fields) for up to 100 accounts in one call. Takes usernames or user_ids as a comma-separated list, not both. Results come back in request order, each with an about object or an error code (not_found is billed; forbidden is free, X refuses that account to everyone; rate_limited and unavailable are free and retryable). Billed per account X answered for. One batch per API key runs at a time: a concurrent call gets 429 batch_in_progress (not billed). fields/compact apply inside each item's about object (fields=account_based_in); a results.* path returns about: {}. Cost: $0.0008 per billed item. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-user-about-batch

Lists the affiliated accounts of an organization profile (the smaller accounts X displays under a company's 'Affiliated' badge, e.g. employees or sub-brands). Takes a username or user_id. Returns profile data per affiliate plus a pagination cursor, and an empty list for accounts with no affiliations. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-affiliates

Returns the follow relationship between two accounts: whether the source follows the target, whether the target follows the source, and blocking/muting flags where available. Each side is a numeric user id or a username (an unknown username or id returns a not-found error, not billed). Covers checking a follow before or after a follow action, and detecting mutuals. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-check-follow-relationship

Checks one account against up to 100 others in one call. Either one source (source_user_id or source_username) with up to 100 targets (target_usernames or target_user_ids), or one target with up to 100 sources (source_usernames or source_user_ids): a list on one side only. Each result carries the relationship from the SOURCE's side (following = source follows target, followed_by = target follows source), in request order. Example: which accounts on a shortlist already follow a brand, with the brand as target_username and the shortlist as source_usernames. Billed per pair answered with a relationship; not_found, forbidden, rate_limited and unavailable pairs are free. One batch per API key runs at a time (a concurrent call gets 429 batch_in_progress, not billed). fields/compact apply inside each item's relationship object. Cost: $0.0008 per billed item. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-check-follow-relationship-batch

Summarises an audience in one call: samples up to 100 followers of an account (username or user_id) or retweeters of a tweet (tweet_id), reads each sampled account's About country, and returns a country histogram (shares over accounts with a known country) plus a likely-bot share from documented profile signals (default avatar, no bio, under 5 followers, extreme follow ratio, no posts, created in the last 30 days, digit-suffix handle; 3 or more signals = likely automated, a heuristic, not a verdict). Billed per item: each sample page that added accounts plus each sampled account X answered About for, so sample=100 costs at most $0.08 plus up to 3 pages. Shares the one-batch-per-key slot with the batch endpoints. Cost: $0.0008 per billed item. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-audience-summary

Returns a user's recent posting timeline, cursor-paginated further back. The endpoint does not filter server-side, so the response routinely includes retweets and replies alongside original posts. Every item carries is_retweet, is_reply and is_quote booleans, and author.username names who wrote it (a retweet's retweeted_tweet holds the original author). Returns tweet text, id, timestamp and engagement metrics. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-tweets

Returns a user's full activity timeline: their original tweets and their replies to others, cursor-paginated. Shows how someone engages with a community, not just what they post. Items carry is_retweet, is_reply and is_quote booleans. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-tweets-and-replies

Returns a large batch of a user's tweet history in one call, auto-paginating server-side across upstream pages: { count, next_cursor, has_more, tweets }. One call does not guarantee the whole history: next_cursor is the completion signal, not count. A non-null next_cursor means the history is truncated and more remains, and passing it back as cursor continues from where the call stopped; a null next_cursor means the history is complete (has_more is the same signal as a boolean). Each call is bounded by both max and a server-side wall-clock budget, so a response can be truncated even when it holds fewer tweets than max, which is why count is not a completion signal. Takes the numeric user_id only. Billed flat per call regardless of how many tweets come back, so fewer, larger calls cost less than many small ones. Cost: $0.0024 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-tweets-complete

Returns the images and videos a user has posted: media-containing tweets with URLs to the media files, dimensions, and type (photo/video/animated_gif), cursor-paginated. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-media

Returns recent public tweets that mention (@ tag) a user, found with the to: search operator, with author info and metrics, cursor-paginated. Covers brand mentions, replies directed at an account, and public conversations about a person. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-mentions

Returns the tweets a user has liked (their public Likes tab), most recent first, each with author and metrics, plus a pagination cursor. Empty if the account hides its likes. Takes the numeric user_id only. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-likes

Lists the accounts that follow a given user, with profile data for each follower (username, display name, bio, follower count), cursor-paginated for large audiences. Covers audience analysis, such as who follows a brand or influencer. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/follower-graph/user-followers

Lists the accounts a given user follows, with profile data for each account followed, cursor-paginated. Covers a user's information sources, influencer networks, and competitor monitoring lists. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/follower-graph/user-following

Lists a user's followers in the v2 response shape: richer profile fields and more reliable cursoring for deep follower lists. Takes a username or user_id. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/follower-graph/user-followers-v2

Lists the accounts a user follows in the v2 response shape: richer profile fields and more reliable cursoring for deep following lists. Takes a username or user_id. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/follower-graph/user-following-v2

Lists a user's followers that have a verified account (checkmark), cursor-paginated: the follower list filtered to verified accounts, which surfaces notable or institutional followers. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/follower-graph/user-verified-followers

Lists the 'Followers you know' for a target user id: the followers of that account that the authenticated account also follows (mutual-connection overlap). Requires an authenticated X session behind the API key. Returns profile data per overlap account plus a cursor. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/follower-graph/user-followers-you-know

Returns the full detail of a single tweet: text, author profile, post timestamp, like/retweet/reply/quote counts (quote_count is X's own total of quote tweets), attached media, referenced quoted tweet, and parent reply context. Takes the tweet id or its full URL. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/tweet-details/tweet-detail

Returns replies to a specific tweet, each with author, text and metrics, cursor-paginated. Covers the conversation under a tweet, its sentiment, and notable responses. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/tweet-details/tweet-replies

Returns every direct reply under a tweet in one call, walking the reply pages server-side: { count, next_cursor, has_more, is_complete, pages_fetched, sort, tweets }. is_complete is the completion signal, not count: true means X signalled the end of the conversation; false means the call stopped early (on max, a server-side time budget, a page cap, or a later page failing), and passing next_cursor back as cursor continues. Billed flat per call however many pages it walks, so one call over a long conversation costs less than paging it one reply page at a time. Cost: $0.0024 per call. Docs: https://docs.twitterapis.com/docs/reference/tweet-details/tweet-replies-complete

Returns the tweets in a thread: the connected chain of tweets posted by the SAME author in sequence (a tweetstorm or numbered thread), in order, in a single call. It reads FORWARD from the tweet you pass and does not walk backwards, so pass the thread's FIRST tweet: its id is the conversation_id carried on every tweet in the thread. Passing a later tweet returns only that tweet and the author's tweets after it, the tail of the thread, and is_partial is true on that response. Replies from other users are not included. Takes the tweet id or its full URL. Cost: $0.0040 per call. Docs: https://docs.twitterapis.com/docs/reference/tweet-details/tweet-thread

Lists the accounts that retweeted a specific tweet, with profile data for each retweeter, cursor-paginated. Shows who amplified a piece of content and how it spread. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/tweet-details/tweet-retweeters

Lists the tweets that QUOTE a specific tweet, cursor-paginated as full tweet objects, so each carries the commentary attached rather than just a number. A plain retweet carries no text and a reply is not a quote, so neither appears here. The endpoint is SEARCH-BACKED: X exposes no dedicated quote-tweets operation, so it runs the query quoted_tweet_id:<id> against X's search index. The returned 'count' is how many quotes this search returned, not the tweet's true total; the authoritative total is 'quote_count' on the tweet object, and the two differ because of index lag and because deleted, protected, suspended and region-withheld quotes are absent from search. Every response carries 'source' ("search"), 'search_query' (the exact query sent), and 'quote_matched' (how many returned tweets demonstrably quote the requested id). quote_matched equal to count means every row is genuine; quote_matched 0 on a NON-EMPTY page means X stopped honouring the operator and the rows are unrelated to the tweet. An empty first Top page is served from Latest instead of reading as zero quotes: the response then says product_used "Latest" and top_fallback true, and its next_cursor pages that Latest list. Search does not return every quote for some accounts, so a page can be empty with has_more false while the tweet has quotes; every response therefore also carries 'quote_count' (the tweet's real total, null when it could not be read or read as 0) and 'coverage': "complete" (the search ended on its first page holding at least quote_count rows), "partial" (it ended with fewer, plus a 'coverage_hint'; the rest were withheld by search) or "unknown" (more pages to walk, a later page, or no total). Count 0 with coverage "partial" means quotes exist that search withheld. X serves at most 20 quotes per page, so count above 20 is clamped to 20; 'requested_count' and 'effective_count' echo it. Page with next_cursor for more. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference

Lists the members of a Twitter/X List by its numeric list id, with profile data for each member, cursor-paginated. Covers curated account sets such as competitor lists, industry watchlists or media outlet lists. The list_id appears in the X.com list URL (x.com/i/lists/<list_id>). Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/list-data/list-members

Lists a public List's followers by its numeric id, cursor-paginated. Followers and members are different sets of people: members are the accounts the List owner added to it, followers are the accounts that subscribed to read it. A List with hundreds of members commonly has only a handful of followers, so a small count here is normal and is not a truncated page. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/list-data/list-followers

Returns the posts written by the members of a public Twitter/X List, newest first, through X's search index. This is the FILTERABLE List feed: it accepts since and until date bounds and an include_replies toggle. It returns no retweets, and search-index lag applies, so a post made moments ago can be missing for a short while. Cursor-paginated. The list_id appears in the X.com list URL (x.com/i/lists/<list_id>). Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/list-data/list-tweets

Returns a public Twitter/X List's NATIVE feed: the same posts and the same ordering the List shows on x.com, including members' retweets. It takes only list_id, count and cursor; no date range and no reply filter exist on this endpoint, because a native timeline cannot honour search operators. Cursor-paginated; an empty tweets array marks the end. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/list-data/list-timeline

Get metadata and the participant roster for one X Space by id, live or ended: title, lifecycle state (Scheduled, NotStarted, Running or Ended), host, topics, scheduled and actual start/end times, peak live listener count, replay view count, and the admin, speaker and listener rosters. Returns metadata only, NOT the Space audio. Note that X does not retain the per-person listener roster once a Space ends, so listeners comes back empty for an ended Space while total_live_listeners and total_replay_watched still reflect the real audience. All timestamps are millisecond-epoch numbers. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/spaces/spaces-info

Finds X Communities by keyword, cursor-paginated, returning each community's id. Each hit is a compact record: id, name, member count, nsfw flag, topic name, banners and the facepile avatars, exactly what X's own search sends and nothing more. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/communities/community-search

Returns the metadata for one X Community by its numeric id: name, description, member_count, moderator_count, join_policy, invites_policy, the join question, primary topic, search tags, the posted rules, both the custom and the default banner plus a resolved banner_url, the permalink, the admin and creator profiles, and the facepile member ids. The community id is the digits in a x.com/i/communities/<id> URL. role, can_join, is_pinned and viewer_relationship_type are null by design, not an error: they describe the account that made the call, and this public read does not run as your account. rules[].description is also null: X sends only the rule id and name on this payload. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/communities/community-info

The About tab for one X Community: its moderators, and a preview of its members, both returned as FULL user profiles with bio, follower and following counts, tweet counts, location, website, banner and join date, so it answers who runs a community in one call. It covers the PEOPLE, not the community object (name, description, rules, join policy). Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/communities/community-about

Lists the member roster of an X Community, cursor-paginated, with each row carrying that member's own role in the community: 'Admin', 'Moderator' or 'Member'. Rows are { user, role }. The user object is REDUCED (id, username, name, profile_image_url, is_blue_verified, verified, is_protected) because X's roster operation sends no bio, no follower or following counts and no created_at. The role on a member ROW is not caller-relative and is returned in full, unlike the role field on the community object itself. Admins and moderators are interleaved through this list at arbitrary positions, so one page filtered by role is not a complete moderator list. Paging is a bare next_cursor with no total count from X; the list ends when members comes back empty or has_more is false. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/communities/community-members

Lists the moderators and admins of an X Community, cursor-paginated, in { user, role } rows (the array is named members). This is a SEPARATE upstream operation, not a filter over the member roster: moderators sit at arbitrary positions inside the full roster, so filtering one roster page would return only the moderators among its first rows while looking like a complete answer. Admins appear here too; each row's role says which. Paging is a bare next_cursor with no total count from X. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/communities/community-moderators

Returns an X Community's own post timeline, cursor-paginated as full tweet objects, with the community's PINNED post in its own separate 'pinned' field rather than as an item inside 'tweets'. X delivers the pinned post as a different timeline entry and does not repeat it in the feed, so 'tweets' alone omits it, and it is very often the community's rules post. One flat list is 'pinned' (when non-null) followed by 'tweets'; the pinned post is excluded from 'tweets', so there is no duplicate. ranking_mode is a REAL upstream parameter, not a local sort. Scope is one community. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/communities/community-tweets

The INVERSE community lookup: given a numeric X USER id, lists the communities that account belongs to, cursor-paginated. Each row is the FULL community object (member counts, rules, topic, policies, admin and creator). Takes a numeric user id ONLY, not a @handle. An EMPTY communities array is a real, successful answer (the account is in no communities), not a not-found. role / can_join / is_pinned / viewer_relationship_type are null on every community returned, because this public read does not run as your account. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/communities/community-memberships

Ranks the accounts posting native video about a topic. Runs one X search page for '<query> filter:native_video' and groups the matching posts by author into a ranked creators list; each row carries rank, the full user profile, video_post_count, quote_post_count, total_views, views_known, median_views, median_reply_count, median_quote_count and up to three top_post_ids. Retweets, posts without video or author, and posts under min_views are skipped and counted per reason in skipped (retweet, no_video, no_author, below_min_views), with tweets_scanned and tweets_matched beside them, so a short list can be told apart from a thin page. The ranking rule is returned as text in ranking on every response. One page covers about 20 posts; next_cursor pages the same search. An empty creators list is a successful answer (nobody posted video on the topic in that page), not an error. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/search/creator-commentary-video

Asks X's own Grok a question as the authenticated account and returns ONE complete JSON reply: the answer text, citations (url, domain, title, snippet) merged and de-duplicated across every search Grok ran, the searches themselves (tool_calls), the conversation and turn ids, and both the requested model and which model ACTUALLY answered (they can differ). Grok reads X in real time, so it answers about what is being said right now, and a bare tweet or status URL as the message returns a structured summary of that post. The reply is text and JSON only: it has no image or media field. Buffered, not streamed: a search-grounded answer can take up to 90 seconds, and a submit-and-poll form of this call exists for clients that stop waiting sooner. STATELESS: nothing is stored, so a multi-turn conversation carries its prior turns in messages[] along with conversation_id. Requires an authenticated X session for the acting account. Cost: $0.0040 per call. Docs: https://docs.twitterapis.com/docs/reference/grok/grok-chat

Starts the same Grok chat as the buffered Grok chat call without holding the connection open, for clients that stop waiting before a search-grounded answer arrives. Takes the same arguments and returns 202 at once with job_id, status 'pending', poll (the path to read the job at), poll_after_seconds (3), result_ttl_seconds (900) and created_at. A bad body, a bad API key, a missing X session and a short balance are answered on the spot, before any job exists. At most 5 jobs per API key can be pending at once; one more answers 429 too_many_pending_jobs. Submitting is free: the $0.004 Grok chat price is charged once, on the poll that first delivers the finished answer, and a failed, timed-out, interrupted or uncollected job is not charged. Requires an authenticated X session for the acting account, and the chat runs as that account. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/grok/grok-chat-submit

Reads a Grok chat job by the job_id its submit call returned. While the job runs: 202 with status 'pending', poll_after_seconds and created_at. When it finishes: 200 with the full Grok chat reply (answer, citations, tool_calls, conversation and turn ids, requested and actual model) plus job_id and status 'done'. When the chat failed: the status and typed error the buffered call would have answered, plus job_id and status 'failed'; 504 job_timeout and 503 job_interrupted mean the job did not finish on this API's side. An unknown job_id, a finished answer older than 15 minutes and another API key's job all answer 404. The $0.004 Grok chat price is charged once, on the first poll that delivers the finished answer; polling it again is free. Needs only the API key that submitted the job, no X session. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/grok/grok-chat-result

Reports whether the authenticated account can use Grok, and which models it may pick: eligibility, X's own reasons when it is NOT eligible (passed through verbatim, since X's policy is not visible to this API), whether free access is enabled, and the available model options. Eligibility is a property of the X ACCOUNT rather than of the API key. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/grok/grok-config

Returns the current top trends for a location, or for one of X's Explore topic tabs. With no parameter, returns Worldwide (WOEID 1, X's own default). country takes an ISO code or country name (e.g. 'US' or 'Japan'); woeid takes a numeric WOEID and wins when both are given. category reads an X Explore tab instead (trending, news, sports, entertainment or for_you), or business_and_finance for only the ranked trends X labels Business and finance, read from the Trending and News tabs. category cannot be combined with country or woeid (400). business_and_finance returns no story items and can return an empty list when X labels nothing Business and finance at that moment. Category results reflect the Explore view of the account the API reads with. Returns the as_of timestamp and the ranked trends; a location call also returns the resolved location and created_at. A category response echoes category and has location and created_at null. An Explore tab response lists X's ranked trends first, then the tab's story items: AI-written headlines X marks, each with the headline as query, an x.com/i/trending/<id> url and the post count as tweet_volume. Story items carry is_ai_story true, but so can a ranked trend X flags as AI-written; the x.com/i/trending url is what marks a story item. A tab may hold only story items. count truncates the list. A location X does not serve returns a 400. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/trends/trends

Lists every location X publishes trends for, each with its name and numeric WOEID. Takes no required parameters. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/trends/trends-locations

Returns your twitterapis.com account details: email, name, credits remaining, credits used, total requests made, and account creation date. Authenticated by the API key. An account read, not Twitter data; it spends no credits. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account/account-me

Takes no parameters.

Returns your twitterapis.com payment history: the list of top-ups and charges on the account. Authenticated by the API key. An account read, not Twitter data; it spends no credits. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account/account-payments

Takes no parameters.

Reports a product problem or gap in twitterapis.com to its team from inside this session. A report is first drafted to a local queue (action "draft", the default), which sends nothing; action "send" posts the drafts named in ids to POST /feedback and returns a server id per report. action "list" shows the pending drafts with their ids, and action "discard" drops drafts. A draft carries a type (bug, idea or missing_capability), a title of at most 120 characters, details of at most 8000 characters, an optional area, and optional evidence identifiers. Evidence fields left out are filled from the last failing call in this session (tool, endpoint, HTTP status, request id), and mcp_version and client are attached to every report. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account/feedback-post

Returns a feedback report this account sent earlier, by its server id: its details and evidence, status new, triaged, shipped or declined, the team's response text if any, and updated_at, which moves only when the team acts on it. 404 if the id is not on this account. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account/feedback-id

Lists the feedback reports this account has already SENT to twitterapis.com, newest first: server-side reports, not local drafts that are still unsent. Each item carries id, type, title, area, status (new, triaged, shipped or declined), the team's response if any, created_at and updated_at; details and evidence are not included, so paging this cannot bulk-export a report's body. Cursor-paginated while next_cursor is non-null. Feedback calls share a 10-per-minute rate limit. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account/feedback-get

Returns the authenticated account's Home timeline (the 'Following'/'For you' feed), most recent first: what that account sees when it opens X. Requires an authenticated X session behind the API key. Returns tweets with author and metrics plus a cursor. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-home-timeline

Lists the authenticated account's bookmarked tweets, most recent first. Requires an authenticated X session behind the API key. Returns each bookmarked tweet with author and metrics plus a cursor. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-bookmarks

Lists the accounts the authenticated account has BLOCKED, as full user objects, cursor-paginated. Requires an authenticated X session behind the API key. There is no user_id argument: X provides no way to read another account's block list, so this reads the authenticated account's only. An empty users array is a real answer meaning the account blocks nobody, not a silent failure, because the endpoint returns an error status rather than an empty page when it cannot read the list. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-blocking

Lists the accounts the authenticated account has MUTED, as full user objects, cursor-paginated. Muting hides an account's posts from the timeline without blocking it, so the mute list is a different list from the block list and an account can appear in one and not the other. Requires an authenticated X session behind the API key. There is no user_id argument: X provides no way to read another account's mute list. An empty users array means the account mutes nobody, not a silent failure. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-muting

Full-text search within the authenticated account's bookmarks. Requires an authenticated X session behind the API key. Returns matching bookmarked tweets plus a cursor. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-bookmark-search

Lists the authenticated account's bookmark FOLDERS (X's internal name: collections), the named groups saved tweets can be organised into, separate from the flat bookmarks list. Requires an authenticated X session behind the API key. Returns each folder's id, name, and a cover image. Takes no arguments; the folders resolve from the session alone. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-bookmark-folders

Returns the tweets inside ONE of the authenticated account's bookmark folders, identified by folder_id. Requires an authenticated X session behind the API key. Cursor-paginated; there is no count/page-size argument for this operation. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/user-reads/user-bookmark-folder-timeline

Lists the authenticated account's Direct Message conversations (inbox), each with the participant and its conversation_id. Requires an authenticated X session behind the API key. Read-only: sends nothing. It reads X's standard DM inbox, so conversations X has moved to end-to-end encrypted chat may not appear, and conversations still in the message-requests folder may be missing. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/direct-messages/dm-list

Returns the messages in one Direct Message conversation by its conversation_id. Requires an authenticated X session behind the API key. Returns each message with sender id, time, and text, plus min_entry_id and max_entry_id for the page; max_id set to a page's min_entry_id returns the next older page. Read-only: sends nothing. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/direct-messages/dm-conversation

Sends a Direct Message as the authenticated account to a recipient's numeric user id (recipient_id) with the message text. Requires an authenticated X session with write capability behind the API key; X soft-blocks writes from datacenter IPs, and a residential proxy_url makes delivery more reliable. Returns message_id and conversation_id. Delivers a real DM and is not silently reversible. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/direct-messages/dm-send

Posts a new tweet as the authenticated account. reply_to posts it as a reply, quote as a quote-tweet. It publishes publicly and is not silently reversible; removal is a separate delete. Requires an authenticated X session with write capability behind the API key. Returns the new tweet_id and url. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-create

Deletes a tweet as the authenticated account. Irreversible: the tweet is permanently removed. Only tweets the authenticated account authored can be deleted. Takes the tweet id or url. Requires write capability behind the API key. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-delete

Changes the display name, bio, location or link on the authenticated account's own X profile. This is a PARTIAL update: only the fields sent change, and every omitted field keeps its current value, so a name alone leaves the bio intact. An empty string CLEARS that field, which differs from omitting it: "" blanks the value, an absent key leaves it alone. At least one of name, description, location or url is required, and a request whose only value is an empty string is a valid clear rather than an empty request. It writes a real profile and takes effect immediately with no undo. Requires an authenticated X session behind the API key. Returns ok and updated_fields, which echoes the field names SENT rather than a diff against the previous profile. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/user-update-profile

Replaces the profile picture on the authenticated account's own X profile. Takes ONE field, image, holding base64-encoded image bytes: not a URL, not multipart, and not a media upload id. It writes a real profile and takes effect immediately with NO UNDO, and X keeps no history of the previous picture; its current URL is profile_image_url on the profile. Returns ok. X mints a new media id for every accepted upload, so profile_image_url changes even when the image is byte-identical to the one already in place. Requires an authenticated X session behind the API key. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/user-update-avatar

Replaces the wide header image on the authenticated account's own X profile. Takes ONE field, banner, holding base64-encoded image bytes: not a URL, not multipart, and not a media upload id. X renders the header as a wide strip, so a 3:1 image fills it without cropping. It writes a real profile and takes effect immediately with NO UNDO, and X keeps no history of the previous banner; its current URL is cover_picture on the profile. Returns ok. At least one of X's own endpoints reports cover_picture as empty for accounts that plainly have a banner, so an empty cover_picture is not by itself evidence the account has none. Requires an authenticated X session behind the API key. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/user-update-banner

Saves a PRIVATE draft tweet on the authenticated account. Nothing is posted and nobody can see it: the draft lands in X's own composer under Drafts until a person publishes or deletes it. Requires an authenticated X session behind the API key. Returns ok and draft_tweet_id. A null draft_tweet_id means X refused the create; that answers 422 and is not billed. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/draft-create

Replaces the contents of one existing PRIVATE draft on the authenticated account. The fields sent BECOME the draft rather than merging into it, so any field left out is dropped, including media. Posts nothing. Requires an authenticated X session behind the API key. Returns ok and the draft_tweet_id edited. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/draft-edit

Deletes one PRIVATE draft from the authenticated account by id. Irreversible, but low-stakes: a draft is not public, so this retracts nothing and notifies nobody. Requires an authenticated X session behind the API key. Returns ok, deleted, and the draft_tweet_id targeted. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/draft-delete

Lists the PRIVATE drafts saved on the authenticated account, the source of draft ids for an edit or a delete. Drafts are private to the account that holds them, so no other account's drafts are readable. Requires an authenticated X session behind the API key. Returns drafts (each with draft_tweet_id, text, thread_truncated), count, and sometimes partial. thread_truncated true means the draft is a THREAD and text is only its first tweet, which is a parse that succeeded. partial true means X's answer was read but not fully understood, which is NOT 'no drafts': partial is absent entirely on a clean read, so an empty drafts array with no partial flag means the account has none. One call returns the whole list; there is no cursor and no timestamp on a draft row. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/draft-list

Schedules a tweet to POST PUBLICLY at a future instant from the authenticated account. This is NOT a draft: it goes out on its own at execute_at unless it is cancelled first. execute_at is epoch SECONDS, not milliseconds (a Date.now() millisecond value is 1000x too large), and a millisecond value is refused with a message naming the unit rather than scheduling the post tens of thousands of years out. It has to be strictly in the future. Requires an authenticated X session behind the API key. Returns ok, scheduled_tweet_id, and the execute_at sent. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/scheduled-create

Cancels one PENDING scheduled post on the authenticated account so it does not publish. Applies only before its execute_at: once the post has gone out there is no scheduled row left to cancel, and what remains is an ordinary tweet. Requires an authenticated X session behind the API key. Returns ok, deleted, and the scheduled_tweet_id targeted. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/scheduled-delete

Lists the posts QUEUED to publish on the authenticated account: the source of scheduled ids for a cancel, and a record of what is already queued. Rows carry X's own state label verbatim (for example Scheduled), and a row that has already published leaves the queue and becomes an ordinary tweet. Requires an authenticated X session behind the API key. Returns scheduled (each with scheduled_tweet_id, text, thread_truncated, execute_at, state), count, and sometimes partial. thread_truncated is INFERRED on this endpoint rather than captured: a scheduled row carries the same compose payload a draft row does, and the captured scheduled row elides that body, so the flag is sound and fail-safe (an absent key yields false) but has not been seen true. execute_at comes back in epoch SECONDS: X answers this operation in milliseconds and the value is normalised, so it is in the same unit the scheduling input takes. partial true means X's answer was read but not fully understood, which is not the same as an empty queue; on a clean read it is absent entirely. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/scheduled-list

Likes (favorites) a tweet as the authenticated account. Takes the tweet id or url. Requires write capability behind the API key. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-favorite

Removes a like (unfavorite) from a tweet as the authenticated account. Takes the tweet id or url. Requires write capability behind the API key. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-unfavorite

Pins one of the authenticated account's own tweets to the top of its profile. Pinning replaces any existing pinned post, since a profile has one. Takes the tweet id or url. Requires write capability behind the API key. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-pin

Unpins the tweet pinned to the top of the authenticated account's profile, leaving the profile with no pinned tweet. The tweet itself stays posted. Takes the tweet id or url. Requires write capability behind the API key. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-unpin

Retweets a tweet as the authenticated account. Takes the tweet id or url. Requires write capability behind the API key. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-retweet

Undoes a retweet as the authenticated account. Takes the tweet id or url. Requires write capability behind the API key. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-unretweet

Bookmarks a tweet to the authenticated account's private bookmarks. Takes the tweet id or url. Requires write capability behind the API key. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-bookmark

Removes a tweet from the authenticated account's bookmarks. Takes the tweet id or url. Requires write capability behind the API key. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/tweet-unbookmark

Follows a user as the authenticated account, by numeric user_id or by @handle (exactly one of the two). Requires write capability behind the API key. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/user-follow

Unfollows a user as the authenticated account, by numeric user_id or by @handle (exactly one of the two). Requires write capability behind the API key. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/user-unfollow

Adds one account to a Twitter/X List that the registered X session owns, by numeric list id and numeric user id. Example: adding each speaker at a conference to a List as they are announced. Returns ok, action, list_id, user_id, the List's member_count read back from X after the write, and the full list object. member_count confirms the change landed; it is null when X returned no list object at all, which is itself the not-applied signal. A write that does not apply (the account is already a member, the List belongs to another account) comes back with the SAME field layout plus a 422 and a machine-readable reason, and is not billed. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/list-add-member

Removes one account from a Twitter/X List that the registered X session owns, by numeric list id and numeric user id. Example: pruning accounts that have gone quiet from a curated List. Returns ok, action, list_id, user_id, the List's member_count read back from X after the write, and the full list object. member_count confirms the removal landed; it is null when X returned no list object at all, which is itself the not-applied signal. A write that does not apply (the account was not a member, the List belongs to another account) comes back with the SAME field layout plus a 422 and a machine-readable reason, and is not billed. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/list-remove-member

Creates a new Twitter/X List owned by the registered X session, with a name and an optional description and privacy flag. Returns ok, action, the new list_id, member_count, and the full list object X returned. A List is PUBLIC unless is_private is "true", and a private List is not readable through the public List reads (members, tweets, timeline). Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/list-create

Joins an X Community as the authenticated account, by numeric community id. One upstream call, nothing read first. Returns ok, action ('join'), community_id, status ('joined') and community, which holds only the keys X sent back among id, name, member_count, role and join_policy, or is null when X sent no community object. Refusals come back with the same fields plus an error code and are not billed: 409 join_requires_approval (the community requires moderator approval; no join request is submitted), 409 already_member, 404 community_not_found, 403 account_suspended or account_locked, and 422 write_not_applied with X's own reason. Requires an authenticated X session. Reversible. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/community-join

Leaves an X Community as the authenticated account, by numeric community id. One upstream call, nothing read first. Returns ok, action ('leave'), community_id, status ('left') and community, which holds only the keys X sent back among id, name, member_count, role and join_policy, or is null when X sent no community object. Refusals come back with the same fields plus an error code and are not billed: 409 not_member, 404 community_not_found, 403 account_suspended or account_locked, and 422 write_not_applied with X's own reason. Requires an authenticated X session. Reversible for a community open to anyone; a community that requires moderator approval cannot be rejoined through this API, since a join there answers 409 join_requires_approval. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/community-leave

Registers your own X account session against the API key, so the authenticated-account reads (home timeline, bookmarks, DMs, likes, articles) and the write actions (posting, DMs, follows, likes, retweets, media upload, articles) act as that account. Takes the x.com session cookies auth_token and ct0 (copied from a logged-in browser), plus an optional user_agent and residential proxy_url. The cookies are stored server-side against the key and are not returned. Returns ok, the resolved username, and whether the session validated live. A username/password login is the alternative to raw cookies. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account-session/customer-session

Reads back the X account session registered against this API key, without changing it. Returns registered (false if none was registered), the resolved username and twitter_user_id the session maps to, status ('ok', or 'dead' once X has rejected the cookies), created_at, updated_at, last_used_at, and an egress block: source (one of session, sticky_residential, pool_residential, direct), customer_proxy_in_use (true when the registered proxy_url is the one writes leave from), and a note explaining that tier. It does not return auth_token, ct0, or any proxy URL. Answers 'which account am I posting as', 'has my session expired', and 'is the proxy I supplied being used'. Scoped to the calling API key by construction: it takes no account identifier of any kind, so it cannot read another key's session. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account-session/customer-session-status

Takes no parameters.

Revokes the X account session registered against this API key, deleting the stored auth_token and ct0 from twitterapis.com. Self-serve, with no ticket and no human in the loop. Scoped to the calling API key by construction: it takes no account identifier of any kind, so it cannot reach another key's session. Idempotent and free: revoking twice, or revoking when nothing was stored, returns ok with deleted=false, and it costs no credits, so a key that is out of balance can still delete its credentials. Afterwards the authenticated-account reads and the write actions stop acting as that account until a session is registered again. This deletes the stored copy only: it does not log the account out of x.com, and the cookies themselves stay valid until the session is revoked in the X account settings. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/account-session/customer-session-delete

Takes no parameters.

Logs in to X with a username and password (plus totp_secret if the account has 2FA) and stores the resulting session against the API key, so the authenticated-account reads and the write actions then act as that account. On success returns { ok, username, message }; it does not return the session cookies (auth_token/ct0 are minted and kept server-side, not sent back). Typical failures: bad_credentials (401), two_factor_required (400, needs totp_secret), captcha_required (422), acid_challenge (409, the login has to be confirmed from the account before a retry). Handles real account credentials. Cost: $0.0100 per call. Docs: https://docs.twitterapis.com/docs/reference/account-session/user-user-login

Uploads an image to X and returns a media_id for a tweet's media_ids. Takes media_data as base64-encoded image bytes. Acts as the X session registered against the API key. Per-call auth_token and ct0 are also accepted. Returns ok and the media_id. Only base64 image data is supported over this JSON transport. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/media-upload

Reports whether an uploaded media_id has finished processing on X. The media upload accepts base64-encoded images only, not video or GIF, and an image has no processing step on X: its media_id is usable in a tweet as soon as the upload returns, with no status check needed. The state fields matter only for media X processes asynchronously, where a tweet attaching the id fails until X reports state 'succeeded'. Returns media_id, state ('pending', 'in_progress', 'succeeded' or 'failed'), check_after_secs (how long X asks to wait before the next status check), progress_percent, and an error object when state is 'failed'. Reads through the registered X session, the same one that performed the upload. Per-call auth_token and ct0 are also accepted. A READ: no daily write cap applies. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/write-actions/media-status

Starts a new DRAFT article ('Note') as the authenticated account. No input required. Returns the new article's entity id and its full article object. Requires an authenticated X session with write capability behind the API key. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-create

Attaches an ALREADY-UPLOADED image as the cover of a DRAFT article, as the authenticated account. This does not upload: media_id is the id a prior media upload returned. Takes the article's entity id. Edits are verified on drafts only. When X refuses an edit and the article is among the first 100 PUBLISHED articles X lists for the account, the call answers 422 article_published and is not billed; the detail names a path that avoids a published-article edit (unpublish, edit the draft, publish again). That round trip is not verified end to end, so it suits only an article that can stay unpublished if republishing fails. Requires an authenticated X session with write capability behind the API key. Returns the updated article object with cover_media populated. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-update-cover-media

Sets or replaces the title of a DRAFT article as the authenticated account. Takes the article's entity id and the new title. Edits are verified on drafts only. When X refuses an edit and the article is among the first 100 PUBLISHED articles X lists for the account, the call answers 422 article_published and is not billed; the detail names a path that avoids a published-article edit (unpublish, edit the draft, publish again). That round trip is not verified end to end, so it suits only an article that can stay unpublished if republishing fails. Requires an authenticated X session with write capability behind the API key. Returns the updated article object. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-update-title

Replaces the body content of a DRAFT article as the authenticated account. Edits are verified on drafts only. When X refuses an edit and the article is among the first 100 PUBLISHED articles X lists for the account, the call answers 422 article_published and is not billed; the detail names a path that avoids a published-article edit (unpublish, edit the draft, publish again). That round trip is not verified end to end, so it suits only an article that can stay unpublished if republishing fails. Takes the article's entity id and content_state: Draft.js JSON ({ blocks: [...], entityMap: [...] }) built by the caller; blocks are forwarded with only the data, text, key, type, entityRanges and inlineStyleRanges fields (X rejects any other block field, depth included). Block types X accepts: unstyled, header-two, unordered-list-item, ordered-list-item, blockquote, atomic (a one-space block carrying an entity via entityRanges [{key, offset: 0, length: 1}]); inline styles Bold and Italic. Entity data is snake_case on INPUT and X returns it camelCase: TWEET (an embedded post) {tweet_id}; MEDIA (an inline image) {caption, entity_key, media_items: [{local_media_id, media_category: 'DraftTweetImage', media_id}]} with media_id from a prior media upload; DIVIDER {}; LINK {url} (a Mutable entity over a text range, not atomic); MARKDOWN {markdown} (tables). A wrong field is refused by X's schema and the call answers 422 with reason validation_failed and the offending path in detail. Requires an authenticated X session with write capability behind the API key. Returns the updated article object (content_state echoed camelCase, media_entities populated for MEDIA). Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-update-content

Publishes a DRAFT article as the authenticated account, transitioning it to Published and posting a REAL, PUBLIC announcement tweet that followers and anyone with the link can see. A consequential, hard-to-fully-undo action, unlike saving a draft: unpublishing reverts the article to Draft but LEAVES the announcement tweet up, and only deleting a published article both unpublishes it and removes the announcement tweet, by which time the content was public for however long it stayed up. Takes the article's entity id; audience accepts only 'Everyone' (or 'Public') and reply_control only 'Everyone', both the default when omitted, and any other value is refused with a 400; caption is optional text that becomes the announcement post's text. Requires an authenticated X session with write capability behind the API key. Returns the updated (Published) article object. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-publish

Reverts a PUBLISHED article back to Draft as the authenticated account. The announcement tweet the publish posted is LEFT IN PLACE and stays publicly visible; deleting the article is what removes that tweet. X refuses this with an 'invalid_lifecycle' error if the article is not currently Published. Requires an authenticated X session with write capability behind the API key. Returns the updated (Draft) article object. Cost: $0.0016 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-unpublish

Returns an article's full content (title, content_state, cover media, author, timestamps, public_url). Two mutually exclusive forms. PUBLIC: id or url of the article's announcement tweet; no registered session or per-call credentials needed, only the API key; PUBLISHED articles only. OWNER-ONLY: article_id (the article's own entity id); requires an authenticated session, and also reaches the account's own Drafts, which have no announcement tweet the public form could resolve. Returns 404 (article null) if not found, not visible, or (article_id form) not owned by the calling account. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-get

Lists the authenticated account's own articles (drafts or published), most recent first. X exposes no combined view, so each call covers ONE lifecycle: lifecycle='published' lists published articles; omitted (or 'draft') lists drafts. Requires an authenticated X session behind the API key. Returns count, next_cursor (the cursor for the next page; null or absent means no more pages), and the page of article objects. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-list

Deletes an article as the authenticated account. A DRAFT is hard-deleted outright; a PUBLISHED article is unpublished first and then its announcement tweet is deleted too, so this fully removes a published article's public footprint, unlike unpublishing, which leaves the tweet up. Irreversible. lifecycle and tweet_id are optional fast-path hints from a prior create or list response: when omitted, the server resolves the lifecycle itself by scanning the account's own Draft then Published articles, which costs an extra round trip. Requires an authenticated X session with write capability behind the API key. Returns ok/deleted and the id targeted. Cost: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/articles/article-delete

Starts watching an X account for new posts. Every new post from that handle is HMAC-signed and delivered to the account's registered webhook(s) on a shared poll interval. Monitor creation is account administration, not a metered read. Returns the new monitor's id, plus its normalized handle, status, and poll_interval_ms. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/monitor-post

List every monitor on your account: id, subject (its from:<handle> query), kind, status ('active' or 'paused'), degraded flag, events_possibly_missed, webhook_ids restriction, and created_at. Takes no arguments. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/monitor-get

Takes no parameters.

Partially updates an existing monitor: pause or resume it via status, change which webhooks receive its events via webhook_ids, change or clear its domain_filter, or any combination in the same call (applied atomically). Resuming a paused monitor re-runs the same capacity and per-account cap checks as creating a new one, since it adds load back to monitoring capacity. All fields are optional; an omitted field stays unchanged. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/monitor-id-post

Stops and removes a monitor by id. Irreversible: watching that handle again takes a new monitor. Delivery history referencing this monitor is retained, not cascade-deleted. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/monitor-id-delete

Returns one monitor's current status, degradation flag, poll interval, possibly-missed-event count, and cursor position (last_tweet_id, last_poll_at), for a health dashboard. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/monitor-id-health

Account-wide monitoring rollup in ONE call, with no monitor id: service status ('operational' or 'degraded'), active/paused/total counts across every monitor on the account, and pending/delivered/failed delivery counts from the last 24 hours. Takes no arguments. A key with zero monitors gets zeroed counts back, not an error. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/monitor-health

Takes no parameters.

Lists the most recent monitor delivery events across every monitor, most recent first: id, monitor_id, tweet_id, status, tweet_created_at, and the real measured latency (detected_lag_ms, from X's own post timestamp to enqueue; delivery_lag_ms, the separate queue-to-webhook-POST time; total_lag_ms). Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/monitor-deliveries

Compatibility endpoint with an x_user_stream-shaped request/response envelope: watches an X account for new posts, translated onto the same underlying monitor system. It exists for migrating an existing x_user_stream-shaped integration without a rewrite. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/oapi-x-user-stream-add-user-to-monitor-tweet

Compatibility endpoint with an x_user_stream-shaped envelope: stops watching an account. Irreversible. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/oapi-x-user-stream-remove-user-to-monitor-tweet

Compatibility endpoint with an x_user_stream-shaped envelope: lists every account currently tweet-monitored. Field mapping, not fabricated: x_user_id is null (this API stores no numeric Twitter user id) and is_monitor_profile is 0 (profile-change monitoring is not a capability this API has). Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/oapi-x-user-stream-get-user-to-monitor-tweet

Takes no parameters.

Registers an HTTPS endpoint to receive signed monitor events. The HMAC signing secret is returned ONLY in this response and cannot be retrieved again; it verifies the X-TwitterAPIs-Signature header on every delivery. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/webhook-post

Lists every webhook registered on the account: id, url, status ('active' delivers, 'disabled' means the endpoint returned a 410 Gone and needs re-registering to reactivate), and created_at. The signing secret is not returned here; it is returned at creation alone. Takes no arguments. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/webhook-get

Takes no parameters.

Soft-deletes a webhook by id: it stops receiving deliveries immediately and disappears from the webhook list, but delivery history referencing it is retained rather than cascade-deleted. Irreversible from the caller's side; resuming delivery takes a newly registered webhook. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/webhook-id

Sends one HMAC-signed test event to this webhook's URL right now and returns the outcome synchronously: delivered (true if the endpoint returned a 2xx within the delivery timeout), status_code, and error. Unlike a real monitor event, a test send is not queued, retried, or dead-lettered: it is a one-shot diagnostic of the endpoint and its signature verification. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/webhook-id-test

Replays deliveries that dead-lettered while the endpoint was down. A delivery is dead-lettered after it fails all 8 attempts across 21 minutes, so an outage longer than that window loses those events; this re-queues them with a full retry budget, oldest first. Bounded by default so a recovered endpoint is not flooded: max_age_hours defaults to 24 and limit to 100. Returns requeued and skipped_permanent. A delivery that died for a permanent reason (a 410 Gone, a deleted webhook, or a URL egress refused) is not replayed, because it would fail the same way and spend the budget again. Replayed events carry the same signature and payload as the original, so a receiver idempotent on the event id sees no duplicate effect. Returns 409 if the webhook is disabled, which happens after the endpoint answers 410 Gone; a disabled webhook has to be re-registered. Cost: Free per call. Docs: https://docs.twitterapis.com/docs/reference/monitoring/webhook-id-redrive