TwitterAPIs

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

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

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

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

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 relati…

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

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. r…

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 …

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 ope…

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…

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/comm…

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

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 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 ca…

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

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 lis…

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. …

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 u…

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…

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

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

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

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

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

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

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

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 cle…

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

Returns the status of a feedback report this account sent earlier, by its server id: 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

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 …

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

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

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, n…

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: $0.0008 per call. Docs: https://docs.twitterapis.com/docs/reference/grok/grok-config

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

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 ma…

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

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

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

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-r…

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

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

Reports whether an uploaded media_id has finished processing on X. Video, GIF and large uploads are processed ASYNCHRONOUSLY: the upload returns a media_id immediately, but a tweet attaching it 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…

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

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

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

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

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

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

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

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

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

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

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

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 eve…

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

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

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

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.twi…

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 …

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.000…

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 retur…

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 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

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, pro…

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: http…

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

Returns all tweets in a thread: the connected chain of tweets posted by the SAME author in sequence (a tweetstorm or numbered thread). Any tweet id or url from the thread returns the full ordered sequence in a single call. 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

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

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

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

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

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:…

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 evid…

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 aut…

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 ap…

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

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 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 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 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

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

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

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.…

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

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

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…

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 ho…

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

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: 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

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